The excaliwow command-line client — a thin, dependency-light HTTP client over the live Excaliwow REST API (/api/v1). Create, read, render, and edit diagrams from your terminal or a script, with a global --json mode for piping.

Install

npm install -g @excaliwow/cli      # exposes `excaliwow` on your PATH
# or run ad-hoc (pin the version):
npx @excaliwow/cli@0.1.0 <command>

From source (local development)

pnpm --filter @excaliwow/cli build
npm link            # from the cli/ dir — exposes `excaliwow` on your PATH

Then authenticate with a Personal Access Token (PAT) minted in the Excaliwow dashboard:

excaliwow auth login          # paste the PAT at the masked prompt
# or non-interactively / in CI:
excaliwow auth login --token "$EXCALIWOW_TOKEN"
echo "$PAT" | excaliwow auth login

auth login validates the token against GET /me before storing it, so a bad token is rejected and nothing is written. The stored config lives at ~/.config/excaliwow/config.json (chmod 600).

Commands

excaliwow auth login [--token <t>]      Validate + store a PAT
excaliwow auth logout                   Clear the stored token
excaliwow auth status                   Show the current identity

excaliwow diagrams list [--filter active|trash] [--cursor <c>] [--limit <n>]
excaliwow diagrams create [--title <t>] (--spec <file> | --scene <file>) [--folder <id>]
excaliwow diagrams get <id>
excaliwow diagrams render <id> [--format png|svg|json] [-o <file>]
excaliwow diagrams edit <id> --fragment <file>
excaliwow diagrams rename <id> --title <t>
excaliwow diagrams move <id> --folder <id|null>
excaliwow diagrams delete <id>
excaliwow diagrams publish <id> (--enable | --disable) [--password <p>]

excaliwow folders list
excaliwow folders create --name <n> [--parent <id>]
excaliwow folders rename <id> --name <n>
excaliwow folders delete <id>

Run any command with --help for its options.

Examples

# Create from a DSL spec file, then preview it inline (iTerm2 / kitty)
excaliwow diagrams create --title "Flow" --spec ./flow.json

# Render to a PNG file
excaliwow diagrams render <id> --format png -o out.png

# Render SVG to stdout (pipe it)
excaliwow diagrams render <id> --format svg > out.svg

# Additively merge an edit fragment (read-your-writes — a follow-up get/render reflects it)
excaliwow diagrams edit <id> --fragment ./add-node.json

# Rename (title only) vs. move (folder) are SEPARATE — never combined
excaliwow diagrams rename <id> --title "New name"
excaliwow diagrams move <id> --folder <folderId>
excaliwow diagrams move <id> --folder null      # move to root

# Public share link: password is tri-state
excaliwow diagrams publish <id> --enable --password "hunter2"
excaliwow diagrams publish <id> --enable --password ""   # clear the password
excaliwow diagrams publish <id> --disable

# Machine output for scripts
excaliwow diagrams list --json | jq '.items[].id'

Inline image preview

diagrams create (and diagrams render --format png with no -o) draws the rendered PNG inline in your terminal when it speaks an inline-image protocol:

iTerm2 family — iTerm2, WezTerm (OSC 1337).
kitty — the kitty graphics protocol.

In any other terminal (plain Terminal.app, most others — including sixel-only terminals, which are intentionally not supported to keep the CLI dependency-thin) the preview is skipped gracefully with a note; use render -o <file> to save the PNG instead. A render/preview failure never fails the create.

PNG fidelity is approximate — the server renders from a pure-JS SVG renderer (system fonts, no rough.js sketchy strokes), so the inline preview is a faithful-enough thumbnail, not a pixel-exact editor render.

Environment variables

Var	Effect
`EXCALIWOW_TOKEN`	Bearer token. Wins over the stored config; never persisted to disk.
`EXCALIWOW_API_URL`	API origin. Overridden per-call by `--api-url`. Default `https://excaliwow.com`.

Exit codes

Stable so scripts can branch on the failure class:

Code	Meaning
0	OK
1	Generic / usage / not authenticated
2	Auth (401 / 403)
4	Not found (404)
5	Rate limited (429 — echoes `Retry-After`)
6	Upstream unavailable (502)

Local development against a dev server

Point the CLI at a local app server:

export EXCALIWOW_API_URL=http://localhost:3000
excaliwow auth status

For diagrams edit (and its read-your-writes guarantee) to work locally, the app server must be able to reach the Hocuspocus merge backend. Set, on the app server's environment:

HOCUSPOCUS_INTERNAL_URL=http://localhost:1234

The dev Hocuspocus container can be stale (the /internal/merge path lives in its image) — rebuild it before testing edit:

docker compose -f docker-compose.dev.yml build hocuspocus

Without these, edit surfaces a distinct 502 upstream_unavailable hint (exit 6) — that means the merge backend was unreachable, not that the edit was invalid.

Dev-server caveat — create --spec: the DSL-layout path runs the app's dagre layout, which can fail under the Vite dev server (react-router dev) with layout is not a function (a CJS/ESM-interop quirk of the dev SSR runtime). This is not a CLI issue — create --spec works against the built/deployed API (verified on test.excaliwow.com) and the raw --scene path works everywhere. To exercise spec-create locally, point at the deployed test API or a built app; every other command works against the dev server.