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-DIP009) on a workflow. Outputs "validation passed" or diagnostic messages. Exit code 1 if any errors found.
Run both structural validation and semantic linting (DIP001-DIP009 + DIP101-DIP134). All 40 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.
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 a workflow file for changes and re-run validation automatically. Use --lint to include semantic linting on each change, or --test to re-run scenario tests. Debounces rapid saves.
Build a deterministic .dipx bundle from a .dip entry, walking every transitively-reachable subgraph ref. Runs structural validation (DIP001–DIP009) 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.
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. Always integrity-verifies in v1.