@excaliwow/cli

@excaliwow/cli

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:
npx @excaliwow/cli <command>       # pin a version in CI, e.g. @0.1.x

Then authenticate with a Personal Access Token (PAT). Sign in at excaliwow.com and create one under Settings → Developer / API tokens (https://excaliwow.com/app/settings):

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>

excaliwow icons [--category <c>]        List the curated diagram icons

The icon-<name> ids from excaliwow icons go on a DSL node's icon field (auto-placed as a glyph) or on a raw image element's fileId.

Run any command with --help for its options.

File formats

Each of --spec, --fragment, and --scene takes a JSON file:

• --spec — a high-level node/edge graph that Excaliwow auto-lays-out. Top-level nodes (each a unique id + optional label) and edges (object form, or the "from -> to: label" shorthand):

  {
    "nodes": [
      { "id": "client", "label": "Client" },
      { "id": "api", "label": "API Server" }
    ],
    "edges": ["client -> api: request"]
  }
  

• --fragment — an additive edit applied to an existing diagram, with any of addNodes / addEdges (object form) / updateNodes:

  {
    "addNodes": [{ "id": "cache", "label": "Cache" }],
    "addEdges": [{ "from": "api", "to": "cache" }]
  }
  

• --scene — a raw Excalidraw scene ({ "elements": [...] }), e.g. one exported from excalidraw.com.

Examples

# Create from a 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 — a follow-up get/render reflects the change immediately
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 family — kitty, Ghostty (the kitty graphics protocol).

In any other terminal (plain Terminal.app, sixel-only terminals, and most others) 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 inline preview is a faithful-enough thumbnail, not a pixel-exact editor render. Open the diagram in the editor for the exact look.

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.

Requirements

Node >= 22.11.0 — a support-policy floor (tracks current LTS), not a technical one; nothing shipped here needs a Node-22-only API. Matches @excaliwow/mcp's floor.

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)

Support

Found a bug or have a question? See excaliwow.com/docs/cli or reach us at excaliwow.com/contact.

License

Apache-2.0 — see LICENSE and NOTICE.