CLI Reference

validate · fmt · export · render · md

Referência CLI

A CLI datro é a principal forma de validar, formatar, exportar e renderizar arquivos .dtro do seu terminal ou pipeline de CI.

# Install globally
npm install -g datro

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

validarfmtexportarrenderizarmédico

validação de dados

Analisa um arquivo .dtro, executa todas as quatro etapas de validação e imprime diagnósticos com locais file:line:col. Sai de 0 quando não há erros (avisos são permitidos).

# 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

Exemplo de saída (1 aviso, 1 dica de informação, 0 erros → saída 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Diagnóstico de saída + estatísticas de IR como JSON. Útil para ferramentas de CI e integrações de editores.
`--no-info`	flag	No	—	Suprima o diagnóstico de nível de informação `I×××` da saída.

datro fmt

Imprime ou reescreve a forma canônica de um arquivo .dtro. O formatador é determinístico: o mesmo IR sempre produz a mesma saída, então as diferenças mostram apenas alterações reais.

# 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	—	Substitua o arquivo local pela forma canônica.
`--check`	flag	No	—	Saia diferente de zero se o arquivo ainda não for canônico — use em ganchos de pré-confirmação ou CI.

💡

Gancho de pré-confirmação

Adicione datro fmt --check arch.dtro ao seu gancho de pré-confirmação para que a forma canônica seja sempre confirmada. Isso evita ruído do formatador na revisão do código.

exportação de dados

Converte um arquivo .dtro validado em outro formato legível por máquina. Imprime em stdout por padrão; use --out para gravar em um arquivo.

# 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	—	Grave a saída neste caminho de arquivo em vez de stdout.

`dot` — linguagem Graphviz DOT. Canalize para dot -Tsvg para renderização personalizada fora do conjunto de ferramentas.
`cytoscape` — Cytoscape.js JSON. Importe diretamente para qualquer instância do Cytoscape para diagramas web interativos.
`json` — JSON IR sem perdas (objeto DatroIR completo). Consumir em qualquer verificação, script ou renderizador de CI personalizado.

renderização de dados

Renderiza um arquivo .dtro em SVG ou PNG com pixels perfeitos via Graphviz. Requer que o binário dot do Graphviz seja instalado e em $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	—	Caminho do arquivo de saída. A extensão determina o formato: `.svg` ou `.png`.

ℹ️

Graphviz obrigatório

Instale o Graphviz de graphviz.org/download e certifique-se de que dot esteja em seu $PATH. A CLI sai com um erro claro se não for encontrada.

datro md

Processa blocos de código protegidos Datro incorporados em arquivos Markdown. Dois subcomandos: check (somente validação, sem necessidade de Graphviz) e render (validação + saída 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 bloco incorporado

Marque um bloco cercado com o identificador de idioma datro. O bloco deve incluir o cabeçalho 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.

Bloco Datro incorporado em um arquivo Markdown

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` — diretório para arquivos de saída. O padrão é o mesmo diretório do arquivo Markdown de entrada.
`--format`	string "svg""png"	No	`svg`	`md render` — formato de saída.
`--json`	flag	No	—	`md check` — gera resultados como JSON em vez de texto legível por humanos.
`--no-fail`	flag	No	—	Continue processando os blocos restantes mesmo quando alguns apresentarem erros. Sai de `0`.

Integração de CI

Adicione estas etapas a qualquer pipeline de CI para impor a qualidade do diagrama em cada solicitação 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 — falha se um diagrama não for formatado canonicamente.
validate --no-info — falha em qualquer diagnóstico de gravidade de erro.
md check --json — valida todos os diagramas incorporados; A saída JSON integra-se com ferramentas de anotação.

Próximas etapas

Leia o Language Reference para obter a sintaxe completa do .dtro.
Aprenda como embed diagrams in Markdown com o plugin remark ou markdown-it.

Abra o Criador de Diagramas

Prefere o navegador? Valide e renderize sem instalar nada.