CLI Reference

validate · fmt · export · render · md

CLI-referentie

De datro-CLI is de primaire mogelijkheid, .dtro-Files van uw terminal of CI-pipeline valideren, formateren, exporteren en renderen.

# Install globally
npm install -g datro

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

validerenfmtuitvoerenuitvoerenmd

datro valideren

Analyseert een .dtro-Een dossier, die alle vier de validatieprocessen uitvoert en diagnoses prints met file:line:col-Verzamelplaatsen. Beëindigd 0, als er geen fouten zijn (waarschuwingen zijn toegestaan)).

# 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

Voorbeeld uitgave (1 waarschuwing, 1 inleiding, 0 fouten → exit 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Geef diagnoses en IR-statistieken uit als JSON. Gebruikbaar voor CI-tools en editor-integratie.
`--no-info`	flag	No	—	Onderdruk de diagnose op informatie-niveau `I×××` uit de uitgave.

datro fmt

Drukt of schrijft de canonische vorm van een .dtro-Doel om. De formater is deterministisch: dezelfde IR produceert altijd dezelfde uitgave, zodat Diffs alleen echte veranderingen tonen.

# 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	—	Schrijf het bestand rechtstreeks over met de canonische vorm.
`--check`	flag	No	—	Exit niet gelijk aan nul als het bestand niet al kanonisch is in pre-commit hooks of CI gebruiken.

💡

Pre-commit-hook

Voeg toe datro fmt --check arch.dtro om je pre-commit hook toe te voegen, zodat de canonische vorm altijd wordt vastgelegd. Dit voorkomt formateringsgeluiden bij codecontrole.

Datro-export

Convert een gevalideerde .dtro-Bestand in een ander machineleesbaar formaat. Print standaard op stdout; gebruik --out, om in een bestand te schrijven.

# 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	—	Doelformaat.
`--out`	path	No	—	Schrijf de uitgave in dit bestandspad in plaats van stdout.

`dot` – Graphviz DOT-Sprache. Verwezenlijking dot -Tsvg voor custom rendering buiten de toolchain.
`cytoscape` – Cytoscape.js JSON. Direct importeren naar elke cytoscape voor interactieve webdiagrammen.
`json` – Verliesvrij JSON IR (volledig) DatroIR-Voorwerp). Gebruik ze in elke gebruikersgeschikte CI-test, elke script of elke renderer.

Datro-rendering

Geef een .dtro-Graphviz-bestand in pixeljuiste SVG of PNG. Vervolgt de installatie dot-Binary file van Graphviz en op $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	—	Weg van de uitgavebestand. De uitbreiding bepaalt het formaat: `.svg` of `.png`.

ℹ️

Grafiek nodig

Installeer Graphviz van [graphviz.org/download]](https://graphviz.org/download/) en zorg ervoor dat dot Op de $PATH is. Het CLI wordt beëindigd met een duidelijke fout als het niet wordt gevonden.

datro md

Verwerk datro-fenced code blocks die zijn ingebed in markdown bestanden. Twee subcommandos: check (alleen validatie, geen grafiek nodig) en render (Validering + SVG/PNG-uitgave).

# 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

Geïntegreerd blokformaat

Merk een omheind blok met de spraakherkenning datro. Het blok moet de Magic Header bevatten.:

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 ingebed in een markdown-bestand

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` – Lijst voor uitgiftebestanden. standaard hetzelfde directory als het input-markdown-bestand.
`--format`	string "svg""png"	No	`svg`	`md render` – Uitgifteformaat.
`--json`	flag	No	—	`md check` – Resultaten als JSON in plaats van menselijk leesbaar.
`--no-fail`	flag	No	—	Verwerk de overgebleven blokken verder, ook al zijn er fouten. Beëindigd `0`.

IC-integratie

Voeg deze stappen toe aan elke CI-pipeline om de grafiekkwaliteit op te dwingen bij elke trekvraag.:

.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 – mislukt wanneer een schema niet kanonisch is geformateerd.
validate --no-info – mislukt bij elke diagnose van ernstige fouten.
md check --json – Alle ingebedde grafieken wordt gevalideerd; de JSON-uitgave kan worden geïntegreerd in notatietools.

Volgende stappen

Lees Language Reference voor de volledige tekst .dtro-Syntax.
Leer hoe je het doet met de Remark- of Markdown-it-plugin [embed diagrams in Markdown].

Maak de diagrammaker open

Voorkeur voor de browser? Valideren en renderen zonder iets te installeren.