CLI Reference
Four sub-commands for the full DAG lifecycle: generate, validate, list, and resolve.
Global Flags
| Flag | Description |
|---|---|
-v, --verbose | Show debug-level output |
-q, --quiet | Suppress informational output (warnings and errors only) |
dagsmith generate
Render YAML specs into .py DAG files.
bash
dagsmith generate TARGETS [options]| Flag | Description |
|---|---|
TARGETS | One or more YAML file paths or directories required |
-p, --pattern REGEX | Filter YAML files by filename regex |
-o, --output-dir DIR | Output directory (default: ./dags/) |
--dry-run | Validate and render without writing files |
-x, --fail-fast | Stop on first failure |
--no-format | Skip ruff post-processing |
Examples
bash
# Generate all YAMLs in a directory
dagsmith generate specs/
# Single file
dagsmith generate specs/sequential_bq.yaml
# Directory + regex filter
dagsmith generate specs/ -p "bq_.*"
# Validate + render without writing (preview)
dagsmith generate specs/ --dry-run
# Fail-fast, skip formatting
dagsmith generate specs/ -x --no-format
# Explicit output directory
dagsmith generate specs/ -o dags/What happens during generate
- Load — Reads the YAML file and expands
${VAR}references - Validate — Pydantic validates every field; errors are shown with file/field context
- Render — The code generator produces a complete
.pystring - Write — Writes to
<output_dir>/<dag_id>.py - Format — Runs
ruff check --fix+ruff format(unless--no-format)
dagsmith validate
Validate YAML specs without generating code. Ideal for CI gates.
bash
dagsmith validate TARGETS [options]| Flag | Description |
|---|---|
TARGETS | One or more YAML file paths or directories required |
-p, --pattern REGEX | Filter YAML files by filename regex |
--strict | Treat warnings as errors (missing metadata, zero retries, isolated tasks) |
Validation checks
- Schema validation — Pydantic field types, constraints, required fields
- Semantic checks —
dag_idnot empty,project_idset, at least 1 task - Dependency resolution — All names in
>>/<<chains resolve to known task/group IDs
Strict mode warnings (treated as errors with --strict)
metadata.titleis "N/A"metadata.jirais "N/A"default_args.retriesis 0- No dependencies defined (tasks are isolated)
dagsmith list
Display all registered operators, sensors, and utilities from the registry.
bash
dagsmith list [options]| Flag | Description |
|---|---|
--origin | Filter by section: standard, third_party, custom |
--type | Filter by class type: operator, sensor, util, model |
Examples
bash
# List everything
dagsmith list
# Only sensors
dagsmith list --type sensor
# Only custom classes
dagsmith list --origin custom
# Standard operators only
dagsmith list --origin standard --type operatordagsmith resolve
Expand ${VAR__...__VAR} references and output the fully resolved YAML. Useful for debugging variable substitution.
bash
dagsmith resolve TARGETS [options]| Flag | Description |
|---|---|
TARGETS | One or more YAML file paths or directories required |
-p, --pattern REGEX | Filter YAML files by filename regex |
-o, --output FILE | Write resolved YAML to a file instead of stdout |
-x, --fail-fast | Stop on first variable expansion error |
Examples
bash
# Print resolved YAML to console
dagsmith resolve examples/01_simple_bq_pipeline.yaml
# Resolve matching files by pattern
dagsmith resolve examples/ -p "parallel"
# Write resolved output to a file
dagsmith resolve examples/01_simple_bq_pipeline.yaml -o resolved.yaml
# Stop on first variable error (CI use)
dagsmith resolve examples/ -x