---
title: "Graph Analysis"
canonical: https://trickest.com/docs/developer-tools/cli/graph
description: "Analyze and validate the workflow DAG: layers, critical path, parallelism, bottlenecks, ancestors/descendants, diff, and export."
---

# Graph Analysis

The `graph` command family treats your active workflow as a directed acyclic graph
and answers structural questions about it: Is it valid? What's the critical path?
Where are the bottlenecks? What can be parallelized?

<Note>
`graph` operates on your **active workflow context** (except `--file` variants).
If a command returns `ERR_NOT_FOUND` (exit 3), set the context first with
`trickest workflow use <name-or-id>`.
</Note>

## Command summary

| Subcommand | Description |
|---|---|
| `graph analyze` | Full DAG analysis: node count, layers, critical path, max parallelism |
| `graph validate` | Find cycles, broken connections, missing inputs |
| `graph layers` | Topological layer breakdown |
| `graph parallelism` | Suggest parallelizable distribution splits |
| `graph bottlenecks` | Identify bottleneck nodes |
| `graph ancestors <node>` | Nodes a given node depends on |
| `graph descendants <node>` | Nodes that depend on a given node |
| `graph path <from> <to>` | Shortest path between two nodes |
| `graph diff` | Diff two workflow versions |
| `graph export` | Export the graph as JSON (graphology) or DOT (Graphviz) |

## `graph analyze`

The headline command — a complete structural report:

```bash
trickest graph analyze
```
```json
{
  "nodeCount": 40,
  "edgeCount": 106,
  "layerCount": 11,
  "maxParallelism": 12,
  "criticalPathLength": 11,
  "criticalPath": ["string-to-file-2","probe-for-web-servers-2", "…", "custom-script-2"],
  "layers": [{"layer":1,"nodes":["string-to-file-2","string-to-file-3"]}, …]
}
```

| Flag | Description |
|---|---|
| `--type <types>` | Filter to specific node types (comma-separated) |
| `--visual` | Also render an ASCII DAG with the critical path annotated |

```bash
trickest graph analyze --visual
trickest graph analyze --type tool,script
```

## `graph validate`

Check correctness before you run — catches cycles, dangling connections, and
missing required inputs:

```bash
trickest graph validate
trickest graph validate -f discovery.yaml      # validate a local YAML file instead
trickest graph validate --type tool        # only report issues for these types
```

| Flag | Description |
|---|---|
| `-f, --file <path>` | Validate a local YAML file instead of the deployed workflow |
| `--type <types>` | Filter issues to specific node types |

<Tip>
Run `graph validate` after every `node`/`connect` change or before `workflow apply
--dry-run` lands. It's the cheapest way to catch a broken DAG.
</Tip>

## Layers, parallelism & bottlenecks

```bash
trickest graph layers                  # topological levels
trickest graph parallelism             # where distribution would help
trickest graph bottlenecks --limit 5   # top structural bottlenecks
```

| Command | Notable flags |
|---|---|
| `graph layers` | `--type <types>` |
| `graph bottlenecks` | `--limit <n>` (default 10), `--type <types>` |

<Info>
`graph distribute` is **deprecated** — use `graph parallelism` instead.
</Info>

## Traversal

Explore dependencies around a node:

```bash
trickest graph ancestors nuclei            # everything nuclei depends on
trickest graph descendants subfinder       # everything downstream of subfinder
trickest graph ancestors nuclei --depth 2  # limit traversal depth
trickest graph path subfinder nuclei       # shortest path between two nodes
```

| Command | Notable flags |
|---|---|
| `graph ancestors` / `graph descendants` | `--depth <n>` |
| `graph path <from> <to>` | — |

## Diff & export

### `graph diff`

```bash
trickest graph diff --versions "v3..v5"    # compare two saved versions
trickest graph diff -f local.yaml          # compare local YAML to deployed
trickest graph diff -f local.yaml --patch  # raw unified diff of serialized JSON
```

| Flag | Description |
|---|---|
| `--versions <range>` | Version range, e.g. `"v3..v5"` |
| `-f, --file <path>` | Compare a local YAML file against the deployed workflow |
| `--patch` | Output a raw unified diff |

### `graph export`

```bash
trickest graph export                       # graphology JSON to stdout
trickest graph export --format dot -o wf.dot   # Graphviz DOT to a file
```

| Flag | Description |
|---|---|
| `--format <json\|dot>` | Export format (default `json`) |
| `-o, --output <path>` | Output file (default stdout) |

Render the DOT export with Graphviz:

```bash
trickest graph export --format dot -o wf.dot && dot -Tpng wf.dot -o wf.png
```

## Related

<CardGroup cols={2}>
  <Card title="Nodes & Connections" icon="circle-nodes" href="/docs/developer-tools/cli/nodes">
    Edit the structure that these commands analyze.
  </Card>
  <Card title="Runs & Outputs" icon="play" href="/docs/developer-tools/cli/runs">
    Once the DAG is valid, execute it and read results.
  </Card>
</CardGroup>

---
_Markdown source of https://trickest.com/docs/developer-tools/cli/graph._