First Example
Overview
Teaching: 5 min
Exercises: 0 minQuestions
How do I write a CWL description of a simple command line tool?
Objectives
Learn the basic structure of a CWL description.
The simplest “hello world” program. This accepts one input parameter, writes a message to the terminal or job log, and produces no permanent output. CWL documents are written in JSON or YAML, or a mix of the two. We will use YAML throughout this guide. If you are not familiar with YAML, you may find it helpful to refer to this quick tutorial for the subset of YAML used in CWL.
First, create a file called 1st-tool.cwl
, containing the boxed text below. It will help you to use a text editor that can be
specified to produce text in YAML or JSON. Whatever text editor you use, the indents you see should not be created using tabs.
1st-tool.cwl
#!/usr/bin/env cwl-runner
cwlVersion: v1.0
class: CommandLineTool
baseCommand: echo
inputs:
message:
type: string
inputBinding:
position: 1
outputs: []
Next, create a file called echo-job.yml
, containing the following boxed text, which will describe the input of a run:
echo-job.yml
message: Hello world!
Now, invoke cwl-runner
with the tool wrapper 1st-tool.cwl
and the input object echo-job.yml on the command line. The command
is cwl-runner 1st-tool.cwl echo-job.yml
. The boxed text below shows this command and the expected output.
$ cwl-runner 1st-tool.cwl echo-job.yml
[job 1st-tool.cwl] /tmp/tmpmM5S_1$ echo \
'Hello world!'
Hello world!
[job 1st-tool.cwl] completed success
{}
Final process status is success
The command cwl-runner 1st-tool.cwl echo-job.yml
is an example of a general form that you will often come across while using
CWL. The general form is cwl-runner [tool-or-workflow-description] [input-job-settings]
What’s going on here? Let’s break down the contents of 1st-tool.cwl
:
cwlVersion: v1.0
class: CommandLineTool
The cwlVersion
field indicates the version of the CWL spec used by the document. The class
field indicates this document
describes a command line tool.
baseCommand: echo
The baseCommand
provides the name of program that will actually run (echo
). echo
is a built-in program in the bash and
C shells.
inputs:
message:
type: string
inputBinding:
position: 1
The inputs
section describes the inputs of the tool.
This is a mapped list of input parameters
(see the YAML Guide for more about the format)
and each parameter includes an identifier,
a data type,
and optionally an inputBinding
.
The inputBinding
describes how this input parameter should appear
on the command line.
In this example,
the position
field indicates where it should appear on the command line.
outputs: []
This tool has no formal output, so the outputs
section is an empty list.
Key Points
CWL documents are written in YAML and/or JSON.
The command called is specified with
baseCommand
.Each expected input is described in the
inputs
section.Input values are specified in a separate YAML file.
The tool description and input files are provided as arguments to a CWL runner.