Every command in the dippin toolchain — authoring, export, analysis, and bundles.
dippin [--format text|json] <command> [args]| Flag | Values | Default | Description |
|---|---|---|---|
--format | text, json | text | Output format for diagnostics. text produces human-readable output. json produces machine-readable arrays for CI/tooling integration. |
Analysis commands:
| Code | Meaning |
|---|---|
0 | Success — no issues found, operation completed |
1 | Error — validation failures, parse errors, check-mode drift, parity mismatches |
2 | Usage error — bad flags, missing arguments, unknown command |
Bundle commands (pack, unpack, inspect) use a finer ladder so tooling can distinguish integrity failures from I/O failures:
| Code | Meaning |
|---|---|
0 | Ok |
1 | User error (parse failure, invalid input) |
2 | Bundle integrity failure (hash mismatch, manifest invalid, forbidden ZIP feature, truncation, unsupported format) |
3 | I/O error (write failure during pack, rename failure during unpack) |
4 | Cancelled (context.Canceled / context.DeadlineExceeded) |
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).
Run structural validation checks (DIP001-DIP010) on a workflow. Outputs "validation passed" or diagnostic messages. Exit code 1 if any errors found.
Run both structural validation and semantic linting (DIP001-DIP010 + DIP101-DIP151). All 61 diagnostic rules. Errors cause exit code 1; warnings alone exit 0.
--extra-models "provider:model1,model2;provider2:model3"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.
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. --migrate re-emits a file in its current format version, still formatting it to canonical form; the v1→v1 migration itself is an identity pass today — no version transform — and scaffolding for future version migrations.
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 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.
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..
Check structural parity between a DOT file and a .dip file to verify migration correctness. Reports missing nodes, different edges, and changed conditions.
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.
Estimate workflow execution cost based on model pricing tables. Per-node cost breakdown with turn and token heuristics.
Analyze edge coverage and reachability. Reports tool output extraction, edge condition matching, and termination analysis.
Health report card aggregating lint, coverage, and cost into a letter grade (A-F). Generates actionable suggestions.
--extra-models "provider:model1,model2;provider2:model3"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 .dip files or directories for changes. On each change it parses, validates, and lints the affected file. Debounces rapid saves (200ms).
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:, and system_prompt_file: body is inlined 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.
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).
Print a bundle's manifest, identity hash (SHA-256 over the manifest bytes-as-stored), and per-file checksums. Integrity-verifies by default; --no-verify skips hash verification (forensic mode).