CLI & configuration

The shape of the CLI

dagron is configured in three layers, and only three:

• Positional arguments — the dagron binary takes at most a subcommand token and two positionals. There are no --flags on the engine binary.
• Environment variables — everything else: executor backend, worker count, datastore, scheduling loops, secrets, logging.
• Cargo features — compile-time selection of the storage backend and optional subsystems. A capability that was not compiled in is a startup error, never a silent downgrade.

There is no run subcommand: the first positional is the DAG path. The two companion tools that do take flags (dagron-plan, dagron-import) are separate binaries, documented below.

dagron — run the engine

dagron [dev] [DAG_PATH] [DB_TARGET]
dagron validate <file|dir>... [--json]
dagron archive-compact [DB_TARGET]

One-shot vs. resident

With only a DAG path, dagron executes that one workflow and exits when all runs drain:

$ ./target/release/dagron examples/simple_dag.yaml
INFO dagron_engine: run complete run_id=… status=succeeded
INFO dagron_engine: all runs drained — scheduler exiting

The process stays resident instead when anything long-lived is enabled: dagron dev, an API_ADDR (the ops API), CRON_CONFIG, GC_RETENTION_SECS, or DB_SCHEDULES. In dev mode, submit a run with raw workflow YAML as the body:

$ cargo build --release -p dagron
$ ./target/release/dagron dev
INFO dagron_engine: dagron dev — local quickstart: datastore workflow.db, management API + Swagger UI on http://127.0.0.1:8787/docs (override with API_ADDR)
$ curl -s -X POST localhost:8787/runs --data-binary @examples/simple_dag.yaml
# {"run_id":"…"}

The full stack with the web UI is one command: docker compose up --build (or podman compose up --build).

Two HTTP surfaces

dagron exposes two HTTP APIs with a deliberate boundary. The engine ops API (built with the default ops feature, bound at API_ADDR) is unauthenticated and meant to stay cluster-internal; it is self-describing — OpenAPI 3 at /openapi.yaml and /openapi.json, Swagger UI at /docs. The dagron-api UI edge is the JWT-gated surface on PORT for browsers, automation, and agents. Full endpoint reference: API.md on GitHub.

dagron validate and dagron archive-compact

dagron validate

dagron validate <file|dir>... [--json] is an offline spec lint: it parses, template-expands, and graph-validates each *.yaml/*.yml through the same pipeline every submit path uses. Directories are walked recursively (hidden directories skipped). No datastore, no server — it works in every build, so it fits pre-commit hooks and CI.

• --json — emit one JSON object per file.
• Exit code — non-zero if any file fails validation.

$ dagron validate workflows/ --json

dagron archive-compact

dagron archive-compact [DB_TARGET] runs one bounded sweep that folds archived run-*.json documents into the date-partitioned Parquet dataset (compact/tasks/dt=…/) — the Kubernetes CronJob shape. It reads the archive sink env (GC_ARCHIVE_DIR / GC_ARCHIVE_URL) and optionally a datastore to stamp archived_runs. Documents younger than GC_ARCHIVE_COMPACT_MIN_AGE_DAYS (default 30) stay individually retrievable; 0 compacts everything eligible.

Companion binaries

dagron-api

Stateless and Postgres-only (SSE needs LISTEN/NOTIFY). It takes no arguments; configuration is environment-only — see the variables below. DATABASE_URL and DAGRON_JWT_SECRET are required at startup.

dagron-mcp

No arguments; JSON-RPC 2.0 over stdio, logs to stderr so stdout carries only protocol messages. Configured by two variables: DAGRON_API_URL (default http://localhost:8080) and DAGRON_MCP_TOKEN (a session JWT sent as Authorization: Bearer). The tool catalogue is below.

dagron-import

dagron-import argo <workflow.yaml> — exactly two arguments; only the argo importer exists. It prints a dagron DAG YAML to stdout; pipe it into a file or POST /api/runs to migrate. An unknown importer or wrong argument count exits 2.

$ dagron-import argo workflow.yaml > my_dag.yaml

dagron-plan

Both specs are resolved through the real dagron parser and expander, so the plan reflects what would actually run. Output is GitHub-flavored markdown (summary, per-task diff, and a Mermaid graph of the resulting DAG) — pipe it into a PR comment.

dagron-plan <base.yaml> <head.yaml>         # diff two files
dagron-plan --git <base>..<head> <path>     # diff a file across two refs
dagron-plan --git <base> <path>             # diff <base>:<path> vs the worktree

• --exit-code — return 2 (not 0) when the plan has changes, for a CI drift gate. Exit codes otherwise follow git diff: 0 no changes, 1 error.
• --mermaid — print only the Mermaid graph.
• -h, --help — usage. Any unrecognized dash-prefixed argument is an error, not a positional.

dagron-gitops

A polling worker with no ports: it scans registered repositories for YAML files carrying a tasks: key, validates each with the engine's own parser, and upserts it as a workflow definition. Repositories are connected from the console or the API; the reconcile is idempotent. It is the one dagron image that carries a git binary, which is why it ships separately — deploy it only if you use GitOps. Configuration: DATABASE_URL (required), GITOPS_POLL_SECS (default 60), DAGRON_GIT_TOKEN (sent only to trusted forge hosts over HTTPS), RUST_LOG.

Environment variables

The tables below are the user-facing subset. The complete list — streaming knobs, split-DSN seams, KMS envelope encryption, CA trust, and per-variable detail — is CONFIG.md on GitHub.

Engine core

Ops API, scheduling, and GC

Artifacts and archive

Secrets and masking

dagron-api (UI edge)

Logging (all binaries)

Every binary shares the same logging knobs: RUST_LOG (full tracing filter, wins over everything), LOG_LEVEL (default info), and LOG_FORMAT (full, compact, pretty, or json; default full). Further formatting toggles are in CONFIG.md.

Cargo features

Features are compile-time: a value that names a subsystem the binary was not built with fails at startup with a message, never a silent downgrade.

MCP tools

dagron-mcp exposes nine tools over stdio. It talks to the JWT-gated dagron-api edge — never the engine's internal ops API — so every access control on the UI edge applies identically to agents.

Reach for dagron_get_run_logs first when a run failed: one call returns every task's output as a single attributed, server-filtered stream. Both log tools take the same filter arguments — q, exclude, regex, level, case, context, limit, tail.

Register the server with an MCP client — the binary, or the published mancube/dagron-mcp image over docker run -i:

{
  "mcpServers": {
    "dagron": {
      "command": "dagron-mcp",
      "env": {
        "DAGRON_API_URL": "http://localhost:8080",
        "DAGRON_MCP_TOKEN": "<session-jwt>"
      }
    }
  }
}

The transport is newline-delimited JSON-RPC 2.0 on stdio. Security guidance — token scoping, edge isolation, executor sandboxing — is in MCP.md on GitHub.