CLI Reference

validate · fmt · export · render · md

Referencia CLI

La CLI datro es la forma principal de validar, formatear, exportar y renderizar archivos .dtro desde su terminal o canal de CI.

# Install globally
npm install -g datro

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

validarfmtexportarrenderizarmédico

validar datro

Analiza un archivo .dtro, ejecuta los cuatro pases de validación e imprime diagnósticos con ubicaciones file:line:col. Sale de 0 cuando no hay errores (se permiten advertencias).

# 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

Salida de ejemplo (1 advertencia, 1 sugerencia de información, 0 errores → salir 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Diagnóstico de salida + estadísticas de IR como JSON. Útil para herramientas de CI e integraciones de editores.
`--no-info`	flag	No	—	Suprime los diagnósticos de nivel de información `I×××` de la salida.

datro fmt

Imprime o reescribe la forma canónica de un archivo .dtro. El formateador es determinista: el mismo IR siempre produce la misma salida, por lo que las diferencias muestran solo cambios reales.

# 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	—	Sobrescriba el archivo in situ con forma canónica.
`--check`	flag	No	—	Salga de un valor distinto de cero si el archivo aún no es canónico; utilícelo en ganchos de confirmación previa o CI.

💡

Gancho de confirmación previa

Agregue datro fmt --check arch.dtro a su gancho de confirmación previa para que la forma canónica siempre esté confirmada. Esto evita el ruido del formateador en la revisión del código.

exportación de datro

Convierte un archivo .dtro validado a otro formato legible por máquina. Imprime en salida estándar de forma predeterminada; use --out para escribir en un archivo.

# 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 de destino.
`--out`	path	No	—	Escriba la salida en esta ruta de archivo en lugar de en la salida estándar.

`dot` — Lenguaje Graphviz DOT. Ingrese a dot -Tsvg para una representación personalizada fuera de la cadena de herramientas.
`cytoscape` — Cytoscape.js JSON. Importe directamente a cualquier instancia de Cytoscape para obtener diagramas web interactivos.
`json` — JSON IR sin pérdidas (objeto DatroIR completo). Consuma en cualquier verificación, secuencia de comandos o renderizador de CI personalizado.

renderizado de datro

Representa un archivo .dtro en SVG o PNG con píxeles perfectos a través de Graphviz. Requiere que el binario dot de Graphviz esté instalado y en $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	—	Ruta del archivo de salida. La extensión determina el formato: `.svg` o `.png`.

ℹ️

Se requiere Graphviz

Instale Graphviz desde graphviz.org/download y asegúrese de que dot esté en su $PATH. La CLI sale con un error claro si no se encuentra.

datro md

Procesa bloques de código protegidos de Datro incrustados en archivos Markdown. Dos subcomandos: check (solo validación, no se necesita Graphviz) y render (validación + salida 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 de bloque incrustado

Marque un bloque vallado con el identificador de idioma datro. El bloque debe incluir el encabezado mágico:

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.

Bloque Datro incrustado en un archivo Markdown

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` — directorio para archivos de salida. El valor predeterminado es el mismo directorio que el archivo Markdown de entrada.
`--format`	string "svg""png"	No	`svg`	`md render` — formato de salida.
`--json`	flag	No	—	`md check` — genera resultados como JSON en lugar de texto legible por humanos.
`--no-fail`	flag	No	—	Continúe procesando los bloques restantes incluso cuando algunos tengan errores. Sale de `0`.

Integración de CI

Agregue estos pasos a cualquier canal de CI para imponer la calidad del diagrama en cada solicitud de extracción:

.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: falla si un diagrama no tiene formato canónico.
validate --no-info — falla en cualquier diagnóstico de gravedad de error.
md check --json — valida todos los diagramas integrados; La salida JSON se integra con herramientas de anotación.

Próximos pasos

Lea el Language Reference para conocer la sintaxis completa de .dtro.
Aprenda a embed diagrams in Markdown con el complemento comentario o markdown-it.

Creador de diagramas abiertos

¿Prefieres el navegador? Valida y renderiza sin instalar nada.