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

растауfmtэкспорткөрсетумд

растау

.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×××` ақпарат деңгейіндегі диагностиканы басу.

datro 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 файлын басқа машина оқылатын пішімге түрлендіреді. Әдепкі бойынша stdout басып шығарады; файлға жазу үшін --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 данасына тікелей импорттаңыз.
`json` — Жоғалмайтын JSON IR (толық DatroIR нысаны). Кез келген реттелетін CI тексеруінде, сценарийде немесе рендерерде тұтыну.

датро көрсету

.dtro файлын Graphviz арқылы мінсіз SVG немесе PNG форматына көрсетеді. Graphviz қолданбасынан dot екілік файлының орнатылуын және $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 ішінен Graphviz орнатыңыз және dot сіздің $PATH жүйесінде екеніне көз жеткізіңіз. Егер ол табылмаса, CLI анық қатемен шығады.

datro md

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 шығысы аннотация құралдарымен біріктірілген.

Келесі қадамдар

Толық .dtro синтаксисі үшін Language Reference оқыңыз.
Ескертпе немесе markdown-it плагині арқылы embed diagrams in Markdown әдісін үйреніңіз.

Диаграмма жасау құралын ашыңыз

Браузерді қалайсыз ба? Ештеңені орнатусыз растаңыз және көрсетіңіз.