# cwltool Command Line Options

## cwltool

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

    usage: 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]
                   [--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] ...

### environment variables

CWLTOOL_OPTIONS

  set additional space-separated `cwltool` options

CWL_FULL_NAME

  full name of 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 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 unset, then `$HOME/.local/commonwl` is searched

XDG_DATA_DIRS

  directory path to search for a `commonwl` CWL tool folder; if unset, then `/usr/local/share/` and `/usr/share/` are searched

### 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

--basedir <basedir>

--outdir <outdir>

  Output directory. The default is the current directory.

--write-summary <write_summary>, -w <write_summary>

  Path to write the final output JSON object to. Default is stdout.

--parallel

  Run jobs in parallel.

--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

--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>

  Specify a prefix to the software container ID filename. Final file name will be followed by a timestamp. The default is no prefix.

### tool resolution

(using the GA4GH Tool Registry Service (TRS) API)

--enable-ga4gh-tool-registry

  Enable tool resolution using GA4GH TRS API

--disable-ga4gh-tool-registry

  Disable tool resolution using GA4GH TRS API

--add-ga4gh-tool-registry <ga4gh_tool_registries>

  Add a GA4GH TRS endpoint to use for resolution, default [’https://dockstore.org/api’]

### javascript options

--eval-timeout <eval_timeout>

  Time to wait for a Javascript expression to evaluate before giving an error, default 60s.

--js-console

  Enable javascript console output

--disable-js-validation

  Disable javascript validation.

--js-hint-options-file <js_hint_options_file>

  File of options to pass to jshint. This includes the added option “includewarnings”.

### execution target selection

(optional, by default all target contributing to final outputs are executed)

--target <target>, -t <target>

  Only execute steps that contribute to listed targets (can be provided more than once).

--single-step <single_step>

  Only executes a single step in a workflow. The input object must match that step’s inputs. Can be combined with –print-subgraph.

--single-process <single_process>

  Only executes the underlying Process (CommandLineTool, ExpressionTool, or sub-Workflow) for the given step in a workflow. This will not include any step-level processing: scatter, when; and there will be no processing of step-level default, or valueFrom input modifiers. However, requirements/hints from the step or parent workflow(s) will be inherited as usual.The input object must match that Process’s inputs.