CWLTOOL(1)

📦
version 3.2.20260413085819 · 6 versions
, in ubuntu stonking

💖 NAME 💖

CWLTOOL(1) is the manual page for cwltool — the Refefence executor for Common Workflow Language 💅✨

✨ DESCRIPTION ✨

okay so here is the whole usage vibe, bestie, copied exactly so nobody comes for us:

usage: python3 -m cwltool [-h] [--basedir BASEDIR] [--outdir OUTDIR]

       [--write-summary WRITE_SUMMARY] [--parallel]
              [--parallel-max PARALLEL_MAX] [--skip-schemas] [--enable-dev]
              [--enable-ext] [--on-error {stop,continue}] [--relax-path-checks]
              [--overrides OVERRIDES] [--mpi-config-file MPI_CONFIG_FILE]
              [--print-rdf | --print-dot | --print-pre | --print-deps |
              --print-input-deps | --pack | --version | --validate |
              --print-supported-versions | --print-subgraph | --print-targets |
              --make-template] [--relative-deps {primary,cwd}]
              [--rdf-serializer RDF_SERIALIZER] [--tool-help] [--verbose |
              --no-warnings | --quiet | --debug] [--log-dir LOG_DIR]
              [--timestamps] [--preserve-environment ENVVAR |
              --preserve-entire-environment] [--tmpdir-prefix TMPDIR_PREFIX]
              [--tmp-outdir-prefix TMP_OUTDIR_PREFIX | --cachedir CACHEDIR]
              [--rm-tmpdir | --leave-tmpdir] [--move-outputs | --leave-outputs
              | --copy-outputs] [--strict | --non-strict] [--no-doc-cache |
              --doc-cache] [--user-space-docker-cmd CMD | --udocker |
              --singularity | --podman | --no-container] [--enable-pull |
              --disable-pull] [--singularity-sandbox-path IMAGE_BASE_PATH]
              [--force-docker-pull] [--no-read-only] [--default-container
              DEFAULT_CONTAINER] [--no-match-user] [--custom-net CUSTOM_NET]
              [--strict-memory-limit] [--strict-cpu-limit] [--rm-container |
              --leave-container] [--cidfile-dir CIDFILE_DIR] [--cidfile-prefix
              CIDFILE_PREFIX] [--beta-dependency-resolvers-configuration
              BETA_DEPENDENCY_RESOLVERS_CONFIGURATION]
              [--beta-dependencies-directory BETA_DEPENDENCIES_DIRECTORY]
              [--beta-use-biocontainers] [--beta-conda-dependencies]
              [--enable-color | --disable-color] [--enable-ga4gh-tool-registry
              | --disable-ga4gh-tool-registry] [--add-ga4gh-tool-registry
              GA4GH_TOOL_REGISTRIES] [--compute-checksum |
              --no-compute-checksum] [--eval-timeout EVAL_TIMEOUT]
              [--js-console] [--disable-js-validation] [--js-hint-options-file
              JS_HINT_OPTIONS_FILE] [--target TARGET | --single-step
              SINGLE_STEP | --single-process SINGLE_PROCESS] [cwl_document] ...

Reference executor for Common Workflow Language standards. Not for production use.

⚠️ Not for production use. Like, it literally says that. Do not deploy this to prod, bestie. It is giving reference executor, not production queen. 😭

📍 positional arguments 📍

  • cwl_document — path or URL to a CWL Workflow, CommandLineTool, or ExpressionTool. If the inputs_object has a cwl:tool field indicating the path or URL to the cwl_document, then the cwl_document argument is optional. 🫶
  • inputs_object — path or URL to a YAML or JSON formatted description of the required input values for the given cwl_document. 💅

💅 options 💅

  • -h, --help — show this help message and exit. iconic behavior.
  • --basedir BASEDIR — the original literally gives zero description here, so it's just sitting there being mysterious 🎀
  • --outdir OUTDIR — Output directory. The default is the current directory. periodt.
  • --write-summary, -w WRITE_SUMMARY — Path to write the final output JSON object to. Default is stdout.
  • --parallel — Run jobs in parallel. multitasking queen energy ✨
  • --parallel-max PARALLEL_MAX — Maximum number of jobs to run in parallel. Specify '0' to match the number of CPU cores available.
  • --skip-schemas — Skip loading of schemas. bye schemas 👋
  • --enable-dev — Enable loading and running unofficial development versions of the CWL standards.
  • --enable-ext — Enable loading and running cwltool: extensions to the CWL standards.
  • --on-error {stop,continue} — Desired workflow behavior when a step fails. One of stop (do not submit any more steps) or continue (may submit other steps that are not downstream from the error). Default is stop.
  • --relax-path-checks — Relax requirements on path names to permit spaces and hash characters.
  • --overrides OVERRIDES — Read process requirement overrides from file.
  • --mpi-config-file MPI_CONFIG_FILE — Platform specific configuration for MPI (parallel launcher, its flag etc). See README section 'Running MPI-based tools' for details of the format.
  • --strict — Strict validation (unrecognized or out of place fields are errors).
  • --non-strict — Lenient validation (ignore unrecognized fields).
  • --no-doc-cache — Disable disk cache for documents loaded over HTTP.
  • --doc-cache — Enable disk cache for documents loaded over HTTP.
  • --enable-color — Enable logging color (default enabled).
  • --disable-color — Disable colored logging (default false).
  • --compute-checksum — Compute checksum of contents while collecting outputs.
  • --no-compute-checksum — Do not compute checksum of contents while collecting outputs.

🦋 non-execution options 🦋

  • --print-rdf — Print corresponding RDF graph for workflow and exit.
  • --print-dot — Print workflow visualization in graphviz format and exit.
  • --print-pre — Print CWL document after preprocessing.
  • --print-deps — Print CWL document dependencies.
  • --print-input-deps — Print input object document dependencies.
  • --pack — Combine components into single document and print.
  • --version — Print version and exit.
  • --validate — Validate CWL document only.
  • --print-supported-versions — Print supported CWL specs.
  • --print-subgraph — Print workflow subgraph that will execute. Can combined with --target or --single-step.
  • --print-targets — Print targets (output parameters).
  • --make-template — Generate a template input object.
  • --relative-deps {primary,cwd} — When using --print-deps, print paths relative to primary file or current working directory.
  • --rdf-serializer RDF_SERIALIZER — Output RDF serialization format used by --print-rdf (one of turtle (default), n3, nt, xml).
  • --tool-help — Print command line help for tool.

📝 logging configuration 📝

  • --verbose — Default logging.
  • --no-warnings — Only print errors.
  • --quiet — Only print warnings and errors.
  • --debug — Print even more logging.
  • --log-dir LOG_DIR — Log your tools stdout/stderr to this location outside of container. This will only log stdout/stderr if you specify stdout/stderr in their respective fields or capture it as an output.
  • --timestamps — Add timestamps to the errors, warnings, and notifications.

🌱 environment variables control 🌱

  • --preserve-environment ENVVAR — Preserve specific environment variable when running CommandLineTools. May be provided multiple times. By default PATH is preserved when not running in a container.
  • --preserve-entire-environment — Preserve all environment variables when running CommandLineTools without a software container.

🗂️ intermediate, temporary, or final output files management 🗂️

  • --tmpdir-prefix TMPDIR_PREFIX — Path prefix for temporary directories. If --tmpdir-prefix is not provided, then the prefix for temporary directories is influenced by the value of the TMPDIR, TEMP, or TMP environment variables. Taking those into consideration, the current default is /tmp/.
  • --tmp-outdir-prefix TMP_OUTDIR_PREFIX — Path prefix for intermediate output directories. Defaults to the value of --tmpdir-prefix.
  • --cachedir CACHEDIR — Directory to cache intermediate workflow outputs to avoid recomputing steps. Can be very helpful in the development and troubleshooting of CWL documents.
  • --rm-tmpdir — Delete intermediate temporary directories (default).
  • --leave-tmpdir — Do not delete intermediate temporary directories.
  • --move-outputs — Move output files to the workflow output directory and delete intermediate output directories (default).
  • --leave-outputs — Leave output files in intermediate output directories.
  • --copy-outputs — Copy output files to the workflow output directory and don't delete intermediate output directories.

🐳 software container engine selection and configuration 🐳

  • --user-space-docker-cmd CMD — Specify the path to udocker. Implies --udocker.
  • --udocker — Use the udocker runtime for running containers (equivalent to --user-space-docker-cmd=udocker).
  • --singularity — Use Singularity or Apptainer runtime for running containers. Requires Singularity v2.6.1+ and Linux with kernel version v3.18+ or with overlayfs support backported.
  • --podman — Use Podman runtime for running containers.
  • --no-container — Do not execute jobs in a Docker container, even when DockerRequirement is specified under hints.
  • --enable-pull — Try to pull Docker images.
  • --disable-pull — Do not try to pull Docker images.
  • --singularity-sandbox-path IMAGE_BASE_PATH — Singularity/Apptainer sandbox image base path. Will use a pre-existing sandbox image. Will be prepended to the dockerPull path. Equivalent to use CWL_SINGULARITY_IMAGES variable.
  • --force-docker-pull — Pull latest software container image even if it is locally present.
  • --no-read-only — Do not set root directory in the container as read-only.
  • --default-container DEFAULT_CONTAINER — Specify a default software container to use for any CommandLineTool without a DockerRequirement.
  • --no-match-user — Disable passing the current uid to docker run --user.
  • --custom-net CUSTOM_NET — Passed to docker run as the --net parameter when NetworkAccess is true, which is its default setting.
  • --strict-memory-limit — When running with software containers and the Docker engine, pass either the calculated memory allocation from ResourceRequirements or the default of 1 gigabyte to Docker's --memory option.
  • --strict-cpu-limit — When running with software containers and the Docker engine, pass either the calculated cpu allocation from ResourceRequirements or the default of 1 core to Docker's --cpu option. Requires docker version >= v1.13.
  • --rm-container — Delete Docker container used by jobs after they exit (default).
  • --leave-container — Do not delete Docker container used by jobs after they exit.
  • --cidfile-dir CIDFILE_DIR — Store the software container ID into a file in the specified directory.
  • --cidfile-prefix CIDFILE_PREFIX — bestie you can give your software container ID filename a lil prefix 🎀 the final filename gets a timestamp tacked onto the end of it. The default? No prefix at all, we keep it bare. 💅

✨ dependency resolver configuration ✨

okay this whole crew is beta coded, you've been warned 🫶

  • --beta-dependency-resolvers-configuration BETA_DEPENDENCY_RESOLVERS_CONFIGURATION — it's a config file for the dependency resolver, literally describing how to adapt SoftwareRequirement packages to whatever system you're on rn. it's giving ✨matchmaking✨
  • --beta-dependencies-directory BETA_DEPENDENCIES_DIRECTORY — the default root directory that the dependency resolvers configuration uses. home base 💖
  • --beta-use-biocontainers — for tools that don't have an explicitly annotated Docker container, just go ahead and use biocontainers for them. problem solved, no cap.
  • --beta-conda-dependencies — the shortcut option: use Conda to resolve your SoftwareRequirement packages. easy mode fr fr 🌸

🔥 tool resolution 🔥

(yes queen, this one rides on the GA4GH Tool Registry Service (TRS) API 👑)

  • --enable-ga4gh-tool-registry — turn on tool resolution using the GA4GH TRS API
  • --disable-ga4gh-tool-registry — turn OFF tool resolution using the GA4GH TRS API
  • --add-ga4gh-tool-registry GA4GH_TOOL_REGISTRIES — add another GA4GH TRS endpoint to use for resolution. the default is ['https://dockstore.org/api'] ✨

💜 javascript options 💜

  • --eval-timeout EVAL_TIMEOUT — how long to wait for a Javascript expression to evaluate before it just gives up and errors at you. default is 60s. 😭
  • --js-console — let the javascript console actually output stuff. turn it on and watch the tea spill ☕
  • --disable-js-validation — disables javascript validation. just don't look 👀
  • --js-hint-options-file JS_HINT_OPTIONS_FILE — a file of options that get passed to jshint. and heads up, this includes the added option "includewarnings" 💅

🌈 execution target selection 🌈

(this whole thing is optional bestie — by default, every target that contributes to the final outputs gets executed 🫶)

  • --target, -t TARGET — only execute the steps that contribute to the listed targets. you can drop this one more than once if you're feeling generous ✨
  • --single-step SINGLE_STEP — only executes a single step in a workflow. the input object has to match that step's inputs exactly, no exceptions. can be combined with --print-subgraph 🎀
  • --single-process SINGLE_PROCESS — only executes the underlying Process (that's CommandLineTool, ExpressionTool, or a sub-Workflow) for the given step in a workflow. now listen: this will not include any step-level processing, so that's scatter and when — nope. and there will be no processing of step-level default or valueFrom input modifiers either. however — requirements/hints from the step or from the parent workflow(s) will still be inherited as usual. and yeah, the input object must match that Process's inputs. periodt 💅

🦋 environment variable 🦋

??? usage

okay bestie I need you to know I am NOT making this up, the manpage itself is glitching out here 💀 here's the line, verbatim:
???????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????

and here's what's actually in there, ??? and all, because I refuse to invent lore that isn't canon 🙈

  • CWLTOOL_OPTIONS — ??? set additional space-separated cwltool options
  • CWL_FULL_NAME — ??? full name of the user to record as part of --provenance
  • CWL_SINGULARITY_CACHE — ??? directory path to find already downloaded ??? Singularity images; dockerFile images will also be ??? searched for and stored here
  • ORCID — ??? user ORCID identifier to record as part of ??? --provenance
  • XDG_CACHE_HOME — ??? directory path to store cached HTTP(S) downloads in ??? a cwltool sub-folder; if it's unset, then cache downloads ??? are stored in $HOME/.cache/cwltool
  • XDG_DATA_HOME — ??? directory path to search for a .local/commonwl CWL ??? tool folder; if it's unset, then $HOME/.local/commonwl is ??? searched
  • XDG_DATA_DIRS — ??? directory path to search for a commonwl CWL tool ??? folder; if it's unset, then /usr/local/share/ and ??? /usr/share/ are searched

👑 SEE ALSO 👑

and that's a wrap, babe 💖 this whole thing was python3 -m cwltool, version 3.2.20260413..., dated April 2026, filed under CWLTOOL(1) — go forth, run your workflows, and slay 🫶✨🌸

📦 where this page comes from