diagram

CLI for rendering text-based diagrams (PlantUML, Mermaid, GraphViz, D2, DBML, BPMN, C4, Erd, Ditaa, Nomnoml, Pikchr, Structurizr, SvgBob, TikZ, Vega, Vega-Lite, WaveDrom, WireViz, BlockDiag / SeqDiag / ActDiag / NwDiag / PacketDiag / RackDiag, Excalidraw, Bytefield, Symbolator, UMlet) to SVG / PNG / PDF / JPEG / TXT / Base64 via the Kroki HTTP API. JSON output.

CLI

• Path: ./diagram-cli/diagram (relative to this SKILL.md). On Windows use diagram.cmd or diagram.ps1.
• Requires uv (install). First call provisions the Python environment automatically.
• Subcommands: render (primary), types (capability discovery).
• Run diagram render --help for current flags.

Endpoint resolution

The CLI picks the Kroki endpoint in this order:

1. --endpoint <url> flag
2. KROKI_URL environment variable
3. .kroki-url file (one URL, no quotes) walked up from the current working directory — useful for pinning a project to a self-hosted Kroki without touching shell config
4. https://kroki.io (default, free public instance)

Add .kroki-url to .gitignore if it points to an internal hostname.

Subcommands

diagram render

Renders one diagram and writes the output to a file. Always pass --output <path> — the JSON envelope is the only thing on stdout; the rendered bytes go to the file. After a successful call, use the Read tool on the produced file path to confirm the output looks right.

Examples:

# Auto-detect type from extension (.mmd → mermaid), default SVG
./diagram-cli/diagram render --input docs/flow.mmd --output docs/flow.svg

# PlantUML to PNG with explicit type/format
./diagram-cli/diagram render --input arch.puml --type plantuml --format png --output assets/arch.png

# Inline GraphViz
./diagram-cli/diagram render \
  --type graphviz \
  --source 'digraph G { Hello -> World }' \
  --output /tmp/hello.svg

# Stdin
cat diagram.d2 | ./diagram-cli/diagram render --type d2 --output diagram.svg

# Self-hosted Kroki
KROKI_URL=http://kroki.internal:8000 ./diagram-cli/diagram render \
  --input flow.puml --output flow.svg

Success output:

{"ok":true,"file":"/abs/path/flow.svg","type":"plantuml","format":"svg","bytes":12345,"endpoint":"https://kroki.io","sourceOrigin":"file"}

diagram types

Lists supported diagram types and their formats. No network call — the table is baked into the CLI. Use this to discover what --type / --format combinations are valid before calling render.

./diagram-cli/diagram types            # all types
./diagram-cli/diagram types mermaid    # one type

Supported diagram types (summary)

Run diagram types for the machine-readable, always-current list.

Workflow guidance

• Default to SVG. It scales, embeds cleanly in HTML/Markdown, and every diagram type supports it. Switch to PNG only when the consumer can't render SVG (image-only chat, certain markdown renderers).
• Prefer writing the diagram source to a file with an unambiguous extension (.puml, .mmd, .dot, etc.). The CLI then auto-detects --type and you keep the source under version control alongside the rendered output.
• When RENDER_FAILED comes back, the hint field contains Kroki's syntax-error message — surface it verbatim to the user and to your reasoning. Most of the time it includes a line number.
• For very large diagrams, raise --timeout. The default 30 s is generous for Kroki's free instance but a self-hosted one rendering complex PlantUML or TikZ may need more.

Error codes