CLI Reference

validate · fmt · export · render · md

Referensi CLI

CLI datro adalah cara utama untuk memvalidasi, memformat, mengekspor, dan merender file .dtro dari terminal atau pipeline CI Anda.

# Install globally
npm install -g datro

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

memvalidasifmtekspormemberikanmd

validasi data

Mengurai file .dtro, menjalankan keempat jalur validasi, dan mencetak diagnostik dengan lokasi file:line:col. Keluar dari 0 ketika tidak ada kesalahan (peringatan diperbolehkan).

# 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

Contoh keluaran (1 peringatan, 1 petunjuk info, 0 kesalahan → keluar 0)

Field	Type	Required	Default	Description
`--json`	flag	No	—	Diagnostik keluaran + statistik IR sebagai JSON. Berguna untuk alat CI dan integrasi editor.
`--no-info`	flag	No	—	Menekan `I×××` diagnostik tingkat info dari output.

datro fmt

Mencetak atau menulis ulang bentuk kanonik file .dtro. Pemformatnya bersifat deterministik: IR yang sama selalu menghasilkan keluaran yang sama, sehingga perbedaan hanya menunjukkan perubahan nyata.

# 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	—	Timpa file di tempatnya dengan bentuk kanonik.
`--check`	flag	No	—	Keluar bukan nol jika file belum kanonik — gunakan di hook pra-komit atau CI.

💡

Kait pra-komitmen

Tambahkan datro fmt --check arch.dtro ke hook pra-komit Anda sehingga bentuk kanonik selalu dikomit. Ini mencegah gangguan formatter dalam tinjauan kode.

ekspor data

Mengonversi file .dtro yang divalidasi ke format lain yang dapat dibaca mesin. Mencetak ke stdout secara default; gunakan --out untuk menulis ke file.

# 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	—	Format sasaran.
`--out`	path	No	—	Tulis keluaran ke jalur file ini alih-alih stdout.

`dot` — Bahasa Graphviz DOT. Masukkan ke dot -Tsvg untuk rendering khusus di luar rantai alat.
`cytoscape` — Cytoscape.js JSON. Impor langsung ke instance Cytoscape mana pun untuk diagram web interaktif.
`json` — JSON IR Lossless (objek DatroIR penuh). Gunakan dalam pemeriksaan CI khusus, skrip, atau perender.

render data

Merender file .dtro menjadi SVG atau PNG dengan piksel sempurna melalui Graphviz. Memerlukan biner dot dari Graphviz untuk diinstal dan pada $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	—	Jalur file keluaran. Ekstensi menentukan format: `.svg` atau `.png`.

ℹ️

Grafikviz diperlukan

Instal Graphviz dari graphviz.org/download dan pastikan dot ada di $PATH Anda. CLI keluar dengan kesalahan yang jelas jika tidak ditemukan.

datro md

Memproses blok kode berpagar Datro yang tertanam dalam file Markdown. Dua sub-perintah: check (validasi saja, tidak diperlukan Graphviz) dan render (validasi + output 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

Format blok tertanam

Tandai blok berpagar dengan pengidentifikasi bahasa datro. Blok tersebut harus menyertakan header ajaib:

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.

Blok Datro tertanam dalam file Markdown

Field	Type	Required	Default	Description
`--out-dir`	path	No	—	`md render` — direktori untuk file keluaran. Defaultnya ke direktori yang sama dengan file input Markdown.
`--format`	string "svg""png"	No	`svg`	`md render` — format keluaran.
`--json`	flag	No	—	`md check` — menampilkan hasil sebagai JSON, bukan teks yang dapat dibaca manusia.
`--no-fail`	flag	No	—	Lanjutkan memproses blok yang tersisa meskipun ada beberapa yang mengalami kesalahan. Keluar `0`.

Integrasi CI

Tambahkan langkah-langkah berikut ke pipeline CI mana pun untuk menerapkan kualitas diagram pada setiap permintaan 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 — gagal jika diagram tidak diformat secara kanonik.
validate --no-info — gagal pada diagnostik tingkat keparahan kesalahan apa pun.
md check --json — memvalidasi semua diagram yang tertanam; Output JSON terintegrasi dengan alat anotasi.

Langkah selanjutnya

Baca Language Reference untuk sintaks .dtro selengkapnya.
Pelajari cara embed diagrams in Markdown dengan plugin komentar atau markdown-it.

Buka Pembuat Diagram

Lebih suka browser? Validasi dan render tanpa menginstal apa pun.