CLI Reference

validate · fmt · export · render · md

CLI-Referenz

Die datro-CLI ist die primäre Möglichkeit, .dtro-Dateien von Ihrem Terminal oder Ihrer CI-Pipeline aus zu validieren, zu formatieren, zu exportieren und zu rendern.

# Install globally
npm install -g datro

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

validierenfmtexportierenrendernmd

datro validieren

Analysiert eine .dtro-Datei, führt alle vier Validierungsdurchläufe aus und druckt Diagnosen mit file:line:col-Speicherorten. Beendet 0, wenn keine Fehler vorliegen (Warnungen sind zulässig).

# 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

Beispielausgabe (1 Warnung, 1 Infohinweis, 0 Fehler → Exit 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Geben Sie Diagnosen und IR-Statistiken als JSON aus. Nützlich für CI-Tools und Editor-Integrationen.
`--no-info`	flag	No	—	Unterdrücken Sie die Diagnose auf Infoebene `I×××` aus der Ausgabe.

datro fmt

Druckt oder schreibt die kanonische Form einer .dtro-Datei um. Der Formatierer ist deterministisch: Derselbe IR erzeugt immer die gleiche Ausgabe, sodass Diffs nur echte Änderungen zeigen.

# 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	—	Überschreiben Sie die Datei direkt mit der kanonischen Form.
`--check`	flag	No	—	Exit ungleich Null, wenn die Datei nicht bereits kanonisch ist – in Pre-Commit-Hooks oder CI verwenden.

💡

Pre-Commit-Hook

Fügen Sie datro fmt --check arch.dtro zu Ihrem Pre-Commit-Hook hinzu, damit die kanonische Form immer festgeschrieben wird. Dies verhindert Formatierungsgeräusche bei der Codeüberprüfung.

Datro-Export

Konvertiert eine validierte .dtro-Datei in ein anderes maschinenlesbares Format. Druckt standardmäßig auf stdout; Verwenden Sie --out, um in eine Datei zu schreiben.

# 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	—	Zielformat.
`--out`	path	No	—	Schreiben Sie die Ausgabe in diesen Dateipfad statt in stdout.

`dot` – Graphviz DOT-Sprache. Weiterleiten an dot -Tsvg für benutzerdefiniertes Rendering außerhalb der Toolchain.
`cytoscape` – Cytoscape.js JSON. Direkter Import in jede Cytoscape-Instanz für interaktive Webdiagramme.
`json` – Verlustfreie JSON IR (vollständiges DatroIR-Objekt). Nutzen Sie sie in jeder benutzerdefinierten CI-Prüfung, jedem Skript oder jedem Renderer.

Datro-Rendering

Rendert eine .dtro-Datei über Graphviz in pixelgenaues SVG oder PNG. Erfordert die Installation der dot-Binärdatei von Graphviz und auf $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	—	Pfad der Ausgabedatei. Die Erweiterung bestimmt das Format: `.svg` oder `.png`.

ℹ️

Graphviz erforderlich

Installieren Sie Graphviz von graphviz.org/download und stellen Sie sicher, dass sich dot auf Ihrem $PATH befindet. Die CLI wird mit einem eindeutigen Fehler beendet, wenn sie nicht gefunden wird.

datro md

Verarbeitet Datro-Fenced-Codeblöcke, die in Markdown-Dateien eingebettet sind. Zwei Unterbefehle: check (nur Validierung, kein Graphviz erforderlich) und render (Validierung + SVG/PNG-Ausgabe).

# 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

Eingebettetes Blockformat

Markieren Sie einen umzäunten Block mit der Sprachkennung datro. Der Block muss den Magic-Header enthalten:

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 eingebettet in eine Markdown-Datei

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` – Verzeichnis für Ausgabedateien. Standardmäßig dasselbe Verzeichnis wie die Eingabe-Markdown-Datei.
`--format`	string "svg""png"	No	`svg`	`md render` – Ausgabeformat.
`--json`	flag	No	—	`md check` – Ergebnisse als JSON statt als für Menschen lesbaren Text ausgeben.
`--no-fail`	flag	No	—	Verarbeiten Sie die verbleibenden Blöcke weiter, auch wenn einige Fehler aufweisen. Beendet `0`.

CI-Integration

Fügen Sie diese Schritte zu jeder CI-Pipeline hinzu, um die Diagrammqualität bei jeder Pull-Anfrage zu erzwingen:

.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 – schlägt fehl, wenn ein Diagramm nicht kanonisch formatiert ist.
validate --no-info – schlägt bei jeder Fehlerschwerediagnose fehl.
md check --json – validiert alle eingebetteten Diagramme; Die JSON-Ausgabe lässt sich in Anmerkungstools integrieren.

Nächste Schritte

Lesen Sie Language Reference für die vollständige .dtro-Syntax.
Erfahren Sie, wie Sie mit dem Remark- oder Markdown-it-Plugin embed diagrams in Markdown machen.

Öffnen Sie den Diagrammersteller

Bevorzugen Sie den Browser? Validieren und rendern Sie, ohne etwas zu installieren.