Developer platform

CLI

@excaliwow/cli is a thin command-line client over the Excaliwow REST API. Create, read, render, and edit diagrams from your terminal or a script, with a global --json mode for piping into other tools.

Install

Install globally to expose excaliwow on your PATH, or run it ad-hoc with npx (handy for pinning a version in CI).

# install globally
npm install -g @excaliwow/cli

# or run a single command without installing
npx @excaliwow/cli <command>

Authenticate

The CLI authenticates with a Personal Access Token. Sign in at excaliwow.com and mint a token from Settings, then store it with auth login. See Authentication for token scopes and lifecycle.

# paste the token at the masked prompt
excaliwow auth login

# or pass it directly
excaliwow auth login --token "$PAT"

# or pipe it in (CI-friendly)
echo "$PAT" | excaliwow auth login

The token is validated before it is stored, so a bad token is rejected and nothing is written. A valid token is saved to ~/.config/excaliwow/config.json with owner-only permissions. Use auth status to confirm who you are signed in as, and auth logout to clear the stored token.

Commands

Run any command with --help to see its options. Add the global --json flag to any command to get machine-readable output.

excaliwow --help

# auth
excaliwow auth login [--token <t>]      validate and store a token
excaliwow auth logout                   clear the stored token
excaliwow auth status                   show the current identity

# diagrams
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>]

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

Every command targets the same surface as the REST API, so anything you can script with the CLI you can also call directly over HTTP.

File formats

Three flags take a JSON file. Each describes a diagram at a different level. The --spec and --fragment formats are described in full in the Diagram DSL reference.

--spec

A high-level node and edge graph that Excaliwow lays out for you. Top-level nodes (each a unique id plus an optional label) and edges (object form, or the "from -> to: label" shorthand).

spec.json

{
  "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), or updateNodes.

fragment.json

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

--scene

A raw Excalidraw scene, for example one exported from excalidraw.com. Excaliwow uses it as-is rather than laying it out.

scene.json

{
  "elements": []
}

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 and pipe it
excaliwow diagrams render <id> --format svg > out.svg

# additively merge an edit; a follow-up get or render reflects it immediately
excaliwow diagrams edit <id> --fragment ./add-node.json

# rename (title) and move (folder) are separate commands
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) draw the rendered PNG directly in your terminal when it speaks an inline-image protocol:

The iTerm2 family, including iTerm2 and WezTerm.
kitty, via the kitty graphics protocol.

In any other terminal the preview is skipped gracefully with a note, and a preview failure never fails the create. Pass -o <file> to save the PNG instead.

Preview fidelity

The inline preview is an approximate thumbnail, not a pixel-exact editor render. Open the diagram in the editor for the exact look.

Environment variables

Variable	Type	Description
`EXCALIWOW_TOKEN`	string	Bearer token used for the request. Wins over the stored config and is never persisted to disk, so it is the safest way to authenticate in CI.
`EXCALIWOW_API_URL`	string	API origin. Defaults to `https://excaliwow.com`. Override it for a single command with `--api-url`.

Exit codes

Exit codes are stable so a script can branch on the failure class.

Code	Description
`0`	Success.
`1`	Generic error, bad usage, or not authenticated.
`2`	Authentication failed (401 or 403).
`4`	Not found (404).
`5`	Rate limited (429). The `Retry-After` value is echoed so a script can back off.
`6`	Upstream unavailable (502).