excalidraw

name	excalidraw
description	Manage Excalidraw+ via CLI and the official MCP endpoint: scenes, scene content, collections, workspace users, invites, logs, and raw MCP tool calls. Use when the user mentions Excalidraw, Excalidraw+, diagrams, .excalidraw scene editing, workspace collections, or the Excalidraw MCP/API.
category	creative

excalidraw-cli

Use excalidraw-cli to manage Excalidraw+ through the official MCP endpoint.

When To Use This Skill

Use this skill when you need to:

• List, create, rename, move, or delete Excalidraw+ scenes.
• Read full scene content or search shapes/text inside a scene.
• Add, update, or delete Excalidraw elements in a scene.
• Create and manage collections.
• Inspect workspace metadata, users, invites, and audit logs.
• Call a newly exposed Excalidraw MCP tool before the CLI has a dedicated shortcut.
• Build agent workflows around Excalidraw+ while keeping commands scriptable with JSON output.

Setup

If excalidraw-cli is not found, install and build it:

bun --version || curl -fsSL https://bun.sh/install | bash
npx api2cli install Melvynx/excalidraw-cli

For a local development checkout:

npx api2cli bundle excalidraw
npx api2cli link excalidraw

api2cli link adds ~/.local/bin to PATH automatically. The CLI is available in the next command.

Always use --json when calling commands programmatically.

Authentication

excalidraw-cli auth set "EXCALIDRAW_API_KEY"
excalidraw-cli auth test --json

Auth commands:

• excalidraw-cli auth set <token> saves the Excalidraw+ API key.
• excalidraw-cli auth show displays a masked token.
• excalidraw-cli auth show --raw displays the full token.
• excalidraw-cli auth remove deletes the saved token file.
• excalidraw-cli auth test --json validates the token against get_workspace.

Token file: ~/.config/tokens/excalidraw-cli.txt, chmod 600.

The CLI also accepts EXCALIDRAW_API_KEY from the environment.

Working Rules

• Always use --json for agent-driven calls so downstream steps can parse the result.
• Start with excalidraw-cli --help or <resource> --help if exact flags are unclear.
• Prefer read commands before mutations: list/get/search first, then create/update/delete.
• Before editing scene elements, run excalidraw-cli scenes format --json and follow the Excalidraw element rules.
• For scenes edit --add, do not include id fields. Use tempId only for same-request references.
• Shape-owned text should use label: { "text": "..." }, not floating text over a shape.
• Arrows pointing at shapes should include explicit startBinding and endBinding.
• Prefer scenes search over scenes content when you only need to find matching shapes/text.

Capabilities

• MCP tool discovery: list all Excalidraw+ MCP tools and inspect schemas.
• Raw MCP passthrough: call any MCP tool by name with --arg key=value or --args-json.
• Scenes: list, create, get metadata, update metadata, delete.
• Scene content: get full content, search content, read element format guide, add/update/delete elements.
• Collections: list, create, get, rename, delete, list scenes, create scene in collection.
• Workspace: get/update workspace, list/get/update/remove users.
• Invites: list, create email invite, create reusable invite link, get/update/delete invites.
• Logs: query workspace logs by pagination, user, action, operation, and date range.

Command Reference

Top-level

excalidraw-cli --help
excalidraw-cli auth test --json

Raw MCP tools

excalidraw-cli tools list --json
excalidraw-cli tools schema <toolName> --json
excalidraw-cli tools call <toolName> --arg key=value --json
excalidraw-cli tools call <toolName> --args-json '{"key":"value"}' --json

Examples:

excalidraw-cli tools call list_scenes --arg limit=10 --json
excalidraw-cli tools call create_collection --args-json '{"name":"Ideas"}' --json

Scenes

excalidraw-cli scenes list --limit 10 --offset 0 --json
excalidraw-cli scenes list --collection-id COLLECTION_ID --json
excalidraw-cli scenes create --name "Architecture" --collection-id COLLECTION_ID --pinned --json
excalidraw-cli scenes get SCENE_ID --json
excalidraw-cli scenes update SCENE_ID --name "New name" --collection-id COLLECTION_ID --pinned true --json
excalidraw-cli scenes delete SCENE_ID --json
excalidraw-cli scenes content SCENE_ID --json
excalidraw-cli scenes search SCENE_ID --query "Auth" --match-mode contains --type rectangle --limit 20 --json
excalidraw-cli scenes format --json
excalidraw-cli scenes edit SCENE_ID --add '[{"type":"rectangle","x":100,"y":100,"width":220,"height":90,"label":{"text":"Hello","fontSize":20,"fontFamily":5}}]' --json
excalidraw-cli scenes edit SCENE_ID --update '[{"id":"ELEMENT_ID","label":{"text":"Updated"}}]' --json
excalidraw-cli scenes edit SCENE_ID --delete '["ELEMENT_ID"]' --json

Collections

excalidraw-cli collections list --limit 20 --offset 0 --json
excalidraw-cli collections create --name "Product diagrams" --json
excalidraw-cli collections get COLLECTION_ID --json
excalidraw-cli collections update COLLECTION_ID --name "Renamed" --json
excalidraw-cli collections delete COLLECTION_ID --json
excalidraw-cli collections scenes COLLECTION_ID --limit 20 --json
excalidraw-cli collections create-scene COLLECTION_ID --name "Flow" --pinned --json

Workspace

excalidraw-cli workspace get --json
excalidraw-cli workspace update --name "Team Workspace" --picture https://example.com/logo.png --json
excalidraw-cli workspace users --limit 20 --offset 0 --json
excalidraw-cli workspace user USER_ID --json
excalidraw-cli workspace update-user USER_ID --name "Ada" --role admin --preferences '{"sceneOrder":"updated"}' --json
excalidraw-cli workspace remove-user USER_ID --json

Invites

excalidraw-cli invites list --limit 20 --json
excalidraw-cli invites create-email --email [e-mail] --role member --json
excalidraw-cli invites create-link --role member --max-uses 5 --restricted-domains '["example.com"]' --json
excalidraw-cli invites get INVITE_ID --json
excalidraw-cli invites update INVITE_ID --email null --role admin --json
excalidraw-cli invites delete INVITE_ID --json

Logs

excalidraw-cli logs list --limit 20 --offset 0 --json
excalidraw-cli logs list --user USER_ID --operation update --json
excalidraw-cli logs list --date-from 2026-01-01T00:00:00Z --date-to 2026-01-31T23:59:59Z --json

Output Format

--json returns a standardized envelope:

{ "ok": true, "data": { "example": true }, "meta": { "total": 1 } }

For arrays, meta.total is included. Some Excalidraw MCP tools return objects with their own pagination metadata inside data.

On error:

{ "ok": false, "error": { "code": 401, "message": "Authentication failed.", "suggestion": "Run: excalidraw-cli auth set <EXCALIDRAW_API_KEY>" } }

Common Use Cases

• "List my Excalidraw scenes and find the one about auth."
• "Create a collection for product diagrams."
• "Create a scene in this collection and add a labeled process box."
• "Search this scene for every rectangle labelled checkout."
• "Patch the label of this existing shape."
• "List workspace users/invites/logs for auditing."
• "Call the raw Excalidraw MCP tool because the beta exposed a new command."

Quick Reference

excalidraw-cli --help
excalidraw-cli <resource> --help
excalidraw-cli <resource> <action> --help

Global flags: --json, --format <text|json|csv|yaml>, --verbose, --no-color, --no-header.

Exit codes: 0 = success, 1 = API error, 2 = usage error.