CLI Reference

parse

Parse a workflow file and output the intermediate representation (IR) as JSON. Useful for debugging, tooling integration, and inspecting how the parser interprets your workflow. Accepts .dip or .dot files (auto-detected by extension).

validate

Run structural validation checks (DIP001-DIP010) on a workflow. Outputs "validation passed" or diagnostic messages. Exit code 1 if any errors found.

lint

Run both structural validation and semantic linting (DIP001-DIP010 + DIP101-DIP162). All 72 diagnostic rules. Errors cause exit code 1; warnings alone exit 0.

--extra-models "provider:model1,model2;provider2:model3"

Extend the DIP108 model catalog at runtime for private or newly-released models.

check

Parse, validate, and lint in one shot. Designed for LLM tool-calling loops and CI. Defaults to JSON output with valid, errors, warnings, diagnostics, and suggested_actions fields.

fmt

Format a .dip file to canonical form. 2-space indentation, standard field ordering, deterministic and idempotent output. Use --check for CI (exit 1 if unformatted) or --write for in-place formatting. It also strips redundant parallel/fan_in fan edges re-declared in the edges block — the inline node list is authoritative (DIP153). --migrate converts a v1 file to dip 2 — a lossless version bump: the retry channel stays on the node (retry_target unchanged; fallback_target relabeled to its dip-2 spelling fallback_retry_target) because the engine reads it there, not from an edge (see #186, #204). --migrate --check exits non-zero when a file is not already canonical dip 2.

new

Generate a starter .dip file from a built-in template. Available templates: minimal, parallel, conditional, review-loop, human-gate. Output always passes dippin validate.

export-dot

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.

export-mermaid

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.

migrate

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

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

simulate

Dry-run a workflow's execution graph without calling LLMs or running commands. Emits JSONL events (pipeline_start, node_enter, node_exit, edge_traverse, pipeline_end). Use --scenario to inject context values and --all-paths to enumerate all possible paths.

cost

Estimate workflow execution cost based on model pricing tables. Per-node cost breakdown with turn and token heuristics.

coverage

Analyze edge coverage and reachability. Reports tool output extraction, edge condition matching, and termination analysis.

doctor

Health report card aggregating lint, coverage, and cost into a letter grade (A-F). Generates actionable suggestions.

--extra-models "provider:model1,model2;provider2:model3"

Extend the DIP108 model catalog at runtime for private or newly-released models.

test

Run scenario tests defined in .test.json files against a workflow. Auto-discovers the test file from the workflow path. Use --verbose to show execution paths. Use --coverage to report node and edge coverage across all test scenarios.

watch

Watch .dip files or directories for changes. On each change it parses, validates, and lints the affected file. Debounces rapid saves (200ms).

pack

Build a deterministic .dipx bundle from a .dip entry, walking every transitively-reachable subgraph ref. Runs structural validation (DIP001–DIP010) before packing. -o - writes to stdout; --dry-run validates and walks refs without writing. File output is atomic via os.CreateTemp + rename. Refuses symlinks anywhere in the source tree, including parent components.

By default (inline mode) every command_file:, prompt_file:, system_prompt_file:, prompt_include:, and defaults prompt_prefix_file:/prompt_suffix_file: fragment is inlined (prompt fragments compose into the agent prompt) into the packed .dip, producing a self-contained format_version 1 bundle. --no-inline instead ships those directive targets as separate entries under workflows/ and keeps the *_file: directives, so they resolve against the extracted tree exactly as in a source-tree run (format_version 2). --include <path> (repeatable, requires --no-inline) ships extra sibling files or directories — assets referenced only from inside shell bodies — as a single file or a whole directory tree; a path that resolves to a .dip is an error.

unpack

Extract a .dipx bundle into a directory atomically. Uses staging dir + rename. --force overwrites an existing destination via a backup-aside / rename-into-place / remove-aside sequence so the original is preserved if the swap fails (e.g. cross-mount EXDEV).

inputs

Print a workflow's declared inputs schema — the typed, introspectable contract a host uses to collect values before a run. --format json emits a stable array in declaration order (each entry with name, type, required, and any declared attributes); defaults are typed (a number default is a JSON number), and a workflow with no inputs emits [], never null.

inspect

Print a bundle's manifest, identity hash (SHA-256 over the manifest bytes-as-stored), and per-file checksums. The verified --format json payload also includes the entry workflow's declared inputs schema (so a host can enumerate what to collect without unpacking). Integrity-verifies by default; --no-verify skips hash verification (forensic mode).