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]

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

Table 1. CLI Commands
Command Purpose

convert [options] <diagram>

Convert the diagram file specified by the <diagram>. See examples.

version

Print the version of Kroki.

help

Help about any command.
Table 2. 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, 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: demo.kroki.io and a timeout of 20 seconds.

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