> ## 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.

# Validate a DAG file and preview the execution plan

> Parse a DAG YAML, verify graph structure, preview the execution wave plan, and catch undefined template variables before spending any tokens.

`agentgraph validate` parses your DAG YAML and checks it without executing anything. It resolves the dependency graph into topological waves, reports the declared inputs and outputs, and inspects every Jinja template for variables that are not accounted for. Run it before `agentgraph run` whenever you edit a DAG file.

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

## Arguments and flags

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

<ParamField path="--input / -i" type="string">
  Declare an input key so the template-variable checker treats it as known. Accepts `key=value` or just `key`. Repeat the flag for multiple inputs. Without this flag, any template variable not covered by `depends_on` or the DAG's own `inputs:` block is flagged as a warning.
</ParamField>

## Expected output

A valid DAG prints a summary of waves, declared inputs, declared outputs, and any warnings:

```
✓ research: 4 nodes, 2 wave(s)
  wave 1: ['research_a', 'research_b', 'research_c']
  wave 2: ['synthesizer']

Declared inputs:
  topic : string (required) — Topic to research

Declared outputs:
  report ← node synthesizer
```

## Examples

<CodeGroup>
  ```bash Check a DAG with no inputs theme={null}
  agentgraph validate examples/research.yaml
  ```

  ```bash Declare inputs for stricter variable checking theme={null}
  agentgraph validate examples/research.yaml --input topic
  ```

  ```bash Declare multiple inputs theme={null}
  agentgraph validate pipeline.yaml \
    --input topic \
    --input audience \
    --input depth
  ```
</CodeGroup>

## Declared inputs table

When the DAG declares an `inputs:` block, validate prints each key with its type, required/optional status, default value, and description. This is the same information `agentgraph run` uses to validate `--input` values at execution time.

| Column             | Meaning                                                   |
| ------------------ | --------------------------------------------------------- |
| key                | Input name, usable as `{{ key }}` in node prompts         |
| type               | Declared type (`string`, `number`, etc.)                  |
| required / default | Whether a value must be supplied, and the fallback if not |
| description        | Human-readable description from the DAG file              |

## Declared outputs table

When the DAG declares an `outputs:` block, validate prints each output path and the node whose artifact it maps to. dagraph writes these files after a successful run completes.

## Template variable warnings

If a node prompt references a Jinja variable that is neither in `depends_on`, a known reserved loop variable (`iteration`, `previous_output`, `evaluator_feedback`, `candidate`, `index`), nor a declared `--input`, validate prints a warning:

```
1 template-variable warning(s):
  ⚠ synthesizer.prompt: uses {{ author }} but it is not in depends_on, reserved, or --input
```

These warnings do not prevent `agentgraph run` from executing the DAG, but the template will render an empty string for the unknown variable at runtime.

<Tip>
  Run `agentgraph validate` in CI as a pre-flight check to catch YAML syntax errors and missing inputs before they reach production.
</Tip>