Getting started

Quickstart

One step gets you a token. After that, pick your path: drive Excaliwow from your terminal, or hand it to your AI agent. Either way you have a diagram in about five minutes.

Get a token

Sign in at excaliwow.com, then open Settings and find Developer / API tokens. Create a Personal Access Token and copy it now: it is shown once. This single token authenticates the API, the CLI, and the MCP server.

Keep it secret

Treat your token like a password. It authenticates as you, so a write-scoped token can change anything in your account. Store it like any other credential, and never commit it to a repository. For token scopes and rotation, see Authentication and access tokens.

From your terminal (CLI)

Install the CLI globally to put the excaliwow command on your PATH, or run it ad-hoc with npx.

Install

npm install -g @excaliwow/cli      # exposes the excaliwow command
# or run a single command without installing:
npx @excaliwow/cli <command>

Authenticate

Paste the token at the masked prompt. It is validated before being stored, so a bad token is rejected and nothing is written.

Authenticate

excaliwow auth login
# or non-interactively, for CI:
excaliwow auth login --token "$EXCALIWOW_TOKEN"

Describe a diagram

Write a small spec file. A spec is a high-level node and edge graph that Excaliwow lays out for you. Save the following as architecture.json.

architecture.json

{
  "version": "1",
  "nodes": [
    { "id": "client", "label": "Client", "shape": "rectangle" },
    { "id": "api", "label": "API Server", "shape": "rectangle" },
    { "id": "db", "label": "Database", "shape": "diamond" },
    { "id": "cache", "label": "Cache", "shape": "ellipse" }
  ],
  "edges": [
    { "from": "client", "to": "api", "label": "request" },
    { "from": "api", "to": "db" },
    { "from": "api", "to": "cache" }
  ],
  "layout": { "direction": "TB" }
}

Create and render

Create the diagram from your spec, then render it to a PNG. Create returns an id; pass that id to render.

Create, then render

excaliwow diagrams create --title "Architecture" --spec architecture.json
excaliwow diagrams render <id> --format png -o out.png

That is your first diagram. The full command reference is in the CLI guide.

From your AI agent (MCP)

Prefer to stay in your AI client? Add the Excaliwow MCP server to its config. It runs over stdio, so any MCP client can launch it. Drop your token into the EXCALIWOW_TOKEN environment variable.

MCP client config

{
  "mcpServers": {
    "excaliwow": {
      "command": "npx",
      "args": ["-y", "@excaliwow/[email protected]"],
      "env": {
        "EXCALIWOW_TOKEN": "excw_pat_…"
      }
    }
  }
}

Pin the version

Keep the pinned version in your config and bump it deliberately after reviewing a release. This server holds a token to your account, so a floating version is an avoidable supply-chain surface.

Restart your client so it picks up the new server, then ask your agent to build something. It calls the generate_diagram tool and hands back an editor URL.

Ask your agent

Create an Excaliwow diagram of a client calling an API server,
with the API talking to a database and a cache.

The server exposes a small set of tools for creating, reading, listing, moving, and editing diagrams. Reads include a rendered image of the diagram. See the MCP guide for the full tool list.

Next steps

Authentication and access tokens. Mint, scope, and rotate tokens.
Diagram DSL. The content model behind nodes, edges, layout, and edit fragments.
REST API. List, read, create, render, and edit diagrams over HTTP.
CLI. Every command and option.
MCP server. Drive Excaliwow from your AI agent.