Common Workflow Language User Guide

This guide will introduce you to writing workflows using the Common Workflow Language (CWL) open standards. This guide describes the latest specification v1.2.

Contributions and Feedback are Welcome!

If you find that something is missing from this guide, or if you would like to provide other feedback, file an Issue on the project repository for this guide. You can also suggest changes directly in a Pull Request by clicking the “Edit this page” button at the right sidebar of each page.

Navigating the User Guide

If you are a beginner user get started with the Introduction section. For advanced users the subsections of the Topics have detailed information about the most common topics for CWL.

The Table of Contents is displayed at the top menu and also on the left sidebar. It also appears further down this page but with links to subsections. The right sidebar contains links to the sections of each page, and the Search form is on the left sidebar.

Table of Contents

• 1. Introduction
  • 1.1. Quick Start
    • 1.1.1. “Hello World”
    • 1.1.2. Installing a CWL runner
    • 1.1.3. Running “Hello World”
    • 1.1.4. Learn more
  • 1.2. Prerequisites
    • 1.2.1. Operating System
    • 1.2.2. CWL runner
    • 1.2.3. Text Editor
    • 1.2.4. Docker
    • 1.2.5. Learn more
  • 1.3. Basic Concepts
    • 1.3.1. The CWL specification
    • 1.3.2. Implementations
    • 1.3.3. Processes and Requirements
    • 1.3.4. FAIR workflows
    • 1.3.5. Learn more
• 2. Topics
  • 2.1. YAML Guide
    • 2.1.1. Contents
    • 2.1.2. Key-Value Pairs
    • 2.1.3. Comments
    • 2.1.4. Maps
    • 2.1.5. Arrays
    • 2.1.6. JSON Style
    • 2.1.7. Reference
  • 2.2. Command Line Tool
  • 2.3. Expressions
    • 2.3.1. Using external libraries and inline JavaScript code with expressionLib
  • 2.4. Inputs
    • 2.4.1. Essential Input Parameters
    • 2.4.2. Array Inputs
    • 2.4.3. Inclusive and Exclusive Inputs
  • 2.5. Additional Arguments and Parameters
  • 2.6. Parameter References
  • 2.7. Outputs
    • 2.7.1. Returning Output Files
    • 2.7.2. Capturing Standard Output
    • 2.7.3. Array Outputs
  • 2.8. Custom Types
  • 2.9. Expression Tool
  • 2.10. Workflows
    • 2.10.1. Writing Workflows
    • 2.10.2. Nested Workflows
    • 2.10.3. Scattering Steps
    • 2.10.4. Conditional Workflows
  • 2.11. Operations
  • 2.12. Environment Variables
  • 2.13. Using Containers
    • 2.13.1. Running Tools Inside Docker
  • 2.14. Creating Files at Runtime
  • 2.15. Staging Input Files
  • 2.16. Best Practices
  • 2.17. File Formats
    • 2.17.1. Sample Parameter Files
  • 2.18. Metadata and Authorship
    • 2.18.1. Extended Example
  • 2.19. Specifying Software Requirements
  • 2.20. Troubleshooting
    • 2.20.1. Run cwltool with cachedir
• 3. Tutorials
  • 3.1. Beginner Tutorials
  • 3.2. Advanced Tutorials
  • 3.3. Bioinformatics Tutorials
• 4. FAQ
  • 4.1. Non “File” types using evalFrom
  • 4.2. Rename an input file
  • 4.3. Rename an output file
  • 4.4. Setting self-based input bindings for optional inputs
  • 4.5. Model a “one-or-the-other” parameter
  • 4.6. Connect a solo value to an input that expects an array of that type
  • 4.7. Optional Inputs 💯
  • 4.8. Enum Inputs ⚜️
  • 4.9. Record Inputs 📀
  • 4.10. Setting Mutually Exclusive Parameters
  • 4.11. Setting Booleans
  • 4.12. Concatenating Strings in Inputs
  • 4.13. cwltool errors due to filenames with space characters inside
  • 4.14. CWL Parameter Reference error due to hyphen in input identifier
  • 4.15. Use CWL and cwltool with Singularity
  • 4.16. Debug JavaScript expressions
• 5. Licenses
  • 5.1. Instructional Material
  • 5.2. Software
  • 5.3. Trademark