Skip to content
DiagramPilot

Public Documentation

DiagramPilot Public Documentation is for developers and AI coding agents using DiagramPilot in their own repositories.

DiagramPilot Source Files are YAML-only. The CLI supports local agent authoring loops with create, inspect, format, lint, watch, configured outputs, fixed Output Profiles, SVG/PNG rendering, and Mermaid/D2/DOT export. Local MCP clients can add the optional @diagrampilot/mcp adapter package.

Start with the Checkout Demo Project quickstart:

Core public references:

Current CLI commands:

Terminal window
diagrampilot init
diagrampilot init --docs
diagrampilot init --config
diagrampilot create docs/architecture.dp.yaml --template architecture
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
diagrampilot check
diagrampilot inspect
diagrampilot generate
diagrampilot watch docs
diagrampilot icons list
diagrampilot icons search database
diagrampilot check docs --json
diagrampilot inspect docs --json
diagrampilot validate docs/architecture.dp.yaml
diagrampilot validate docs/architecture.dp.yaml --json
diagrampilot fix docs/architecture.dp.yaml --json
diagrampilot fix docs/architecture.dp.yaml --fallback-icon lucide:database
diagrampilot lint docs/architecture.dp.yaml
diagrampilot lint docs/architecture.dp.yaml --json
diagrampilot format docs/architecture.dp.yaml
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot render docs/architecture.dp.yaml --view runtime --out docs/architecture-runtime.svg
diagrampilot render docs/architecture.dp.yaml --group checkout_runtime --out docs/architecture-checkout-runtime.svg
diagrampilot render docs/architecture.dp.yaml --around orders_service --depth 1 --out docs/architecture-orders-service.svg
diagrampilot render docs/architecture.dp.yaml --hide-edge-labels --out docs/architecture-overview.svg
diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
diagrampilot export docs/architecture.dp.yaml --format mermaid
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
diagrampilot export docs/architecture.dp.yaml --format d2 --out docs/architecture.d2
diagrampilot export docs/architecture.dp.yaml --format dot --out docs/architecture.dot

Use init --docs only when a repository intentionally wants managed local agent docs. Use init --config only when a repository intentionally wants diagrampilot.config.yaml. Use create to write a starter *.dp.yaml source from the maintained architecture, flow, package-map, system-context, or service-map templates. Use check as the read-only repo review/CI command. Use inspect for read-only source inventory, topology, Stable IDs, and artifact expectations before editing. Use lint <path> for read-only readability warnings on one valid source; it differs from validate source correctness and check artifact freshness. render requires --out, defaults to SVG, supports --format svg|png, accepts --view <view-id> for focused projections declared in the source file, renders one group with --group, renders node neighborhoods with --around and --depth, and can hide edge labels for one-off overview artifacts with --hide-edge-labels. Configured outputs can use profile: clean, profile: compact, profile: overview, or profile: presentation; use overview when dense review artifacts need less edge-label noise. export prints to stdout by default, writes a file only when --out is provided, and accepts --view <view-id> for Mermaid, D2, and DOT projections. import <input> --format mermaid|d2|dot --out <path> converts supported diagram text into a new DiagramPilot Source File, refuses existing outputs unless --force is present, and reports preserved, approximated, and dropped constructs in text or JSON with --json. format <path> validates one *.dp.yaml source and rewrites it in canonical YAML key order; YAML comments may be removed or moved. fix <path> --json plans deterministic source-only repairs without writing, and fix <path> writes only the DiagramPilot Source File after post-fix validation succeeds. watch [path] watches *.dp.yaml and diagrampilot.config.yaml, debounces changes, checks first, and generates only when source/config state is valid. The optional @diagrampilot/mcp adapter launches the MCP stdio server as diagrampilot-mcp; keeping it separate makes routine CLI/CI installs smaller and leaves adapter iteration independent. Use icons list and icons search <query> to discover packaged lucide:* icon references locally.