CWL Upgrader

1.2.15 · active · verified Thu Apr 16

cwl-upgrader is a Python library and command-line tool designed to upgrade Common Workflow Language (CWL) documents. It supports upgrading CWL tools and workflows from older versions (draft-3, v1.0, v1.1) to the current v1.2 specification. The library focuses solely on syntax migration and does not perform validation of the document's correctness. It is actively maintained with frequent patch releases, often driven by dependency updates and Python version support.

Common errors

```
cwl-upgrader: command not found
```
cause The `cwl-upgrader` executable is not in your system's PATH, or the installation failed, or the Python environment is not active.

fix Ensure Python's script directory is in your PATH. If using a virtual environment, activate it (`source venv/bin/activate`). Reinstall with `pip install cwl-upgrader` to check for installation errors.
```
Error: 'cwlVersion' must be one of 'v1.0', 'v1.1', 'v1.2'
```
cause The input CWL document specifies a `cwlVersion` that `cwl-upgrader` does not recognize as an upgradable source (e.g., already v1.2, or an unknown future version).

fix Verify the `cwlVersion` field in your input document. `cwl-upgrader` supports upgrading from draft-3, v1.0, and v1.1 to v1.2. If the document is already v1.2 or an unsupported version, no upgrade is necessary or possible with this tool.
```
ERROR Workflow error, try again with --debug for more information: createfile.cwl:18:5: Name '/scripts/myscript.sh' at index 0 of listing is invalid, paths starting with '/' only permitted in CWL 1.2 and later.
```
cause This error typically occurs when a CWL document, even after upgrading to v1.2, uses features (like absolute paths in `InitialWorkDirRequirement`) that were not valid in previous versions and still cause issues with the CWL runner (like `cwltool`), or the document has not been correctly updated/validated.

fix This is a post-upgrade validation error. Examine the specific line indicated in the error message. If using absolute paths in `InitialWorkDirRequirement`, ensure your target CWL `cwlVersion` is indeed `v1.2` and that the CWL runner you are using fully supports CWL v1.2 features. Consider adjusting paths to be relative if possible, or consult the CWL v1.2 specification for correct usage of such features.

Warnings

breaking Support for older Python versions has been progressively dropped. Ensure your environment uses Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10, 3.11, 3.12, 3.13, or 3.14.
gotcha cwl-upgrader performs syntax upgrades but does not validate the semantic correctness of the CWL document. Always validate your upgraded documents using a CWL reference implementation like `cwltool --validate` after upgrading.
Fix: Run `cwltool --validate your_upgraded_document.cwl` after using `cwl-upgrader` to ensure the document is valid.
gotcha Documents written in the legacy 'sbg:draft-2' format are not supported by cwl-upgrader. A separate tool, `sevenbridges-cwl-draft2-upgrader`, is required for these older documents.
Fix: For 'sbg:draft-2' documents, use `pip install sevenbridges-cwl-draft2-upgrader` and then use the `sbg_cwl_upgrader` command.
breaking CWL v1.2 introduces stricter rules and clarifications that might cause previously working (but non-standard) constructs to fail validation. For example, absolute paths starting with '/' for `InitialWorkDirRequirement` are only permitted in CWL 1.2 and later, and `loadContents` has a 64KiB size limit.
Fix: Review the CWL v1.2 specification changelog and adjust documents to conform to new requirements. Use `cwltool --validate` to pinpoint specific issues.

Install

pip install cwl-upgrader Install latest version

Imports

cwl-upgrader
```
cwl-upgrader --help
```
cwl-upgrader is primarily a command-line tool. Direct programmatic import of a public API for upgrading CWL documents is not the primary interface; users typically invoke the 'cwl-upgrader' executable.

Quickstart

The cwl-upgrader tool is primarily used from the command line. This quickstart demonstrates how to create a simple CWL v1.0 `CommandLineTool` and then upgrade it to v1.2 using the `cwl-upgrader` executable. The output is redirected to a new file.

# Create a sample CWL v1.0 CommandLineTool
cat <<EOF > my_tool_v1_0.cwl
cwlVersion: v1.0
class: CommandLineTool
baseCommand: echo
inputs:
  message:
    type: string
    inputBinding:
      position: 1
outputs:
  output_file:
    type: File
    outputBinding:
      glob: output.txt
EOF

# Upgrade the CWL document to v1.2
cwl-upgrader my_tool_v1_0.cwl > my_tool_v1_2.cwl

# Verify the upgraded file
cat my_tool_v1_2.cwl

view raw JSON →