CLI Reference

Complete reference for all daggle commands. See also global flags that apply to every command.

daggle run

Run a DAG immediately.

daggle run <dag> [-p key=value]... [--dry-run]

Flag	Type	Default	Description
-p, --param	key=value	(none)	Set a parameter value. Repeatable.
--dry-run	bool	false	Validate and report what would happen; do not execute or create a run

Runs the named DAG synchronously, streaming step output to the terminal. Exit code reflects the DAG outcome: 0 for success, 1 for failure.

With --dry-run, daggle loads the DAG, resolves secrets, checks the R version constraint, detects renv, evaluates freshness rules, and verifies that referenced scripts exist — then prints a plan of which steps would run in which tiers. No run directory is created and no steps are executed. Exits non-zero if any check fails. Use daggle plan for cache-status analysis.

daggle watch

Run a DAG and re-run it whenever its YAML or any referenced script changes. Useful while authoring a DAG.

daggle watch <dag> [-p key=value]... [--debounce <duration>]

Flag	Type	Default	Description
-p, --param	key=value	(none)	Set a parameter value. Repeatable.
--debounce	duration	500ms	Delay after the last change before re-running

The initial run executes immediately, then daggle watches the DAG YAML, its base.yaml (if present), and every file referenced by a script:, validate:, quarto:, or rmd: step. On save, the DAG is re-validated and re-run. Steps marked cache: true skip automatically when their inputs haven’t changed, so only the affected steps re-execute. Press Ctrl+C to stop.

daggle validate

Validate a DAG definition and display the execution plan.

daggle validate <dag|path>

Accepts a DAG name (resolved via discovery) or a direct file path. Checks YAML syntax, schema conformance, dependency cycles, and missing references. Prints the resolved execution plan on success.

daggle lint

Semantic diagnostics for a DAG. Goes beyond daggle validate by checking that referenced resources actually exist and are resolvable.

daggle lint <dag|path> [--format text|gnu|json] [--check-packages]

Flag	Type	Default	Description
--format	string	text	Output format: text, gnu (path:line:col: severity: message [code]), or json
--check-packages	bool	false	Check that required R packages for R-based step types are installed (runs Rscript)

Checks performed:

• Parse/schema errors (same as daggle validate)
• Referenced scripts exist (script:, validate:, quarto:, rmd:, connect.path)
• ${env:} secret references resolvable against the current environment
• ${file:} secret references point to readable files (${vault:} references are reported as info — not checked)
• notify: channel names are defined in config.yaml
• With --check-packages: required R packages for step types like rmd, coverage, pkgdown, etc. are installed

The gnu and json formats are designed for editor integration (VS Code problem matchers, CI annotations). Exits 1 if any error-severity diagnostic is reported.

daggle status

Show the status of the latest (or specified) run.

daggle status <dag> [--run-id <id>]

Flag	Type	Default	Description
--run-id	string	(latest)	Specific run ID to inspect

Displays step-by-step status, durations, and any error messages.

daggle list

List all available DAGs with their last run status.

daggle list [--tag <tag>] [--team <team>] [--owner <owner>]

Flag	Type	Default	Description
--tag	string	(none)	Only show DAGs with this tag
--team	string	(none)	Only show DAGs owned by this team
--owner	string	(none)	Only show DAGs owned by this user

Scans the DAGs directory and displays each DAG name, trigger schedule (if any), and last run outcome. Also shows OWNER, TEAM, and TAGS columns when any DAG declares those fields. Filters combine with AND semantics.

daggle serve

Start the scheduler daemon, optionally with the REST API.

daggle serve [--port <n>]

Flag	Type	Default	Description
--port	integer	8787	Port for the REST API

Runs in the foreground. The scheduler evaluates cron triggers and file-watch triggers. When --port is specified, the REST API is also served.

daggle stop

Stop the running scheduler daemon.

daggle stop

Reads the PID from ~/.local/share/daggle/proc/scheduler.pid and sends a graceful shutdown signal.

daggle doctor

Check system health.

daggle doctor

Verifies R installation, required packages, directory permissions, scheduler status, and configuration validity. Prints a checklist of pass/fail items.

daggle history

Show run history for a DAG.

daggle history <dag> [--last <N>]

Flag	Type	Default	Description
--last	integer	10	Number of recent runs to show

Displays a table of runs with timestamps, durations, and outcomes.

daggle stats

Show duration trends and success rate for a DAG.

daggle stats <dag> [--last <N>]

Flag	Type	Default	Description
--last	integer	20	Number of recent runs to analyze

Displays min/max/median duration, success rate, and a sparkline trend.

daggle cancel

Cancel an in-flight run.

daggle cancel <dag> [--run-id <id>]

Flag	Type	Default	Description
--run-id	string	(latest)	Specific run ID to cancel

Sends a cancellation signal to the running DAG. Steps already completed are not rolled back.

daggle clean

Remove old run data.

daggle clean --older-than <duration>

Flag	Type	Default	Description
--older-than	duration	(required)	Remove runs older than this (e.g. 30d, 2w)

The --older-than flag is required to prevent accidental deletion. Removes run directories, logs, and event files.

daggle approve

Approve a run waiting at an approval gate.

daggle approve <dag> [--run-id <id>]

Flag	Type	Default	Description
--run-id	string	(latest)	Specific run ID to approve

Resumes execution of a DAG paused at a step with approval: true.

daggle reject

Reject a run waiting at an approval gate.

daggle reject <dag> [--run-id <id>]

Flag	Type	Default	Description
--run-id	string	(latest)	Specific run ID to reject

Marks the waiting step as rejected and fails the DAG.

daggle why

Diagnose why a run failed.

daggle why <dag> [run-id]

Collapses status, stderr tail, step states, and DAG-hash drift into a single screen. Defaults to the most recent failed run; pass an explicit run ID to inspect a specific one. Compares the run’s dag_hash against the last successful run so you can tell whether the YAML changed between runs.

Output sections: failed step and error detail, last 20 lines of stderr, per-step status table, and DAG-hash comparison.

daggle annotate

Attach a free-form note to a run.

daggle annotate <dag> <run-id> <note> [--author <name>]

Flag	Type	Default	Description
--author	string	$USER	Override the recorded author

Writes a run_annotated event to the run’s events.jsonl. Annotations surface in daggle status, the REST API, and the web UI. Use them for post-mortem notes, manual-restart explanations, or any context you want future-you to see next to the run.

daggle monitor

Interactive TUI that streams a run’s events live.

daggle monitor <dag> [--run-id <id>] [--url <url>]

Flag	Type	Default	Description
--run-id	string	latest	Specific run ID to follow
--url	string	auto-detect	Base URL of a daggle server

Subscribes to the SSE stream endpoint and renders per-step status, duration, peak RSS, and annotation count. If no server is listening on http://localhost:8080, daggle monitor spawns an embedded read-only API on a random port for the session. Press q or esc to quit.

daggle archive

Bundle a run directory into a tamper-evident .tar.gz with an embedded SHA-256 manifest.

daggle archive <dag> <run-id> [-o <path>]

Flag	Type	Default	Description
-o, --output	path	./<dag>_<run-id>.tar.gz	Output archive path

The archive contains .manifest.sha256 as its first entry (one <sha256> <path> line per file), followed by every regular file in the run directory in sorted order. Pair with daggle verify to detect corruption, tampering, missing files, or extras. FDA 21 CFR Part 11 adjacent.

daggle verify

Check the integrity of a daggle archive.

daggle verify <archive>

Re-hashes every file inside the archive and compares against the embedded manifest. Prints OK: <N> files verified on success; on failure lists mismatched, missing, and extra files and exits non-zero.

daggle impact

Show a DAG’s downstream dependents and declared exposures.

daggle impact <dag>

Lists other DAGs that trigger off this one (via trigger.on_dag.name) plus any exposures: declared on the DAG itself (Shiny apps, Quarto reports, dashboards, etc.). Purely informational — daggle does not deploy or monitor the exposures.

daggle init

Generate a DAG from a built-in template.

daggle init <template>

Available templates:

Template	Description
pkg-check	R package check pipeline (build, check, test)
pkg-release	R package release workflow
data-pipeline	Extract-transform-load data pipeline

Writes the generated YAML to .daggle/ in the current directory.

daggle register

Register a project directory so the scheduler picks up its .daggle/ DAGs.

daggle register [path] [--name <name>]

Flag	Type	Default	Description
--name	string	(directory basename)	Project name for the registry

• path defaults to the current working directory
• Validates .daggle/ exists (warns if not)
• Checks for DAG name collisions across all sources
• Sends SIGHUP to running scheduler for immediate reload
• Registry stored at ~/.config/daggle/projects.yaml

daggle unregister

Remove a project from the registry.

daggle unregister <name|path>

Accepts the project name or its filesystem path. Sends SIGHUP to running scheduler.

daggle projects

List all registered projects.

daggle projects

Shows: project name, status (ok/missing), DAG count, path. Also shows the global DAGs directory.

daggle version

Print the daggle version.

daggle version

Prints the version string (e.g. 0.4.1). Development builds show dev.

Global flags

These flags apply to all commands and override the corresponding environment variables.

Flag	Type	Default	Description
--dags-dir	path	(discovery order)	Directory containing DAG definitions
--data-dir	path	~/.local/share/daggle	Directory for run data and state