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.1 <command>

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`.