CLI Reference

validate · fmt · export · render · md

Référence CLI

La CLI datro est le principal moyen de valider, formater, exporter et restituer les fichiers .dtro à partir de votre terminal ou de votre pipeline CI.

# Install globally
npm install -g datro

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

validerfmtexporterrendremdr

validation des données

Analyse un fichier .dtro, exécute les quatre passes de validation et imprime les diagnostics avec les emplacements file:line:col. Quitte 0 lorsqu'il n'y a aucune erreur (les avertissements sont autorisés).

# 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

Exemple de sortie (1 avertissement, 1 indice d'information, 0 erreur → sortie 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Diagnostics de sortie + statistiques IR au format JSON. Utile pour les outils CI et les intégrations d'éditeurs.
`--no-info`	flag	No	—	Supprime les diagnostics au niveau des informations `I×××` de la sortie.

données fmt

Imprime ou réécrit la forme canonique d'un fichier .dtro. Le formateur est déterministe : le même IR produit toujours le même résultat, donc les différences ne montrent que les changements réels.

# 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	—	Écrasez le fichier sur place avec une forme canonique.
`--check`	flag	No	—	Quittez une valeur différente de zéro si le fichier n'est pas déjà canonique - à utiliser dans les hooks de pré-validation ou CI.

💡

Hook de pré-validation

Ajoutez datro fmt --check arch.dtro à votre hook de pré-validation afin que la forme canonique soit toujours validée. Cela évite le bruit du formateur lors de la révision du code.

exportation de données

Convertit un fichier .dtro validé dans un autre format lisible par machine. Imprime sur la sortie standard par défaut ; utilisez --out pour écrire dans un fichier.

# 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	—	Format cible.
`--out`	path	No	—	Écrivez la sortie dans ce chemin de fichier au lieu de la sortie standard.

`dot` — Langage Graphviz DOT. Dirigez-vous vers dot -Tsvg pour un rendu personnalisé en dehors de la chaîne d'outils.
`cytoscape` — Cytoscape.js JSON. Importez directement dans n'importe quelle instance Cytoscape pour des diagrammes Web interactifs.
`json` — JSON IR sans perte (objet DatroIR complet). À consommer dans n'importe quelle vérification, script ou moteur de rendu CI personnalisé.

rendu des données

Rend un fichier .dtro au format SVG ou PNG au pixel près via Graphviz. Nécessite l'installation du binaire dot de Graphviz et sur $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	—	Chemin du fichier de sortie. L'extension détermine le format : `.svg` ou `.png`.

ℹ️

Visualisation graphique requise

Installez Graphviz à partir de graphviz.org/download et assurez-vous que dot est sur votre $PATH. La CLI se termine avec une erreur claire si elle n'est pas trouvée.

datro md

Traite les blocs de code clôturés Datro intégrés dans les fichiers Markdown. Deux sous-commandes : check (validation uniquement, aucun Graphviz nécessaire) et render (validation + sortie SVG/PNG).

# 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

Format de bloc intégré

Marquez un bloc clôturé avec l'identifiant de langue datro. Le bloc doit inclure l'en-tête magique :

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.

Bloc Datro intégré dans un fichier Markdown

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` — répertoire pour les fichiers de sortie. La valeur par défaut est le même répertoire que le fichier Markdown d'entrée.
`--format`	string "svg""png"	No	`svg`	`md render` — format de sortie.
`--json`	flag	No	—	`md check` — affiche les résultats au format JSON au lieu de texte lisible par l'homme.
`--no-fail`	flag	No	—	Continuez à traiter les blocs restants même si certains contiennent des erreurs. Quitte `0`.

Intégration CI

Ajoutez ces étapes à n’importe quel pipeline CI pour appliquer la qualité des diagrammes à chaque demande d’extraction :

.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 — échoue si un diagramme n'est pas formaté canoniquement.
validate --no-info — échoue lors de tout diagnostic de gravité d'erreur.
md check --json — valide tous les diagrammes intégrés ; La sortie JSON s'intègre aux outils d'annotation.

Prochaines étapes

Lisez le Language Reference pour connaître la syntaxe complète de .dtro.
Apprenez à embed diagrams in Markdown avec le plugin remarque ou markdown-it.

Ouvrir le créateur de diagrammes

Vous préférez le navigateur ? Validez et effectuez le rendu sans rien installer.