Kroki CLI

The easiest way to interact with Kroki is probably to use the Kroki CLI. This client is available on Linux, macOS, Windows and OpenBSD and provides a user-friendly Command Line Interface.

Once you’ve downloaded the archive, extract the kroki binary file from the archive to a directory, then open a terminal and type:

/path/to/kroki version

If installation was successful, the command should report the version of Kroki CLI:

kroki 0.1.0 4afafe2e51df4d02a21661e1d8838a146b5cba66 [https://kroki.io]

📌 NOTE

We recommend to add kroki to your PATH so you can use the command kroki without specifying the path:

kroki version

Command structure

The kroki command accepts user inputs in the form of options, positional arguments, and environment variables.

kroki <command> [options] <arguments>

1. All functions start with a base call to Kroki (kroki).
2. The command tells Kroki what operation to perform.
3. Additional options can be specified after a command.
4. Positional arguments, such as the name of the diagram file, are specified last.
5. Environment variables are read from the terminal’s state.

Commands and options

CLI Commands

Command	Purpose
completion	Generate the autocompletion script for the specified shell.
convert [options] <diagram>	Convert the diagram file specified by the <diagram>. See examples.
decode	Decode an encoded (deflate + base64) diagram.
encode	Encode text diagram in deflate + base64 format.
help	Help about any command.
version	Print the version of Kroki.

CLI Options

Option	Purpose	Format	Default
-c, --config <file>	An alternate config file.	String	not set
-f, --format <format>	Image output format: svg, jpg, png or pdf.	String	Infer from output file extension, otherwise svg.
-o, --out-file <file>	Output file. Use - to output to STDOUT.	String	Infer from input file name.
-t, --type <type>	Diagram type: actdiag, blockdiag, c4plantuml, ditaa, dot, erd, goat, graphviz, nomnoml, nwdiag, plantuml, seqdiag, svgbob, symbolator, umlet, vega, vegalite.	String	Infer from input file extension.
-v, --version	Output the Kroki version information.	Built-in	n/a
-h, --help	Output the command usage information.	Built-in	n/a

Get help with the CLI

When you’re using the Kroki CLI and need help, type -h or --help after the command.

Display help for the kroki command

kroki --help

Display help for the convert command

kroki convert -h

Run the convert command

By default the diagram type will be inferred from the diagram file extension and the default output format will be SVG. So to convert a PlantUML diagram named diagram.puml to an SVG image, open a terminal and type:

Example 1: Short format (implicit)

kroki convert diagram.puml

In Example 1, Kroki converts a PlantUML diagram named diagram.puml to an SVG image named diagram.svg.

Example 2: Long format (explicit)

kroki convert diagram.puml --type plantuml --format svg --out-file diagram.svg

In Example 2, Kroki will do exactly the same as Example 1.

Example 3: Run the convert with --out-file option (implicit)

kroki convert simple.er --out-file out.png

In Example 3, Kroki converts en Erd diagram to a PNG image named out.png. When the output format is not defined, it will be inferred from the output file.

Example 4: Run the convert command with - (stdin)

cat hello.dot | kroki convert - -t dot

In Example 4, Kroki reads from stdin and outputs the result to stdout. If you want to output to a file you can use -o:

Example 5: Have the convert command reads from stdin and output to file

cat hello.dot | kroki convert - -t dot -o out.png

Similarly, you can also output to stdout when reading from a file using the special value - with the --out-file option:

Example 6: Have the convert command reads from a file and output to stdout

kroki convert simple.er --out-file -

Configuration

To configure the endpoint, you can use a configuration file. The CLI will look for the following locations:

• /etc/kroki.yml
• $HOME/kroki.yml
• kroki.yml

You can also specify an alternate config file using the --config option:

kroki convert hello.dot --config config.yml

The config file should contain the endpoint URL and the HTTP timeout. By default Kroki will use the demonstration server: https://demo.kroki.io and a timeout of 20 seconds.

🔥 CAUTION

Please note that the demonstration server usage is restricted to reasonable, non-commercial use-cases. We provide no guarantee regarding uptime or latency.

Example

kroki.yml

endpoint: "https://localhost:8000"
timeout: "30s"

If you don’t want to use a file you can also use the following environment variables:

• KROKI_ENDPOINT
• KROKI_TIMEOUT

KROKI_ENDPOINT=https://localhost:8000 KROKI_TIMEOUT=1m kroki convert hello.dot