✏️ excalidraw-cli

Create and manipulate Excalidraw diagrams from the command line.

A CLI-Anything harness that turns Excalidraw into an agent-native, scriptable tool.
Generate flowcharts, sequence diagrams, ER diagrams, mind maps, and Kanban boards —
then open them in Excalidraw for hand-drawn-style polish.

Why excalidraw-cli?

Problem	Solution
Excalidraw has no CLI — diagrams require the web UI	`excalidraw-cli` generates valid `.excalidraw` files from the terminal
AI agents can't create visual diagrams easily	`--json` flag on every command enables structured agent workflows
Repetitive diagram creation is tedious	Templates generate complete diagrams in one command
No programmatic access to the `.excalidraw` format	Python API (`Scene`, `create_element`) for full control

Quick Start

Installation

From PyPI (recommended):

pip install excalidraw-cli

# For PNG, JPG, PDF export support:
pip install excalidraw-cli[export]

From source (for development):

cd agent-harness
pip install -e .

# For PNG, JPG, PDF export support:
pip install -e ".[export]"

Your first diagram in 10 seconds

# Generate a flowchart and open it at excalidraw.com
excalidraw-cli template flowchart "Start" "?Is valid?" "Process" "End" \
  -o my_flow.excalidraw

Open my_flow.excalidraw in excalidraw.com (File > Open) to see your diagram with the signature hand-drawn style.

Features

5 diagram templates — flowchart, sequence, ER, mind map, Kanban
Export to SVG, PNG, JPG, PDF — high-quality image and vector output with configurable scale and quality
Full element control — add, update, remove, connect shapes programmatically
Undo/redo — built-in state management for safe iteration
--json everywhere — structured output for AI agents and pipelines
REPL mode — interactive session for iterative diagram building
Python API — import Scene directly for maximum flexibility
Valid Excalidraw format — output files open natively in excalidraw.com

Command Reference

excalidraw-cli [--json] [--version] COMMAND

Scene Management

Command	Description
`scene new [--background COLOR] [--grid SIZE]`	Create a new empty scene
`scene load FILE`	Load an existing `.excalidraw` file
`scene save [FILE]`	Save the current scene
`scene info`	Show scene summary (element counts, background, etc.)
`scene clear`	Remove all elements
`scene background COLOR`	Change background color
`scene undo`	Undo last modification
`scene redo`	Redo last undone modification

Element Operations

Command	Description
`element add TYPE [OPTIONS]`	Add an element (rectangle, ellipse, diamond, arrow, line, text, freedraw, image, frame)
`element list [--type TYPE]`	List elements, optionally filtered by type
`element remove ID`	Remove an element by ID
`element update ID [OPTIONS]`	Update element properties
`element connect FROM_ID TO_ID`	Draw an arrow between two elements

Element add options:

--x, --y          Position (default: 0,0)
-w, --width       Width (default: 200)
-h, --height      Height (default: 100)
-l, --label       Text label
--stroke-color    Stroke color (hex, e.g. "#ff0000")
--bg-color        Background color (hex)
--fill            Fill style: hachure | cross-hatch | solid
--stroke-width    Stroke width (number)
--roughness       0=sharp, 1=normal, 2=rough
--opacity         0-100

Templates

Command	Description
`template flowchart STEPS... [-d vertical\|horizontal] [-o FILE]`	Linear flowchart; prefix step with `?` for decision diamond
`template sequence -a ACTORS -m FROM:TO:TEXT [-o FILE]`	Sequence diagram with lifelines
`template er -e NAME:field1,field2 -r A:B:label [-o FILE]`	Entity-relationship diagram
`template mindmap ROOT -b LABEL:leaf1,leaf2 [-o FILE]`	Radial mind map
`template kanban -c NAME:card1,card2 [-o FILE]`	Kanban board with columns

Export

All export commands accept --input/-i FILE to load directly from a .excalidraw file, enabling single-command export without a separate load step.

Command	Description
`export json [-o FILE] [--compact]`	Export as raw JSON
`export excalidraw FILE`	Save as `.excalidraw` file
`export svg FILE [--scale N] [--padding N]`	Export as SVG vector image
`export png FILE [--scale N] [--padding N]`	Export as high-quality PNG (default 2x DPI)
`export jpg FILE [--scale N] [--quality 1-100]`	Export as JPG (default quality 95)
`export pdf FILE [--scale N] [--padding N]`	Export as PDF document

Optional dependencies for image export:

pip install cairosvg          # Required for PNG, JPG, PDF
pip install Pillow            # Required for JPG
# Or install everything at once:
pip install -e ".[export]"

Usage Examples

1. Flowchart with decisions

excalidraw-cli template flowchart \
  "User submits form" \
  "?Input valid?" \
  "Save to database" \
  "Send confirmation" \
  "?Email delivered?" \
  "Done" \
  -o registration_flow.excalidraw

2. REST API sequence diagram

excalidraw-cli template sequence \
  -a "Browser,API Gateway,Auth Service,Database" \
  -m "0:1:POST /login" \
  -m "1:2:Validate token" \
  -m "2:3:SELECT user" \
  -m "3:2:User row" \
  -m "2:1:JWT token" \
  -m "1:0:200 OK + token" \
  -o api_auth.excalidraw

3. Database ER diagram

excalidraw-cli template er \
  -e "User:id,username,email,created_at" \
  -e "Post:id,title,body,published_at" \
  -e "Comment:id,body,created_at" \
  -r "User:Post:writes" \
  -r "Post:Comment:has many" \
  -r "User:Comment:authors" \
  -o blog_schema.excalidraw

4. Project mind map

excalidraw-cli template mindmap "My SaaS App" \
  -b "Frontend:React,TypeScript,Tailwind" \
  -b "Backend:Python,FastAPI,SQLAlchemy" \
  -b "Infrastructure:AWS,Docker,Terraform" \
  -b "Data:PostgreSQL,Redis,S3" \
  -o architecture.excalidraw

5. Sprint Kanban board

excalidraw-cli template kanban \
  -c "Backlog:Auth flow,Dark mode,Search" \
  -c "In Progress:User profiles,API docs" \
  -c "Review:Payment integration" \
  -c "Done:Landing page,CI/CD pipeline" \
  -o sprint_board.excalidraw

6. Manual element-by-element construction

# Create a scene and build step by step
excalidraw-cli scene new --background "#f5f5dc"

excalidraw-cli element add rectangle --x 100 --y 50 -w 180 -h 80 \
  -l "Client" --bg-color "#a5d8ff" --fill solid

excalidraw-cli element add rectangle --x 100 --y 250 -w 180 -h 80 \
  -l "Server" --bg-color "#d0bfff" --fill solid

excalidraw-cli element add text --x 80 --y 10 -l "System Overview"

excalidraw-cli scene save system.excalidraw

7. Export to PNG, JPG, PDF, SVG

# Generate a diagram and export to all formats in one go
excalidraw-cli template flowchart "Start" "Process" "End" -o diagram.excalidraw

# High-quality PNG (2x scale by default for crisp images)
excalidraw-cli export png diagram.png -i diagram.excalidraw

# Ultra-high-res PNG (4x scale, great for presentations)
excalidraw-cli export png diagram_4x.png -i diagram.excalidraw --scale 4.0

# JPG with custom quality
excalidraw-cli export jpg diagram.jpg -i diagram.excalidraw --quality 95

# PDF for documents and printing
excalidraw-cli export pdf diagram.pdf -i diagram.excalidraw

# SVG for web embedding
excalidraw-cli export svg diagram.svg -i diagram.excalidraw

8. JSON output for scripting / AI agents

# Every command supports --json
excalidraw-cli --json scene new
# {"status": "created", "background": "#ffffff", "grid": null}

excalidraw-cli --json element add rectangle --x 100 --y 100
# {"status": "added", "id": "abc123...", "type": "rectangle"}

excalidraw-cli --json element list
# [{"id": "abc123...", "type": "rectangle", "x": 100, "y": 100, ...}]

excalidraw-cli --json scene info
# {"total_elements": 1, "element_types": {"rectangle": 1}, ...}

Using with AI Agents

excalidraw-cli is designed to be controlled by AI agents via structured JSON I/O. Here are patterns for common AI workflows:

Claude Code / Claude

You: Create an architecture diagram for a microservices app with
     API gateway, user service, order service, and PostgreSQL.

Claude: I'll use excalidraw-cli to generate that diagram.

> excalidraw-cli --json scene new --background "#fafafa"
> excalidraw-cli --json element add rectangle --x 300 --y 50 -w 200 -h 70 -l "API Gateway" --bg-color "#a5d8ff" --fill solid
> excalidraw-cli --json element add rectangle --x 100 --y 200 -w 180 -h 70 -l "User Service" --bg-color "#b2f2bb" --fill solid
> excalidraw-cli --json element add rectangle --x 400 --y 200 -w 180 -h 70 -l "Order Service" --bg-color "#d0bfff" --fill solid
> excalidraw-cli --json element add rectangle --x 250 --y 380 -w 200 -h 70 -l "PostgreSQL" --bg-color "#f9e2af" --fill solid
> excalidraw-cli --json element connect <gateway_id> <user_svc_id>
> excalidraw-cli --json element connect <gateway_id> <order_svc_id>
> excalidraw-cli --json element connect <user_svc_id> <db_id>
> excalidraw-cli --json element connect <order_svc_id> <db_id>
> excalidraw-cli --json scene save microservices.excalidraw

Created microservices.excalidraw — open in excalidraw.com to view.

Python scripting (agent or automation)

from cli_anything.excalidraw.core import Scene
from cli_anything.excalidraw.templates import flowchart

# Use templates for common patterns
scene = flowchart(["Receive order", "?In stock?", "Ship", "Backorder"])
scene.save("order_flow.excalidraw")

# Or build custom diagrams
scene = Scene()
scene.set_background("#1e1e2e")
web = scene.add_shape("rectangle", x=200, y=50, width=200, height=70,
                       label="Web App", backgroundColor="#89b4fa", fillStyle="solid")
api = scene.add_shape("rectangle", x=200, y=200, width=200, height=70,
                       label="API", backgroundColor="#a6e3a1", fillStyle="solid")
scene.connect(web, api)
scene.save("custom.excalidraw")

Shell pipeline

# Generate a diagram from a list of steps in a file
cat steps.txt | xargs excalidraw-cli template flowchart -o pipeline.excalidraw

# Batch generate diagrams
for project in frontend backend infra; do
  excalidraw-cli template mindmap "$project" \
    -b "$(cat ${project}_topics.txt)" \
    -o "${project}_map.excalidraw"
done

REPL mode for interactive building

$ excalidraw-cli
excalidraw-cli v0.1.0 — interactive mode
Type 'help' for commands, 'quit' to exit.

excalidraw> scene new
  status: created
excalidraw> element add rectangle --x 100 --y 100 -l "Hello"
  status: added
excalidraw> element list
  - abc123  type=rectangle  (100,100)  200x100
excalidraw> scene save hello.excalidraw
  status: saved
excalidraw> quit
Bye!

Project Structure

excalidraw-cli/
├── README.md                  # This file
├── LICENSE                    # MIT License
├── CONTRIBUTING.md            # Contribution guidelines
├── agent-harness/
│   ├── setup.py               # Package installation
│   ├── cli_anything/
│   │   └── excalidraw/
│   │       ├── __init__.py    # Version
│   │       ├── core.py        # Scene & element engine
│   │       ├── templates.py   # Diagram templates
│   │       ├── render.py      # SVG renderer + PNG/JPG/PDF export
│   │       └── cli.py         # Click CLI + REPL
│   └── tests/
│       ├── test_core.py       # 39 unit tests
│       ├── test_templates.py  # 11 template tests
│       ├── test_render.py     # 43 render/export tests
│       └── test_cli.py        # 29 E2E CLI tests
├── examples/
│   ├── flowchart.sh           # Flowchart example
│   ├── sequence.sh            # Sequence diagram example
│   ├── er_diagram.sh          # ER diagram example
│   ├── mindmap.sh             # Mind map example
│   ├── kanban.sh              # Kanban board example
│   ├── manual_build.sh        # Step-by-step manual build
│   └── ai_agent_example.py    # Python API usage example
└── TEST.md                    # Test documentation & results

Architecture

                     ┌──────────────────────┐
                     │     CLI (cli.py)     │  Click commands + REPL
                     │     --json flag      │  Human & agent output
                     └──────────┬───────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          ▼                     ▼                     ▼
 ┌──────────────┐      ┌──────────┐      ┌──────────────────┐
 │ templates.py │      │ core.py  │      │   render.py      │
 │  flowchart   │      │  Scene   │      │  SVG renderer    │
 │  sequence    │      │  Element │      │  ┌──── PNG (2x+) │
 │  er / mind   │      │  undo/   │      │  ├──── JPG       │
 │  kanban      │      │  redo    │      │  ├──── PDF       │
 └──────────────┘      └──────────┘      │  └──── SVG       │
                             │           └──────────────────┘
                    ┌────────┴────────┐
                    │ .excalidraw JSON │
                    │  (open in web)  │
                    └─────────────────┘

Testing

cd agent-harness
pip install pytest
python -m pytest tests/ -v

154 tests covering:

Core (39 tests) — element creation, scene management, persistence, undo/redo
Templates (11 tests) — all 5 diagram templates with edge cases
Render/Export (43 tests) — SVG generation, PNG/JPG/PDF output, format validation, CLI integration
CLI E2E (29 tests) — every command with JSON output validation

Supported Element Types

Type	Description	Key Properties
`rectangle`	Rectangle shape	x, y, width, height, label, fill, stroke
`ellipse`	Ellipse/circle	x, y, width, height, label
`diamond`	Diamond (decision)	x, y, width, height, label
`arrow`	Arrow with arrowheads	start/end binding, points, arrowhead style
`line`	Straight/multi-point line	points array, stroke style
`text`	Text element	text, fontSize, fontFamily, textAlign
`freedraw`	Freehand drawing	points, pressure, simulatePressure
`image`	Embedded image	fileId, status, scale
`frame`	Grouping frame	name

Excalidraw File Format

The .excalidraw format is plain JSON:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 200,
      "height": 100,
      "strokeColor": "#1e1e1e",
      "backgroundColor": "transparent",
      "fillStyle": "hachure",
      "roughness": 1,
      "opacity": 100,
      ...
    }
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

Files generated by excalidraw-cli are fully compatible with:

excalidraw.com (File > Open)
VS Code Excalidraw extension
Obsidian Excalidraw plugin
Any tool that reads the .excalidraw JSON format

Star History

Built With

CLI-Anything — methodology for agent-native CLI generation
Excalidraw — open source hand-drawn style whiteboard
Click — Python CLI framework
prompt_toolkit — REPL interface

Contributing

See CONTRIBUTING.md for guidelines. In short:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for new functionality
Ensure all 154+ tests pass (python -m pytest tests/ -v)
Submit a pull request

License

This project is licensed under the MIT License — see LICENSE for details.

Acknowledgments

HKUDS for the CLI-Anything framework and methodology
Excalidraw team for the amazing open source whiteboard
The Excalidraw JSON schema docs for format specification

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
agent-harness		agent-harness
examples		examples
.gitignore		.gitignore
AGENT.md		AGENT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
TEST.md		TEST.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

✏️ excalidraw-cli

Why excalidraw-cli?

Quick Start

Installation

Your first diagram in 10 seconds

Features

Command Reference

Scene Management

Element Operations

Templates

Export

Usage Examples

1. Flowchart with decisions

2. REST API sequence diagram

3. Database ER diagram

4. Project mind map

5. Sprint Kanban board

6. Manual element-by-element construction

7. Export to PNG, JPG, PDF, SVG

8. JSON output for scripting / AI agents

Using with AI Agents

Claude Code / Claude

Python scripting (agent or automation)

Shell pipeline

REPL mode for interactive building

Project Structure

Architecture

Testing

Supported Element Types

Excalidraw File Format

Star History

Built With

Contributing

License

Acknowledgments

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages