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.2.1. Network Access
  • 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. How do I create non “File” types using evalFrom?
  • 4.2. How do I rename an input file?
  • 4.3. How do I rename an output file?
  • 4.4. How do I reference a local script?
  • 4.5. How can I set self-based input bindings for optional inputs?
  • 4.6. How can I model a “one-or-the-other” parameter?
  • 4.7. How do I connect a solo value to an input that expects an array of that type?
  • 4.8. How do make an input optional? 💯
  • 4.9. How do I specify an input that must come from a list of predefined values (i.e. How do I use enum inputs) ?
  • 4.10. How do I describe dependent or exclusive input parameters(e.g. How do I use record inputs)?
  • 4.11. How do I set mutually exclusive parameters?
  • 4.12. How can I set Booleans?
  • 4.13. What should I do when concatenating strings in inputs?
  • 4.14. I get cwltool errors due to filenames with space characters inside. What should I do?
  • 4.15. What should I do when I get CWL Parameter Reference error due to hyphen in an input identifier?
  • 4.16. How do I use CWL and cwltool with Singularity?
  • 4.17. How do I debug the JavaScript in my CWL tool?
• 5. Licenses
  • 5.1. Instructional Material
  • 5.2. Software