CLI Reference

validate · fmt · export · render · md

CLI 参考

datro CLI 是从终端或 CI 管道验证、格式化、导出和渲染 .dtro 文件的主要方式。

# Install globally
npm install -g datro

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

验证FMMT出口渲染MD

达特罗验证

解析 .dtro 文件，运行所有四次验证，并使用 file:line:col 位置打印诊断信息。当没有错误时退出 0（允许警告）。

# 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

输出示例（1 个警告、1 个信息提示、0 个错误 → 退出 0）

Field	Type	Required	Default	Description
`--json`	flag	No	—	以 JSON 形式输出诊断 + IR 统计数据。对于 CI 工具和编辑器集成很有用。
`--no-info`	flag	No	—	抑制输出中的 `I×××` 信息级诊断。

达特罗FMT

打印或重写 .dtro 文件的规范形式。格式化程序是确定性的：相同的 IR 始终产生相同的输出，因此差异仅显示真实的更改。

# 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	—	使用规范形式就地覆盖文件。
`--check`	flag	No	—	如果文件尚未规范，则退出非零 — 在预提交挂钩或 CI 中使用。

💡

预提交挂钩

将 datro fmt --check arch.dtro 添加到预提交挂钩中，以便始终提交规范形式。这可以防止代码审查中的格式化噪音。

达特罗出口

将经过验证的 .dtro 文件转换为另一种机器可读格式。默认打印到标准输出；使用 --out 写入文件。

# 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	—	目标格式。
`--out`	path	No	—	将输出写入此文件路径而不是 stdout。

`dot` — Graphviz DOT 语言。通过管道传输到 dot -Tsvg 以在工具链外部进行自定义渲染。
`cytoscape` — Cytoscape.js JSON。直接导入任何 Cytoscape 实例以获取交互式 Web 图表。
`json` — 无损 JSON IR（完整 DatroIR 对象）。在任何自定义 CI 检查、脚本或渲染器中使用。

达特罗渲染

通过 Graphviz 将 .dtro 文件渲染为像素完美的 SVG 或 PNG。需要在 $PATH 上安装来自 Graphviz 的 dot 二进制文件。

# 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	—	输出文件路径。扩展名决定格式：`.svg` 或 `.png`。

ℹ️

需要 Graphviz

从 graphviz.org/download 安装 Graphviz 并确保 dot 在您的 $PATH 上。如果未找到，CLI 将退出并显示明显错误。

达特罗医学博士

处理嵌入在 Markdown 文件中的 Datro 防护代码块。两个子命令：check（仅验证，不需要 Graphviz）和 render（验证 + 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

嵌入块格式

使用 datro 语言标识符标记受隔离的块。该块必须包含魔术头：

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.

嵌入 Markdown 文件中的 Datro 块

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` — 输出文件的目录。默认为与输入 Markdown 文件相同的目录。
`--format`	string "svg""png"	No	`svg`	`md render` — 输出格式。
`--json`	flag	No	—	`md check` — 将结果输出为 JSON，而不是人类可读的文本。
`--no-fail`	flag	No	—	即使有些块有错误，也要继续处理剩余的块。退出`0`。

CI集成

将这些步骤添加到任何 CI 管道中，以增强每个拉取请求的图表质量：

.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 — 如果图表未采用规范格式，则会失败。
validate --no-info — 任何错误严重性诊断均失败。
md check --json — 验证所有嵌入图； JSON 输出与注释工具集成。

后续步骤

阅读 Language Reference 了解完整的 .dtro 语法。
了解如何使用 remark 或 markdown-it 插件 embed diagrams in Markdown。

打开图表制作器

更喜欢浏览器？无需安装任何东西即可验证和渲染。