CLI Reference

validate · fmt · export · render · md

CLI Reference

The datro CLI is the primary way to validate, format, export, and render .dtro files from your terminal or CI pipeline.

# Install globally
npm install -g datro

# Or run without installing via npx
npx datro --version

validatefmtexportrendermd

datro validate

Parses a .dtro file, runs all four validation passes, and prints diagnostics with file:line:col locations. Exits 0 when there are no errors (warnings are allowed).

# Validate and print human-readable diagnostics
datro validate arch.dtro

# Suppress info-level hints
datro validate arch.dtro --no-info

# Output machine-readable JSON (for CI pipelines, tooling)
datro validate arch.dtro --json

✓ arch.dtro
  nodes=5  edges=6  groups=1  constraints=1
  errors=0  warnings=1  info=1

[W] arch.dtro:38:3 W602 Theme colour 'cache: #C0FFE8' has contrast ratio 1.82:1 ...
[I] arch.dtro:12:1 I003 No meta block found — consider adding one for documentation

Example output (1 warning, 1 info hint, 0 errors → exit 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Output diagnostics + IR stats as JSON. Useful for CI tools and editor integrations.
`--no-info`	flag	No	—	Suppress `I×××` info-level diagnostics from output.

datro fmt

Prints or rewrites the canonical form of a .dtro file. The formatter is deterministic: the same IR always produces the same output, so diffs show only real changes.

# Print canonical form to stdout (no file changes)
datro fmt arch.dtro

# Overwrite file with canonical form
datro fmt --write arch.dtro

# CI check — exits non-zero if file is not already canonical
datro fmt --check arch.dtro

Field	Type	Required	Default	Description
`--write`	flag	No	—	Overwrite the file in-place with canonical form.
`--check`	flag	No	—	Exit non-zero if the file is not already canonical — use in pre-commit hooks or CI.

💡

Pre-commit hook

Add `datro fmt --check arch.dtro` to your pre-commit hook so the canonical form is always committed. This prevents formatter noise in code review.

datro export

Converts a validated .dtro file to another machine-readable format. Prints to stdout by default; use --out to write to a file.

# Export to Graphviz DOT (pipe into dot for rendering)
datro export arch.dtro --to dot

# Export to Cytoscape.js JSON
datro export arch.dtro --to cytoscape --out arch.cytoscape.json

# Export the lossless JSON IR (full metadata preserved)
datro export arch.dtro --to json --out arch.ir.json

Field	Type	Required	Default	Description
`--to`	string "dot""cytoscape""json"	Yes	—	Target format.
`--out`	path	No	—	Write output to this file path instead of stdout.

`dot` — Graphviz DOT language. Pipe into dot -Tsvg for custom rendering outside the toolchain.
`cytoscape` — Cytoscape.js JSON. Import directly into any Cytoscape instance for interactive web diagrams.
`json` — Lossless JSON IR (full DatroIR object). Consume in any custom CI check, script, or renderer.

datro render

Renders a .dtro file to pixel-perfect SVG or PNG via Graphviz. Requires the dot binary from Graphviz to be installed and on $PATH.

# Render to SVG (requires Graphviz installed)
datro render arch.dtro --out diagram.svg

# Render to PNG
datro render arch.dtro --out diagram.png

Field	Type	Required	Default	Description
`--out`	path	Yes	—	Output file path. Extension determines format: `.svg` or `.png`.

ℹ️

Graphviz required

Install Graphviz from [graphviz.org/download](https://graphviz.org/download/) and ensure `dot` is on your `$PATH`. The CLI exits with a clear error if it is not found.

datro md

Processes Datro fenced code blocks embedded in Markdown files. Two sub-commands: check (validation only, no Graphviz needed) and render (validation + SVG/PNG output).

# Validate all Datro blocks embedded in a Markdown file
datro md check docs/architecture.md

# Validate and output JSON (CI-friendly)
datro md check docs/architecture.md --json

# Render all blocks to SVG files next to the Markdown file
datro md render docs/architecture.md

# Render to a specific output directory in PNG format
datro md render docs/architecture.md --out-dir public/diagrams --format png

# Continue even when some blocks have errors
datro md render docs/architecture.md --no-fail

Embedded block format

Mark a fenced block with the datro language identifier. The block must include the magic header:

Markdown

<!-- docs/architecture.md -->

# System Overview

```datro
#!DATRO 1.0

node api { type: gateway label: "API Gateway" }
node svc { type: service label: "Auth Service" }

edge api -> svc { kind: http }
```

Run `datro md render docs/architecture.md` to generate
`docs/architecture-block-1.svg` alongside this file.

Datro block embedded in a Markdown file

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` — directory for output files. Defaults to the same directory as the input Markdown file.
`--format`	string "svg""png"	No	`svg`	`md render` — output format.
`--json`	flag	No	—	`md check` — output results as JSON instead of human-readable text.
`--no-fail`	flag	No	—	Continue processing remaining blocks even when some have errors. Exits `0`.

CI integration

Add these steps to any CI pipeline to enforce diagram quality on every pull request:

.github/workflows/ci.yml

# .github/workflows/ci.yml (excerpt)
- name: Validate Datro diagrams
  run: |
    npx datro fmt --check docs/arch.dtro
    npx datro validate docs/arch.dtro --no-info
    npx datro md check docs/architecture.md --json

fmt --check — fails if a diagram is not canonically formatted.
validate --no-info — fails on any error-severity diagnostic.
md check --json — validates all embedded diagrams; JSON output integrates with annotation tools.

Next steps

Read the Language Reference for the full .dtro syntax.
Learn how to embed diagrams in Markdown with the remark or markdown-it plugin.

Open Diagram Maker

Prefer the browser? Validate and render without installing anything.