cwl-utils

Python Utilities and Autogenerated Classes for loading and parsing CWL v1.0, CWL v1.1, and CWL v1.2 documents.

Requires Python 3.8+

Installation

pip3 install cwl-utils

To install from source:

git clone https://github.com/common-workflow-language/cwl-utils.git
cd cwl-utils
pip3 install .

Usage

Pull the all referenced software container images

cwl-docker-extract is useful to cache or pre-pull all software container images referenced in a CWL CommandLineTool or CWL Workflow (including all referenced CommandLineTools and sub-Workflows and so on).

The default behaviour is to use the Docker engine to download and save the software container images in Docker format.

cwl-docker-extract path_to_my_workflow.cwl

cwl-docker-extract --dir DIRECTORY path_to_my_workflow.cwl

Or you can use the Singularity software container engine to download and save the software container images and convert them to the Singularity format at the same time.

cwl-docker-extract --singularity --dir DIRECTORY path_to_my_workflow.cwl

Print all referenced software packages

cwl-cite-extract prints all software packages found (recursively) in the specified CWL document.

Currently the package name and any listed specs and version field are printed for all SoftwareRequirement s found.

cwl-cite-extract path_to_my_workflow.cwl

Replace CWL Expressions with concrete steps

cwl-expression-refactor refactors CWL documents so that any CWL Expression evaluations are separate steps (either CWL ExpressionTools or CWL CommandLineTools.) This allows execution by CWL engines that do not want to support inline expression evaluation outside of concrete steps, or do not want to directly support CWL’s optional InlineJavascriptRequirement at all.

cwl-expression-refactor directory/path/to/save/outputs path_to_my_workflow.cwl [more_workflows.cwl]

Split a packed CWL document

cwl-graph-split splits a packed CWL document file into multiple files.

Packed CWL documents use the $graph construct to contain multiple CWL Process objects (Workflow, CommandLineTool, ExpressionTool, Operation). Typically packed CWL documents contain a CWL Workflow under the name “main” and the workflow steps (including any sub-workflows).

cwl-graph-split --outdir optional/directory/path/to/save/outputs path_to_my_workflow.cwl

Pack a CWL document

cwl-pack packs a CWL document and all of its referenced documents into a single JSON document. Unlike cwl-normalizer, cwl-pack does not upgrade the CWL version and does not refactor expressions; it is a thin CLI wrapper around cwl_utils.pack.pack().

cwl-pack path_to_my_workflow.cwl
cwl-pack --outfile packed.json path_to_my_workflow.cwl

Normalize a CWL document

cwl-normalizer normalizes one or more CWL document so that for each document, a JSON format CWL document is produces with it and all of its dependencies packed together, upgrading to CWL v1.2, as needed. Can optionally refactor CWL Expressions into separate steps in the manner of cwl-expression-refactor.

cwl-normalizer directory/path/to/save/outputs path_to_my_workflow.cwl [more_workflows.cwl]

Generate for Workflow Parameters from a CWL document

cwl-inputs-schema-gen generates a JSON Schema for workflow input parameters from a CWL document.

cwl-inputs-schema-gen path_to_my_workflow.cwl

Using the CWL Parsers

from pathlib import Path
from ruamel import yaml
import sys

from cwl_utils.parser import load_document_by_uri, save

# File Input - This is the only thing you will need to adjust or take in as an input to your function:
cwl_file = Path("testdata/md5sum.cwl")  # or a plain string works as well

# Import CWL Object
cwl_obj = load_document_by_uri(cwl_file)

# View CWL Object
print("List of object attributes:\n{}".format("\n".join(map(str, dir(cwl_obj)))))

# Export CWL Object into a built-in typed object
saved_obj = save(cwl_obj)
print(f"Export of the loaded CWL object: {saved_obj}.")

Development

Regenerate parsers

To regenerate install the schema_salad package and run:

cwl_utils/parser/cwl_v1_0.py was created via schema-salad-tool --codegen python https://github.com/common-workflow-language/common-workflow-language/raw/codegen/v1.0/extensions.yml --codegen-parser-info "org.w3id.cwl.v1_0" > cwl_utils/parser/cwl_v1_0.py

cwl_utils/parser/cwl_v1_1.py was created via schema-salad-tool --codegen python https://github.com/common-workflow-language/cwl-v1.1/raw/codegen/extensions.yml --codegen-parser-info "org.w3id.cwl.v1_1" > cwl_utils/parser/cwl_v1_1.py

cwl_utils/parser/cwl_v1_2.py was created via schema-salad-tool --codegen python https://github.com/common-workflow-language/cwl-v1.2/raw/codegen/extensions.yml --codegen-parser-info "org.w3id.cwl.v1_2" > cwl_utils/parser/cwl_v1_2.py

Release

To release CWLUtils, bump the version in src/cwl_utils/__meta__.py, and tag that commit with the new version. The gh-action-pypi-publish should release that tag.

Metadata

Release files for cwl-utils 0.44

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cwl-utils 0.44
File	Size	Uploaded
cwl_utils-0.44.tar.gz	384.2 kB	Sep 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cwl-utils 0.44
File	Interpreter	ABI	Platform	Reset
cwl_utils-0.44-py3-none-any.whl 444.6 kB Sep 16, 2026	Python 3	none	any	Details

Total release size: 828.8 kB

Release files / cwl_utils-0.44.tar.gz

Download URL	cwl_utils-0.44.tar.gz
Size	384.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`dad3c6a0ed55d6661fa7841713489555a1be6429396a2362b12fe6423c90da0c`
BLAKE2b-256 checksum How to use checksums	`d4c945fcb39e23e37c00b4e596dc940a60fe9073fe456f14e98f15e0044ed166`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/common-workflow-language/cwl-utils
Publishing commit: github.com/common-workflow-language/cwl-utils/tree/f6e84157d948ea53a32f1dc22b93ece1a86b0ec4

Workflow

Publishing configuration: github.com/common-workflow-language/cwl-utils/blob/f6e84157d948ea53a32f1dc22b93ece1a86b0ec4/.github/workflows/tag_to_publish.yml
Publishing logs: github.com/common-workflow-language/cwl-utils/actions/runs/35078357734/attempts/1

Artifact

Subject: cwl_utils-0.44.tar.gz
SHA-256 checksum: dad3c6a0ed55d6661fa7841713489555a1be6429396a2362b12fe6423c90da0c Verifying attestations

Release files / cwl_utils-0.44-py3-none-any.whl

Download URL	cwl_utils-0.44-py3-none-any.whl
Size	444.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`523d58a6687b09d7a5d95d03933717b87e06ba671f71f0da3939dbfb5fbd2d87`
BLAKE2b-256 checksum How to use checksums	`7bc4fe1aa245e053e0090b1dc9bfd744d5057ef85ff9ac852ada7b7b5849593b`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/common-workflow-language/cwl-utils
Publishing commit: github.com/common-workflow-language/cwl-utils/tree/f6e84157d948ea53a32f1dc22b93ece1a86b0ec4

Workflow

Publishing configuration: github.com/common-workflow-language/cwl-utils/blob/f6e84157d948ea53a32f1dc22b93ece1a86b0ec4/.github/workflows/tag_to_publish.yml
Publishing logs: github.com/common-workflow-language/cwl-utils/actions/runs/35078357734/attempts/1

Artifact

Subject: cwl_utils-0.44-py3-none-any.whl
SHA-256 checksum: 523d58a6687b09d7a5d95d03933717b87e06ba671f71f0da3939dbfb5fbd2d87 Verifying attestations