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

# Visualize DAG topology and diff artifacts across runs

> Render a DAG as Mermaid or Graphviz to understand its structure, then compare per-node artifacts between two runs for prompt iteration or A/B testing.

`agentgraph graph` prints a text representation of your DAG's node topology — useful for understanding wave structure before running a complex workflow. `agentgraph diff` compares the artifact produced by each node across two runs of the same DAG, making it straightforward to evaluate the effect of a prompt change or a backend switch.

<Tabs>
  <Tab title="graph">
    ## agentgraph graph

    Render the DAG as Mermaid flowchart or Graphviz DOT. Output goes to stdout so you can pipe it directly to a renderer.

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

    ### Arguments and flags

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

    <ParamField path="--format / -f" type="string" default="mermaid">
      Output format. Options: `mermaid` or `graphviz`.
    </ParamField>

    ### Examples

    <CodeGroup>
      ```bash Print Mermaid to terminal theme={null}
      agentgraph graph examples/research.yaml
      ```

      ```bash Render Mermaid to PNG with mmdc theme={null}
      agentgraph graph examples/research.yaml | mmdc -i - -o dag.png
      ```

      ```bash Generate Graphviz DOT and render to SVG theme={null}
      agentgraph graph examples/research.yaml --format graphviz > dag.dot
      dot -Tsvg dag.dot > dag.svg
      ```

      ```bash Save Mermaid to a file theme={null}
      agentgraph graph examples/research.yaml > research.mmd
      ```
    </CodeGroup>

    ### Mermaid output format

    The Mermaid output groups nodes by execution wave inside `subgraph` blocks, with node types shown as italicised labels. Edges reflect the `depends_on` declarations in your YAML.

    ```
    flowchart TD
        classDef agent fill:#cfe2ff,stroke:#084298;
        subgraph wave1["wave 1"]
            research_a["research_a<br/><i>agent</i>"]:::agent
            research_b["research_b<br/><i>agent</i>"]:::agent
            research_c["research_c<br/><i>agent</i>"]:::agent
        end
        subgraph wave2["wave 2"]
            synthesizer["synthesizer<br/><i>agent</i>"]:::agent
        end
        research_a --> synthesizer
        research_b --> synthesizer
        research_c --> synthesizer
    ```

    Node type colours match the `inspect` status colour scheme: agent nodes are blue, approval gates are red, exec nodes are grey, and so on.
  </Tab>

  <Tab title="diff">
    ## agentgraph diff

    Compare per-node artifacts between two runs of the same DAG as a unified diff. Lines added in `run_b` are green, lines removed from `run_a` are red, and unchanged nodes are shown with an `=` marker.

    ```
    agentgraph diff <run_a> <run_b> [OPTIONS]
    ```

    ### Arguments and flags

    <ParamField path="run_a" type="string" required>
      Baseline run ID.
    </ParamField>

    <ParamField path="run_b" type="string" required>
      Comparison run ID.
    </ParamField>

    <ParamField path="--runs-dir" type="string" default="runs">
      Runs directory containing both runs.
    </ParamField>

    <ParamField path="--context / -c" type="number" default="3">
      Number of context lines to show around each change in the unified diff output.
    </ParamField>

    ### Examples

    <CodeGroup>
      ```bash Basic diff between two runs theme={null}
      agentgraph diff a1b2c3d4e5f6 f6e5d4c3b2a1
      ```

      ```bash More context lines theme={null}
      agentgraph diff a1b2c3d4e5f6 f6e5d4c3b2a1 --context 10
      ```

      ```bash Custom runs directory theme={null}
      agentgraph diff a1b2c3d4e5f6 f6e5d4c3b2a1 --runs-dir /data/runs
      ```
    </CodeGroup>

    ### Output format

    For each node that appears in either run:

    * `= node_id (identical digest)` — node produced the same output in both runs
    * `~ node_id (changed)` — followed by a unified diff of the two artifacts
    * `+ node_id — only in <run_b>` — node exists only in the second run
    * `- node_id — only in <run_a>` — node exists only in the first run

    ### Use cases

    **Prompt iteration** — Run the same DAG twice with a modified prompt on one node, then diff to see exactly what changed in downstream outputs.

    **Backend comparison** — Run the same DAG with `--backend claude_code` and `--backend api` to compare output quality across providers.

    **Regression testing** — Record a fixture from a known-good run, replay it after a DAG change, and diff to confirm no outputs changed unintentionally.
  </Tab>
</Tabs>

<Tip>
  Paste Mermaid output directly into a GitHub pull request comment — GitHub renders Mermaid natively inside code fences tagged <code>\`\`\`mermaid</code>.
</Tip>