excal

Agent-first CLI for Excalidraw scene inspection, validation, and rendering.

Built for AI agents, CI pipelines, and developers who need deterministic, non-interactive workflows around .excalidraw files. Every command returns a structured JSON envelope on stdout with stable error codes and exit semantics.

Install

npm install -g @trohde/excal-cli

Or run directly with npx:

npx @trohde/excal-cli inspect diagram.excalidraw

PNG and PDF export require Playwright (optional):

npx playwright install chromium

From source

git clone https://github.com/ThomasRohde/excalidraw-cli.git
cd excalidraw-cli
npm install
npm run build

Quick Start

# Inspect a scene
excal inspect diagram.excalidraw

# Validate structure
excal validate diagram.excalidraw --check-assets

# Export to SVG
excal render diagram.excalidraw --outDir ./out

# Export to PNG + PDF
excal render diagram.excalidraw --outDir ./out --png --pdf

# Pipe from stdin
cat diagram.excalidraw | excal inspect -

# Agent bootstrapping
excal guide
excal skill

Commands

excal inspect <file|->

Return element counts, type breakdown, frame details, text stats, bounding box, image info, and binary file metadata.

excal inspect diagram.excalidraw
excal inspect diagram.excalidraw --frame "Login Flow"
excal inspect diagram.excalidraw --include-deleted

excal validate <file|->

Check structural consistency: frame references, bound text bindings, arrow bindings, and optionally image asset references.

excal validate diagram.excalidraw
excal validate diagram.excalidraw --check-assets

excal render <file|->

Render a scene to SVG, PNG, or PDF. SVG is the default. PNG and PDF require Playwright.

excal render diagram.excalidraw --outDir ./out
excal render diagram.excalidraw --outDir ./out --svg --png
excal render diagram.excalidraw --outDir ./out --frame "Dashboard" --dark-mode
excal render diagram.excalidraw --dry-run

excal guide

Print a Markdown CLI reference — commands, flags, error codes, envelope schema. Designed for agent bootstrapping.

excal skill

Print Markdown domain knowledge about Excalidraw scene structure, element types, frames, arrows, bound text, images, and export tips.

Response Envelope

Every command writes a JSON envelope to stdout:

{
  "schema_version": "1.0",
  "request_id": "req_20260302_143000_7f3a",
  "ok": true,
  "command": "scene.inspect",
  "target": { "file": "diagram.excalidraw", "fingerprint": "ab12..." },
  "result": { ... },
  "warnings": [],
  "errors": [],
  "metrics": { "duration_ms": 42 }
}

• ok, result, warnings, errors, and metrics are always present.
• On failure, result is null and errors contains structured error objects.
• Each error has code, message, retryable, and suggested_action.

Error Codes

Input Formats

The CLI auto-detects three input formats:

• Full scene — standard .excalidraw JSON with elements, appState, files
• Elements-only — a bare JSON array of elements
• Clipboard — { "type": "excalidraw/clipboard", "elements": [...] }

Architecture

src/
  cli/          Commander commands (inspect, validate, render, guide, skill)
  core/         Envelope, errors, IO, fingerprinting, exit codes
  scene/        Zod schemas, scene loading, normalization, inspection, validation, filtering
  render/       Playwright browser bridge using @excalidraw/utils
  guide/        Guide + skill markdown content

Dual bundle via tsup:

• CLI entry — ESM, Node.js, Playwright external
• Bridge entry — IIFE, browser, @excalidraw/utils bundled in

Rendering works by loading a minimal HTML page in headless Chromium, passing scene JSON via page.evaluate(), and calling exportToSvg/exportToBlob from @excalidraw/utils.

Development

npm run build       # Build CLI + bridge bundles
npm test            # Run all tests
npm run dev         # Watch mode build
npm run typecheck   # TypeScript type checking

Releasing

pnpm run bump:patch                              # or bump:minor / bump:major
git add -A && git commit -m "chore: release vX.Y.Z"
git push
npm publish --access=public --auth-type=web      # opens browser for npm auth

License

MIT