Usage Guide

Kroki-rs can be used in two modes: CLI (Command Line Interface) and Server (HTTP API).

CLI Mode¶

Use the CLI for one-off conversions or batch processing scripts.

Command Structure¶

kroki-rs convert --type <DIAGRAM_TYPE> --format <OUTPUT_FORMAT> <INPUT_FILE>

-t, --type: The diagram type (e.g., dot, mermaid, d2, excalidraw).
-f, --format: The output format (svg, png, pdf, webp). Note: SVG provides the best vector fidelity, but WebP is supported natively by kroki-rs via high-quality lossless rasterization.
<INPUT_FILE>: Path to the file containing the diagram description.
--cache-dir <DIR>: (Optional) Path to enable local SVG/WebP caching to skip redundant conversions.
--font <URL>: (Optional) HTTP URL to a .ttf or .otf font file. Kroki-rs will download, cache, and automatically load this font into the rendering context (especially useful for achieving perfect WebP output fidelity for web-based tools like Mermaid). You can specify multiple --font flags.

Batch Conversion¶

Have a folder full of diagrams? Kroki-rs can convert them all concurrently:

kroki-rs batch -f webp --out-dir ./output ./my-diagrams

Kroki-rs will automatically detect the diagram type from the file extension (e.g., .mmd -> mermaid, .d2 -> d2).

CLI Examples¶

Graphviz

Mermaid

BPMN

Wavedrom

Ditaa

Excalidraw

Vega

Vega-Lite

Command:

kroki-rs convert -t graphviz -f svg tests/fixtures/test.dot > output.svg

Server Mode¶

The server CLI follows the Kroki API specification.

Start Server¶

kroki-rs serve [--port <PORT>]

Default port is 8000.

API Endpoints¶

`GET /:type/:format/:source_encoded`¶

Generates a diagram from an encoded source string.

:type: Diagram type (e.g., graphviz, mermaid).
:format: Output format (svg, png, etc.).
:source_encoded: The diagram source code, compressed with Zlib (or Deflate) and encoded in Base64URL.

Example: Request a Graphviz diagram:

curl http://localhost:8000/graphviz/svg/eNpLyUwvSizm5TIGAAWDAY0=

`POST /`¶

(If implemented) Accepts a JSON payload with diagram source and type.

{
  "diagram_source": "digraph G { Hello -> World }",
  "diagram_type": "graphviz",
  "output_format": "svg"
}

Admin Dashboard & Health Checks¶

When running in Server Mode, Kroki-rs automatically exposes an Admin Dashboard on an isolated port (default: 8081). This completely separates administrative capabilities from the primary diagram rendering APIs.

Dashboard UI: Navigate to http://localhost:8081/ to view service status, version metrics, and an active discovery capabilities list.
Health Check API: A machine-readable HTTP GET /health endpoint is available at http://localhost:8081/health enabling Docker, Kubernetes, and other orchestration platforms to reliably monitor container liveliness.

Supported Clients¶

Since kroki-rs is API-compatible, you can use existing Kroki clients! Just point them to your local instance.

VS Code: Kroki extension (set URL to http://localhost:8000)
Obsidian: Kroki plugin
Browser: Kroki integrations

Debugging & Troubleshooting¶

Enabling Verbose Logs¶

If a diagram fails to render, the first step is to increase the logging level:

# For CLI
RUST_LOG=debug kroki-rs convert -t mermaid -f svg test.mmd

# For Server
RUST_LOG=debug kroki-rs serve

Checking Capabilities¶

Kroki-rs skips diagram providers if their underlying tools are missing. Verify your installation by running the discovery check:

kroki-rs serve --dry-run

This will print the discovery log without starting the server, showing which tools were found and where.

Browser Worker Debugging¶

For diagrams using the browser pool (Mermaid, BPMN), ensure your system has a compatible Chromium/Chrome binary. If running on a headless server without a window manager, ensure Xvfb is installed or use the official Docker Image which handles these dependencies automatically.