wdl-lint

name: wdl-lint description: > Validate, lint, and fix WDL files using womtool, miniwdl check, and/or sprocket. Use this skill whenever the user wants to check WDL syntax, understand or fix lint warnings, suppress specific rules, interpret tool error output, set up CI validation, or run any of: womtool validate, miniwdl check, sprocket check, sprocket lint, or sprocket format. Also trigger when the user pastes tool output containing WDL errors or warnings and asks for help understanding or fixing them.

WDL Lint & Validation

Three tools cover the WDL validation/lint space. Each has a different focus, WDL version range, and strictness model. Use all three for maximum coverage — they catch different things.

For WDL syntax help see the root SKILL.md and references/wdl-spec-highlights.md.

Installation

# womtool — download the jar matching your Cromwell version
wget https://github.com/broadinstitute/cromwell/releases/latest/download/womtool-<version>.jar
alias womtool='java -jar /path/to/womtool.jar'

# miniwdl — Python 3.6+, Docker required for run (not check)
pip install miniwdl
# with ShellCheck integration (recommended)
brew install shellcheck       # macOS
sudo apt install shellcheck   # Debian/Ubuntu

# sprocket — single binary, no JVM/Python needed
cargo install sprocket        # via Rust/cargo
# or download prebuilt from GitHub releases:
# https://github.com/stjude-rust-labs/sprocket/releases

Quick Reference — Common Commands

# ── WOMTOOL ─────────────────────────────────────────────────────────
womtool validate workflow.wdl                     # syntax + type check
womtool validate --list-dependencies workflow.wdl # also print imports
womtool inputs workflow.wdl                       # generate inputs JSON template
womtool inputs workflow.wdl > inputs.json
womtool parse workflow.wdl                        # grammar-only AST (no semantic check)
womtool graph workflow.wdl                        # DOT-format dependency graph
womtool highlight workflow.wdl html               # colorized HTML output
womtool highlight workflow.wdl console            # colorized terminal output

# ── MINIWDL ─────────────────────────────────────────────────────────
miniwdl check workflow.wdl                        # parse + type + lint (exit 0 on warn)
miniwdl check --strict workflow.wdl               # lint warnings → non-zero exit
miniwdl check -p imports/ workflow.wdl            # add import search path
miniwdl check --suppress MissingVersion,StringCoercion workflow.wdl
miniwdl check --no-quant-check workflow.wdl       # skip optional→String coercion warnings
miniwdl check workflow.wdl task.wdl               # check multiple files at once

# ── SPROCKET ────────────────────────────────────────────────────────
sprocket check workflow.wdl                       # analysis only (errors/warnings, no extra lint)
sprocket lint workflow.wdl                        # check + full lint rules (shortcut for check --lint)
sprocket lint .                                   # lint entire directory (defaults to CWD)
sprocket format workflow.wdl                      # format in-place
sprocket format --check workflow.wdl              # format dry-run (exit 1 if changes needed)
sprocket validate --entrypoint my_workflow workflow.wdl inputs.json
sprocket analyzer                                 # start LSP server for IDE integration

Interpreting Output

womtool output

# Success
Success!

# Syntax error
ERROR: Unexpected symbol (line 4, col 5) when parsing '_gen4'.
  Expected rbrace, got input.
    input {
    ^

# Semantic error
ERROR: Task and namespace have the same name: Task defined here (line 3, col 6):
  task ps {
       ^
  Import statement defined here (line 1, col 20):
  import "ps.wdl" as ps

womtool limitations to know:

• Validates "can this be run on Cromwell" not just "is this spec-valid" — task-only files (no workflow) will fail older versions
• Does not enforce style or best-practice lint beyond type correctness
• WDL 1.2 support is partial; use sprocket for 1.2/1.3

miniwdl check output

workflow.wdl (Ln 1, Col 1) MissingVersion
  document should declare WDL version; draft-2 assumed
task align (Ln 5, Col 17) CommandShellCheck, SC2086
  Double quote to prevent globbing and word splitting.
task align (Ln 12, Col 10) StringCoercion
  String s = :Int?:
task align (Ln 18, Col 14) NameCollision
  declaration of 'align' collides with a task name
task align (Ln 22, Col 10) UnusedDeclaration
  nothing references String scratch

Format: file (Ln N, Col N) WarningName[, detail]

All miniwdl warning names:

Suppressing miniwdl warnings:

# Inline suppression — same line or the line after
task t {
    String s = i   # !ForwardReference !StringCoercion
    Int? i

    command <<<
        if [ ! -n ~{s} ]; then   # shellcheck: disable=SC2236
            echo Empty
        fi
    >>>

    output {
        String t = read_string(stdout())  # !NameCollision — meant to do that
    }
}

# Global suppression via CLI (not recommended — use inline instead)
miniwdl check --suppress ForwardReference,StringCoercion workflow.wdl

sprocket output

error[v1::E001]: unknown type `Fiel`
  --> workflow.wdl:13:5
   |
13 |     Fiel outfile = "wc.txt"
   |     ^^^^ unknown type

warning[v1::W001]: missing `meta` section
  --> workflow.wdl:1:1
   |
 1 | version 1.2
   | ^^^^^^^^^^^ missing `meta` section in task `my_task`

note[v1::N001]: `input:` keyword is deprecated in WDL 1.2+
  --> workflow.wdl:20:10

Format: level[code]: message + source location span

Sprocket exit codes:

• 0 — no errors (warnings may still be present)
• 1 — one or more errors found
• 2 — internal tool error

Sprocket Lint Rules

All rules are enabled with sprocket lint (or sprocket check --lint).

Suppress a rule for the whole file (preamble directive):

#@ except: SnakeCase, DoubleQuotes
version 1.2

Suppress a rule for a section:

#@ except: MetaSections
task legacy_task {
    command <<< echo hello >>>
}

Full rule table

Fix vs. Review Decision Guide

When Claude encounters WDL errors or warnings, use this classification:

✅ Auto-fix safe (deterministic, no semantic risk)

These can be applied without review:

⚠️ Review before fixing (may change behaviour or require decisions)

These need the user's input before applying:

CI Integration Patterns

Minimal CI (syntax errors only)

# Fast gate — catches parse/type errors, not style
miniwdl check --strict *.wdl

Cromwell-targeted CI

# womtool for Cromwell semantic validation
for f in workflows/*.wdl; do
    java -jar womtool.jar validate "$f" || exit 1
done

Full lint CI (recommended for new projects)

# sprocket covers 1.2/1.3 and has the strictest lint rules
sprocket lint .
sprocket format --check .    # fail if any file needs formatting

Combined multi-tool CI

#!/usr/bin/env bash
set -euo pipefail

echo "=== miniwdl check ==="
miniwdl check --strict workflows/*.wdl tasks/*.wdl

echo "=== sprocket lint ==="
sprocket lint .

echo "=== sprocket format check ==="
sprocket format --check .

echo "All checks passed."

GitHub Actions example

name: WDL Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install miniwdl
        run: pip install miniwdl

      - name: Install shellcheck
        run: sudo apt-get install -y shellcheck

      - name: Install sprocket
        run: |
          curl -LO https://github.com/stjude-rust-labs/sprocket/releases/latest/download/sprocket-x86_64-unknown-linux-gnu.tar.gz
          tar -xzf sprocket-*.tar.gz
          sudo mv sprocket /usr/local/bin/

      - name: miniwdl check
        run: miniwdl check --strict **/*.wdl

      - name: sprocket lint
        run: sprocket lint .

      - name: sprocket format check
        run: sprocket format --check .

Tool Selection by Situation