1.1. Quick Start#

This section will show you a brief overview of what CWL is, and where you can learn more about it. No previous knowledge of CWL is required, but you must be comfortable following instructions for the command-line.

1.1.1. “Hello World”#

CWL is a way to describe command-line tools and connect them together to create workflows. Because CWL is a specification and not a specific piece of software, tools and workflows described using CWL are portable across a variety of platforms that support the CWL standard.

CWL documents are written in YAML (and/or JSON). The example below shows a simple CWL “Hello World” workflow annotated with comments. Note that comments start with #:

hello_world.cwl#

cwlVersion: v1.2

# What type of CWL process we have in this document.
class: CommandLineTool
# This CommandLineTool executes the linux "echo" command-line tool.
baseCommand: echo

# The inputs for this process.
inputs:
  message:
    type: string
    # A default value that can be overridden, e.g. --message "Hola mundo"
    default: "Hello World"
    # Bind this message value as an argument to "echo".
    inputBinding:
      position: 1
outputs: []

The example above is just a wrapper for the echo command-line tool. Running the workflow above with the default input values will produce the same result as the command-line echo "Hello World".

Note

In CWL, there is a distinction between a command-line tool and a workflow. But for the sake of simplicity, we are using the term “workflow” here. You will learn more about this in the basic concepts section.

1.1.2. Installing a CWL Runner#

cwltool is an implementation of the CWL specification. It is also the CWL Reference Runner for the specification, and it is compliant with the latest version of the specification: v1.2. You can install cwltool using pip:

Installing cwltool with pip.#

$ pip install cwltool

Note

If installing the cwltool using the pip command doesn’t work for you, the prerequisites section contains other ways to install cwltool and a more detailed list of software and libraries used for following the rest of this user guide.

1.1.3. Running “Hello World”#

The usage of the cwltool command-line executable is basically cwltool [OPTIONS] [CWL_DOCUMENT] [INPUTS_OBJECT]. You can run the hello_world.cwl workflow without specifying any option:

Running hello_world.cwl with cwltool.#

$ cwltool hello_world.cwl
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'hello_world.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/hello_world.cwl'
INFO [job hello_world.cwl] /tmp/52f5jfoh$ echo \
    'Hello World'
Hello World
INFO [job hello_world.cwl] completed success
{}INFO Final process status is success

Or you can override the default value of the input parameter message, similar to how you would change the argument of the echo base command:

Running hello_world.cwl with cwltool passing an input parameter.#

$ cwltool hello_world.cwl --message="Hola mundo"
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'hello_world.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/hello_world.cwl'
INFO [job hello_world.cwl] /tmp/8owm7vcj$ echo \
    'Hola mundo'
Hola mundo
INFO [job hello_world.cwl] completed success
{}INFO Final process status is success

Another way of passing values to your workflow input parameters is via an Inputs Object. This is a file containing the input fields with their corresponding values. The Inputs Objects file can be written in JSON or YAML. For example:

hello_world-job.json#

{
  "message": "こんにちは世界"
}

You can use this Inputs Object file now to execute the “Hello World” workflow:

Passing an Inputs Object file to cwltool.#

$ cwltool hello_world.cwl hello_world-job.json
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'hello_world.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/hello_world.cwl'
INFO [job hello_world.cwl] /tmp/asatxmp5$ echo \
    こんにちは世界
こんにちは世界
INFO [job hello_world.cwl] completed success
{}INFO Final process status is success

Note

We used a similar file name for the workflow and for the Inputs Object files. The -job.json suffix is very common in Inputs Object files, but it is not a requirement. You can choose any name for your workflows and Inputs Object files.

1.1.4. Learn More#

Continue reading the next sections of this User Guide!

List of CWL Implementations.
The common-workflow-language organization at GitHub.
Common Workflow Language at Wikipedia.
YAML.org and YAML at Wikipedia.
The CWL Specification v1.2.
Workflow management system at Wikipedia.