> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dagraph.app/llms.txt
> Use this file to discover all available pages before exploring further.

# agentgraph run: execute DAG workflows from the CLI

> Execute a dagraph YAML workflow from the CLI. Control the backend, sandbox, concurrency, rate limits, and deterministic replay with a single command.

`agentgraph run` is the primary command for executing a workflow. It reads your DAG YAML, computes the execution wave schedule from `depends_on` declarations, fires each wave in parallel, and writes all results to a run directory under `runs/`. If a run was previously interrupted or paused at an approval gate, passing `--run-id` resumes it from exactly where it stopped — completed nodes are skipped automatically.

```
agentgraph run <dag_path> [OPTIONS]
```

## Arguments and flags

<ParamField path="dag_path" type="string" required>
  Path to the DAG YAML file. Relative or absolute.
</ParamField>

<ParamField path="--input / -i" type="string">
  Pass a template input as `key=value`. Repeat the flag for multiple inputs. Keys must match `[A-Za-z_][A-Za-z0-9_]*`. Values are available as Jinja variables inside node prompts (e.g., `{{ topic }}`).
</ParamField>

<ParamField path="--run-id" type="string">
  Use a specific run ID instead of the auto-generated 12-character hex string. Pass the same ID as a previous run to resume it.
</ParamField>

<ParamField path="--runs-dir" type="string" default="runs">
  Directory where run subdirectories are created. Defaults to `runs/` relative to your working directory.
</ParamField>

<ParamField path="--backend" type="string" default="claude_code">
  LLM executor backend. Options:

  * `claude_code` — spawns `claude -p` as a subprocess using your Claude Code plan (no API key needed)
  * `api` — calls the Anthropic Messages API directly (requires `ANTHROPIC_API_KEY`)
  * `codex` — spawns the Codex CLI using your OpenAI/Codex plan
</ParamField>

<ParamField path="--sandbox" type="string">
  Sandbox for `bash` and `python_exec` nodes. Required if your DAG contains exec nodes. Options:

  * `inprocess` — runs subprocesses in the current process (for trusted code)
  * `docker` — runs each exec call in an ephemeral Docker container
</ParamField>

<ParamField path="--record" type="string">
  Path to a JSONL file where every LLM call is recorded. The run still executes against the real backend; the fixture can be used later with `--replay` for deterministic testing.
</ParamField>

<ParamField path="--replay" type="string">
  Path to a JSONL fixture file. All LLM calls are served from the fixture — no backend is contacted. Calls with unknown hashes exit with an error.
</ParamField>

<ParamField path="--replay-from" type="string">
  Run ID of a previous run. Replays from that run's auto-recorded fixture at `runs/<run_id>/fixture.jsonl`. Equivalent to `--replay runs/<run_id>/fixture.jsonl`.
</ParamField>

<ParamField path="--max-concurrent" type="number" default="10">
  Maximum number of simultaneous in-flight LLM calls. Useful with `claude_code` where each call spawns a subprocess.
</ParamField>

<ParamField path="--rpm" type="number">
  Requests-per-minute cap. Applies a token-bucket rate limiter across all nodes. Most useful with `--backend api` to avoid Anthropic 429 errors.
</ParamField>

## Examples

<CodeGroup>
  ```bash Basic run theme={null}
  agentgraph run examples/research.yaml --input topic="quantum computing"
  ```

  ```bash With multiple inputs theme={null}
  agentgraph run pipeline.yaml \
    --input topic="quantum computing" \
    --input audience="engineers" \
    --input depth="detailed"
  ```

  ```bash With Anthropic API backend theme={null}
  agentgraph run examples/research.yaml \
    --backend api \
    --input topic="quantum computing"
  ```

  ```bash With rate limiting theme={null}
  agentgraph run examples/research.yaml \
    --backend api \
    --max-concurrent 5 \
    --rpm 30 \
    --input topic="quantum computing"
  ```

  ```bash Deterministic replay theme={null}
  # First run records automatically; note the run_id in the output
  agentgraph run examples/research.yaml --input topic="quantum computing"

  # Replay with no LLM calls — fast, free, deterministic
  agentgraph run examples/research.yaml \
    --input topic="quantum computing" \
    --replay-from a1b2c3d4e5f6
  ```

  ```bash With Docker sandbox (exec nodes) theme={null}
  agentgraph run examples/code_and_llm.yaml \
    --sandbox docker \
    --input topic="data analysis"
  ```

  ```bash Resume a paused run theme={null}
  agentgraph run examples/approval_flow.yaml --run-id a1b2c3d4e5f6
  ```
</CodeGroup>

## Run directory layout

Every run creates a directory at `runs/<run_id>/` with the following structure:

```
runs/<run_id>/
├── state.db          # SQLite checkpoint — one row per node status change
├── trace.jsonl       # OTel-semconv JSON-line trace events
├── fixture.jsonl     # Auto-recorded LLM calls (for --replay-from)
└── artifacts/
    ├── index.json    # Maps node_id → SHA-256 digest
    └── sha256/
        ├── <hash>.bin
        └── ...
```

After the run completes, agentgraph prints the artifacts directory path and trace path so you can navigate directly.

<Note>
  `--record`, `--replay`, and `--replay-from` are mutually exclusive. Passing more than one exits with an error.
</Note>

<Tip>
  Every run automatically records a fixture file at `runs/<run_id>/fixture.jsonl`, so you can always replay any past run with `--replay-from <run_id>` — even if you did not pass `--record` explicitly.
</Tip>