CLI Reference

validate · fmt · export · render · md

Riferimento CLI

La CLI datro è il modo principale per convalidare, formattare, esportare ed eseguire il rendering dei file .dtro dal terminale o dalla pipeline CI.

# Install globally
npm install -g datro

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

convalidarefmtesportazionerenderemd

datro convalidare

Analizza un file .dtro, esegue tutti e quattro i passaggi di convalida e stampa la diagnostica con le posizioni file:line:col. Esce da 0 quando non sono presenti errori (sono consentiti avvisi).

# 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

Esempio di output (1 avviso, 1 suggerimento informativo, 0 errori → esci 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Diagnostica di output + statistiche IR come JSON. Utile per strumenti CI e integrazioni di editor.
`--no-info`	flag	No	—	Elimina la diagnostica a livello di informazioni `I×××` dall'output.

datro fmt

Stampa o riscrive la forma canonica di un file .dtro. Il formattatore è deterministico: lo stesso IR produce sempre lo stesso output, quindi le differenze mostrano solo i cambiamenti reali.

# 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	—	Sovrascrivi il file sul posto con il formato canonico.
`--check`	flag	No	—	Esci diverso da zero se il file non è già canonico: utilizzalo negli hook pre-commit o CI.

💡

Hook pre-commit

Aggiungi datro fmt --check arch.dtro al tuo hook pre-commit in modo che la forma canonica sia sempre impegnata. Ciò impedisce il rumore del formattatore nella revisione del codice.

datro esportazione

Converte un file .dtro convalidato in un altro formato leggibile dalla macchina. Stampa su stdout per impostazione predefinita; utilizzare --out per scrivere su un 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	—	Formato di destinazione.
`--out`	path	No	—	Scrivi l'output su questo percorso file anziché su stdout.

`dot` — Linguaggio Graphviz DOT. Collega a dot -Tsvg per il rendering personalizzato all'esterno della toolchain.
`cytoscape` — Cytoscape.js JSON. Importa direttamente in qualsiasi istanza Cytoscape per diagrammi web interattivi.
`json` — IR JSON senza perdite (oggetto DatroIR completo). Utilizzo in qualsiasi controllo CI, script o renderer personalizzato.

datro render

Rende un file .dtro in SVG o PNG pixel-perfetto tramite Graphviz. Richiede che il binario dot di Graphviz sia installato e su $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	—	Percorso del file di output. L'estensione determina il formato: `.svg` o `.png`.

ℹ️

È richiesto Graphviz

Installa Graphviz da graphviz.org/download e assicurati che dot sia sul tuo $PATH. La CLI esce con un errore chiaro se non viene trovata.

datro md

Elabora i blocchi di codice protetti Datro incorporati nei file Markdown. Due comandi secondari: check (solo convalida, non è necessario Graphviz) e render (convalida + output 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

Formato blocco incorporato

Contrassegna un blocco delimitato con l'identificatore della lingua datro. Il blocco deve includere l'intestazione magica:

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.

Blocco Datro incorporato in un file Markdown

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` — directory per i file di output. Per impostazione predefinita si trova nella stessa directory del file Markdown di input.
`--format`	string "svg""png"	No	`svg`	`md render` – formato di output.
`--json`	flag	No	—	`md check`: restituisce i risultati come JSON anziché come testo leggibile dall'uomo.
`--no-fail`	flag	No	—	Continua a elaborare i blocchi rimanenti anche quando alcuni presentano errori. Esce da `0`.

Integrazione CI

Aggiungi questi passaggi a qualsiasi pipeline CI per garantire la qualità del diagramma su ogni richiesta pull:

.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: fallisce se un diagramma non è formattato canonicamente.
validate --no-info: fallisce su qualsiasi diagnostica di gravità dell'errore.
md check --json: convalida tutti i diagrammi incorporati; L'output JSON si integra con gli strumenti di annotazione.

Prossimi passi

Leggere il Language Reference per la sintassi completa del .dtro.
Scopri come embed diagrams in Markdown con il plug-in Commento o Markdown-it.

Apri Creatore di diagrammi

Preferisci il browser? Convalida e renderizza senza installare nulla.