Tooling

Export & Visualization

Turn a workflow into a diagram — Mermaid, DOT, and migration.

A workflow is a graph, and sometimes you want to see it. Dippin exports to two diagram formats — Mermaid and Graphviz DOT — and can migrate existing DOT pipelines back into .dip source.

export-mermaid

dippin export-mermaid <file>

Export a workflow to a Mermaid flowchart — shapes and colors by node kind, edges labeled by routing condition, start/exit emphasized. Renders natively on GitHub and in the playground; the quickest way to drop a live workflow diagram into a README. Subgraph refs are flattened first.

Because Mermaid renders natively on GitHub, piping a workflow into a fenced ```mermaid block in your README gives you a live, always-current diagram with no build step:

dippin export-mermaid pipeline.dip

export-dot

dippin export-dot [--rankdir=LR|TB] [--prompts] <file>

Export a workflow to Graphviz DOT format for visualization. Maps node kinds to DOT shapes (agent=box, human=hexagon, tool=parallelogram). Goal gate nodes get red background; restart edges are dashed.

--rankdir=LR|TB: Set graph layout direction — left-to-right or top-to-bottom.
--prompts: Include prompt text inside the rendered nodes.

migrate / validate-migration

Coming from an existing Graphviz DOT pipeline? Convert it to .dip source and verify the conversion preserved the graph.

migrate

dippin migrate [--output <file>] <file.dot>

Convert a DOT file to .dip source format. Maps DOT shapes to Dippin node kinds, extracts graph attributes, unescapes prompts, and prefixes bare condition variables with ctx..

validate-migration

dippin validate-migration <old.dot> <new.dip>

Check structural parity between a DOT file and a .dip file to verify migration correctness. Reports missing nodes, different edges, and changed conditions.

Graphviz Integration

For visual workflow diagrams, pipe export-dot output to Graphviz:

# PNG output
dippin export-dot pipeline.dip | dot -Tpng -o pipeline.png

# SVG for web
dippin export-dot pipeline.dip | dot -Tsvg -o pipeline.svg

# Left-to-right layout (better for wide pipelines)
dippin export-dot --rankdir=LR pipeline.dip | dot -Tpng -o pipeline.png

# Include prompt text in nodes
dippin export-dot --prompts pipeline.dip | dot -Tpng -o pipeline.png

Install Graphviz: brew install graphviz (macOS), apt install graphviz (Debian/Ubuntu), or graphviz.org.