Skip to main content
Documentation menu

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, pick its capabilities (read + write covers the CLI and MCP basics), 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 token with write access can change content in your account. Store it like any other credential, and never commit it to a repository. Pasting a literal token into a command also stores it in your shell history, so where a command below takes the token as an argument, it is passed through an exported environment variable instead. For token capabilities 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. On Claude Code, export the token first, then add the server, so the literal PAT never appears on the claude mcp add line (where it would land in your shell history):

Claude Code (CLI)
export EXCALIWOW_TOKEN=excw_pat_…
claude mcp add excaliwow --scope local \
  --env EXCALIWOW_TOKEN="$EXCALIWOW_TOKEN" -- npx -y @excaliwow/mcp

On Claude Desktop (or any JSON-config client), add this instead:

MCP client config
{
  "mcpServers": {
    "excaliwow": {
      "command": "npx",
      "args": ["-y", "@excaliwow/mcp"],
      "env": {
        "EXCALIWOW_TOKEN": "excw_pat_…"
      }
    }
  }
}

Floating package, visible version

The package spec is unversioned, so the docs cannot strand you on an old pin. However, npx -y can reuse a global or cached copy. The server prints its running version in your MCP client logs; if tools appear to be missing, run npx -y @excaliwow/mcp --version and check the MCP troubleshooting guide. For more on tokens and capabilities, see the MCP guide.

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 eighteen tools for creating, reading, organizing, inspecting, and editing diagrams. Reads include a rendered image of the diagram. See the MCP guide for the full tool list.

Next steps