The koboyo CLI

koboyo draws diagrams from code on your own machine. It turns Koboyo diagram code into SVG, PNG or HTML with the same engine as the editor, and it needs no account. It is made for people and for coding agents alike: the output is plain files, --json gives a result a script can read, and exit codes tell success from failure.

Install#

Run it without installing anything:

npx koboyo render diagram.kbd

Or install it once:

npm install -g koboyo

It needs Node.js 20 or newer, and works on macOS, Linux (Alpine too) and Windows.

To set up a coding agent (Claude Code, Codex, Cursor, VS Code or Windsurf) to draw with it, run npx koboyo setup. See local MCP server.

Render a diagram#

Write diagram code in a file. .kbd is the usual extension. For example, docs/checkout.kbd:

title: Checkout
browser [monitor] -> api [tech/nodedotjs]
api -> database [aws/rds]: save order
api -> payments: charge card

Render it. The picture is written next to the code:

koboyo render docs/checkout.kbd                 # docs/checkout.svg
koboyo render docs/checkout.kbd --preview       # also docs/checkout.preview.png
koboyo render docs/*.kbd                        # one SVG per file
koboyo render docs/checkout.kbd -o checkout.png # the extension picks the format

The SVG carries its fonts and icons, so it shows correctly anywhere, including in a README or an <img> tag:

![Checkout](docs/checkout.svg)

Code from stdin goes to stdout:

echo "build -> test -> deploy" | koboyo render - > pipeline.svg

Mermaid code works too. It is converted as it is read, and a .mmd or .mermaid file is always read as Mermaid. See importing Mermaid.

Formats#

Pick one with --format, or let the --out file's extension decide.

The html figure uses the diagram's title as its accessible name. Its "Edit in Koboyo" link opens the code in the editor on koboyo.com. The code travels inside the link itself, so nothing is uploaded.

Other options:

• --width <px> sets the display width, and a PNG's width in pixels.
• --padding <px> sets the space around the diagram (24 by default).
• --transparent leaves out the background.
• --fonts-css <path> writes the fonts to one CSS file instead of into every SVG. Use it for a page that inlines many diagrams, and link that file once.
• --watch renders again every time you save an input, until you press Ctrl-C. Code with an error prints the error and leaves the last good picture in place.
• --check writes nothing and tells you whether the pictures on disk still match their code. See Keep diagrams in sync in CI.

Themes#

--theme light is the default, and --theme dark draws the dark palette. --theme auto writes one SVG that carries both and follows the reader's light or dark mode in the browser. A PNG holds one theme, so auto works with SVG and HTML only.

koboyo render docs/checkout.kbd --theme auto

Keep diagrams in sync in CI#

When you commit the SVG next to its .kbd file, --check makes sure the two never drift apart. Run it with the same options you render with:

koboyo render docs/*.kbd --theme auto --check

It draws each diagram in memory and compares it with the file on disk, without writing anything. Each picture is listed as up to date, out of date or missing. If any picture is out of date or missing, it exits with code 1 and prints the command that brings them up to date.

--check works with SVG and HTML output, and with the --fonts-css stylesheet. It does not check PNG files: their anti-aliased pixels can differ slightly from one machine to another, so a committed PNG would fail for no visible reason. Commit the SVG instead.

Pin the koboyo version in CI to the one you render with. A new release can draw a diagram slightly differently, and the check should fail only when the code changes.

In GitHub Actions:

name: Diagrams
on: [push, pull_request]
jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx --yes koboyo@0.1.0 render docs/*.kbd --theme auto --check

As a Git pre-commit hook, with koboyo installed in the project (npm install --save-dev koboyo). Save it as .git/hooks/pre-commit and make it executable with chmod +x .git/hooks/pre-commit:

#!/bin/sh
# Check the pictures of every .kbd file in this commit, as staged.
koboyo="$(git rev-parse --show-toplevel)/node_modules/.bin/koboyo"
staged=$(mktemp -d)
trap 'rm -rf "$staged"' EXIT
git checkout-index --all --prefix="$staged/"
git diff --cached --name-only -z --diff-filter=ACMR -- '*.kbd' |
  (cd "$staged" && xargs -0 -r "$koboyo" render --theme auto --check)

The hook checks the files as they are staged, not as they are in your working folder, so a picture you re-rendered but did not git add still fails. When the check fails, run the command it prints, then add the updated pictures to the commit.

Check, syntax, icons and convert#

koboyo check docs/*.kbd        # report errors and warnings, write nothing
koboyo syntax                  # list the diagram kinds
koboyo syntax sequence         # how to write one kind, and what makes it look good
koboyo icons redis "route 53"  # icon refs to write in the code
koboyo convert flow.mmd        # Mermaid to Koboyo code: writes flow.kbd

koboyo syntax <kind> prints the same cheatsheet these docs pages are built from, followed by advice on what makes that kind of diagram read well.

koboyo icons prints each match the way the code takes it:

redis
  [tech/redis]                 Redis (tech)
  [aws/memorydb-for-redis]     MemoryDB for Redis (aws)
route 53
  [aws/route-53]  Route 53 (aws)

Comments#

koboyo comments docs/arch.kbd                                    # list the open comments
koboyo comments docs/arch.kbd --thread 3f2a9c1e --reply "Done" --resolve

koboyo comments lists the comments someone pinned on a diagram in the editor, each with an id, the box it is on and the replies under it. With --thread and the first characters of an id, it replies (--reply), marks the comment resolved (--resolve) or reopens it (--reopen). --agent-name sets who the reply is from. An open editor shows the reply straight away.

Run koboyo help for every command, and koboyo help <command> for its options and examples.

Errors and warnings#

Problems are printed with the file and line, the way compilers print them:

docs/checkout.kbd:3  warning  unknown icon "tech/redsi" (did you mean: tech/redis?)
docs/checkout.kbd:4  warning  "database" is drawn as a shape here. For the icon, write [icon: database]

An error means a line cannot be drawn, so no image is written for that file. A warning means the image was written but may not look the way you meant. See error handling for how the compiler reads code it does not fully understand.

JSON output#

Add --json to any command and it prints one JSON object on stdout, and nothing else:

koboyo render docs/checkout.kbd --json

{
  "ok": true,
  "command": "render",
  "input": "docs/checkout.kbd",
  "output": {
    "path": "/work/docs/checkout.svg",
    "format": "svg",
    "bytes": 61234,
    "width": 742,
    "height": 389
  },
  "preview": null,
  "editLink": "https://koboyo.com/code#src=…",
  "title": "Checkout",
  "convertedFrom": null,
  "diagnostics": [],
  "warnings": [],
  "fontsCss": null
}

• Every result has ok and command. A failure adds error: { code, message, hint }.
• Each diagnostic is { line, severity, message }, with suggestions when koboyo can guess what was meant.
• When the image goes to stdout, it is in output.content (text for SVG, base64 for PNG).
• Several input files give { ok, command, files: [...], fontsCss }, one entry per file.

New fields may be added over time. Existing ones keep their names and meaning.

Exit codes#

Icons and the network#

The fonts, the Lucide icons and the names of every brand and cloud icon ship inside the package, so koboyo icons and icon warnings work offline. The drawings of brand and cloud icons (tech/, aws/, gcp/, azure/, emoji) are downloaded from koboyo.com the first time a diagram uses them, then kept in a cache on disk. If one cannot be downloaded, the image is still written and a warning names the missing icon. Apart from the daily version check below, nothing else is sent anywhere.

• KOBOYO_CACHE_DIR sets where downloaded icons are kept.
• KOBOYO_OFFLINE=1 never downloads, uses only cached icons, and skips the version check.
• NO_COLOR=1 turns off colored output.

Update notices#

Once a day, koboyo asks the npm registry for its latest version, in the background, so no command waits for it. When a newer one is out, the next run ends with one line saying so and how to update:

koboyo 0.3.0 is available (you have 0.2.1). Update: npm i -g koboyo

It never prints with --json, when the output goes to a file or a pipe, under koboyo mcp, or in CI. Set NO_UPDATE_NOTIFIER=1 or KOBOYO_NO_UPDATE_CHECK=1 to turn it off.

Shell completion#

koboyo completion <shell> prints a script that completes commands, options and their values, and offers only the diagram files a command reads. Install it once, and again after updating koboyo:

# bash (with bash-completion)
koboyo completion bash > ~/.local/share/bash-completion/completions/koboyo

# zsh: then add  fpath=(~/.zfunc $fpath)  to ~/.zshrc, before compinit
mkdir -p ~/.zfunc && koboyo completion zsh > ~/.zfunc/_koboyo

# fish
koboyo completion fish > ~/.config/fish/completions/koboyo.fish

In PowerShell, save the script and load it from your profile:

koboyo completion powershell > "$HOME\koboyo-completion.ps1"
Add-Content $PROFILE '. "$HOME\koboyo-completion.ps1"'