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수출세우다MD

데이터로 검증

.dtro 파일을 구문 분석하고, 4개의 검증 단계를 모두 실행하고, 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×××` 정보 수준 진단을 억제합니다.

다트로 fmt

.dtro 파일의 표준 형식을 인쇄하거나 다시 작성합니다. 포맷터는 결정적입니다. 동일한 IR은 항상 동일한 출력을 생성하므로 diff는 실제 변경 사항만 표시합니다.

# 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	—	파일이 아직 정식이 아닌 경우 0이 아닌 값으로 종료합니다. 사전 커밋 후크 또는 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 검사, 스크립트 또는 렌더러에서 사용합니다.

데이터로 렌더

Graphviz를 통해 .dtro 파일을 픽셀이 완벽한 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를 찾을 수 없으면 명확한 오류와 함께 종료됩니다.

다트로 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를 읽어보세요.
Remark 또는 markdown-it 플러그인을 사용하여 embed diagrams in Markdown하는 방법을 알아보세요.

오픈 다이어그램 메이커

브라우저를 선호하시나요? 아무것도 설치하지 않고 검증하고 렌더링합니다.