CLI Reference

validate · fmt · export · render · md

Reference til CLI

datro CLI er den primære måde at validerere, formatere, eksportere og rendere .dtro-filer fra din terminal eller CI-pipeline.

# Install globally
npm install -g datro

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

validererFmteksportafleveringmd

datro-valideret

Parserer en .dtro-fil, kører alle fire valideringspass og udskriver diagnostik med file:line:col-steder. Forlader 0, når der ikke er nogen fejl (varsel er tilladt).

# 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

Eksempel output (1 advarsel, 1 info hint, 0 fejl → exit 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Udgangsdiagnostik + IR-statistik som JSON. Gode til CI-værktøjer og editorintegrationer.
`--no-info`	flag	No	—	Slip `I×××` info-niveau diagnostik fra udgangen.

datro fmt

Print eller omskrive den kanoniske form af en .dtro fil. Formateren er deterministisk: den samme IR producerer altid den samme udgang, så diffs viser kun reelle ændringer.

# 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	—	Overskrive filen med kanonisk form.
`--check`	flag	No	—	Udgang ikke-null, hvis filen ikke allerede er kanonisk brug i for forpligtelseshakker eller CI.

💡

Forhåndsforpligtelseshak

Tilføj datro fmt --check arch.dtro til din for-kommitting kruk, så den kanoniske form altid er forpligtet. Dette forhindrer formatter støj i kode gennemgang.

datroeksport

Omdanner en valideret .dtro-fil til et andet maskinlæsbart format. Printer til stdout som standard; brug --out til at skrive til en fil.

# 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	—	- Målformat.
`--out`	path	No	—	Skriv output til denne filvej i stedet for stdout.

`dot` Graphviz DOT sprog. Pipe ind i dot -Tsvg til brugerdefineret rendering uden for værktøjskæden.
`cytoscape` Cytoscape.js JSON. Import direkte til enhver Cytoscape-instans for interaktive webdiagrammer.
`json` Lossless JSON IR (fuldt DatroIR objekt). Forbrug i enhver brugerdefineret CI-kontrol, script eller renderer.

datro-renderet

Renderer en .dtro-fil til pixel-perfekte SVG eller PNG via Graphviz. Forlanger, at dot- binären fra Graphviz installeres og på $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	—	Udgangsfilens vej. Udvidelsen bestemmer formatet: `.svg` eller `.png`.

ℹ️

Graphviz kræves

Installer Graphviz fra graphviz.org/download og sørg for at dot er på din $PATH. CLI udgår med en klar fejl, hvis den ikke findes.

datro md

Processer Datro-hammerede kodeblokker indlejret i Markdown-filer. To underkommandoer: check (kun validation, ingen Graphviz nødvendig) og 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

Indlejret blokformat

Markér et hegnet blok med sprogidentifikatoren datro. Blokken skal indeholde den magiske overskrift:

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-blok indlejret i en Markdown-fil

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` katalog til udgangsdata. Standardregister til samme katalog som indgangsdata Markdown.
`--format`	string "svg""png"	No	`svg`	`md render` udgangsformat.
`--json`	flag	No	—	`md check` udgangsresultater som JSON i stedet for tekst, der kan læses af mennesker.
`--no-fail`	flag	No	—	Fortsæt med at behandle de resterende blokke, selv når nogle har fejl. Udgår `0`.

Integration af CI

Tilføj disse trin til enhver CI-rørledning for at sikre diagramkvaliteten på hver trækforespørgsel:

.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 fejler, hvis et diagram ikke er kanonisk formateret.
validate --no-info fejler i enhver fejl alvorlighedsdiagnostik.
md check --json validerer alle indlejrede diagrammer; JSON-udgang integreres med annotationsværktøjer.

Næste trin

Læs Talsreference for den fulde .dtro syntax.
Lær at indlejre diagrammer i Markdown med bemærkningen eller markdown-it plugin.

Åben diagrammaker

foretrækker du browseren? Validerer og renderer uden at installere noget.