CLI Reference

validate · fmt · export · render · md

Справочник по интерфейсу командной строки

Интерфейс командной строки datro — это основной способ проверки, форматирования, экспорта и рендеринга файлов .dtro из вашего терминала или конвейера CI.

# Install globally
npm install -g datro

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

подтвердитьФМТэкспортоказыватьМэриленд

данные проверки

Анализирует файл .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	—	Вывод диагностики + IR-статистики в формате JSON. Полезно для инструментов CI и интеграции редакторов.
`--no-info`	flag	No	—	Подавить диагностику информационного уровня `I×××` из вывода.

датро фмт

Печатает или перезаписывает каноническую форму файла .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	—	Запишите вывод в этот путь к файлу вместо стандартного вывода.

`dot` — язык Graphviz DOT. Перейдите в dot -Tsvg для пользовательского рендеринга вне цепочки инструментов.
`cytoscape` — Cytoscape.js JSON. Импортируйте непосредственно в любой экземпляр Cytoscape для интерактивных веб-диаграмм.
`json` — JSON IR без потерь (полный объект DatroIR). Используйте в любой пользовательской проверке CI, скрипте или средстве визуализации.

датро рендеринг

Преобразует файл .dtro в SVG или PNG с точностью до пикселя с помощью Graphviz. Требуется установка двоичного файла dot из Graphviz на $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	—	Путь к выходному файлу. Расширение определяет формат: `.svg` или `.png`.

ℹ️

Требуется графвиз

Установите Graphviz из graphviz.org/download и убедитесь, что dot установлен на вашем $PATH. Если он не найден, CLI завершает работу с явной ошибкой.

Датро Мэриленд

Обрабатывает изолированные блоки кода Datro, встроенные в файлы Markdown. Две подкоманды: 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.

Блок Datro, встроенный в файл Markdown

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.
Узнайте, как embed diagrams in Markdown с помощью плагина примечаний или уценки.

Открыть конструктор диаграмм

Предпочитаете браузер? Проверка и рендеринг без установки чего-либо.