excalidraw-cli
excalidraw-cli turns a text description, JSON or Graphviz DOT into an editable Excalidraw diagram and exports PNG and SVG for agents
- 319 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The command writes diagram and image files to the chosen folder and needs no network
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/excalidraw-cliDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The command writes diagram and image files to the chosen folder and needs no network
This is third-party code. Review the repository files before installing.
What it does
The excalidraw-cli package builds `.excalidraw` files from a short text language: `[Label]` draws a rectangle, `{Label}` a decision diamond, `(Label)` a start or end ellipse, `[[Label]]` a database, and the arrows `->`, `-->` and `<->` set solid, dashed and two-way links with labels. The source can also be JSON or Graphviz DOT. ELK.js computes node placement, and direction is one of TB, BT, LR and RL. The `convert` command exports a finished file to PNG or SVG with dark mode, scale, padding and a transparent background. The `create` command writes Excalidraw JSON only, and `convert` produces the images. The `skills/excalidraw-cli` folder holds a skill for Claude Code, Codex and Cursor, and `.claude-plugin` describes a plugin. The agent splits a request into nodes and links, writes a small `.dsl` and runs `create`, then `convert` if needed.
Who it is for. Developers and technical writers who ask an agent to draw an architecture, flowchart or decision tree and want a file editable in Excalidraw.
Good fit when
- A service diagram must come from a text description and then be tweaked by hand in Excalidraw
- The repository holds a Graphviz DOT graph that needs converting to an editable form
- A support decision tree is described in a few lines and the agent draws it
- Documentation needs PNG and SVG in dark mode at a chosen scale
- The agent builds a diagram from the `src/` directory structure and saves it in the project root
Not a fit when
- You need a Mermaid or PlantUML diagram: the tool produces Excalidraw files only
- The diagram goes beyond an ordinary flowchart and needs hand design
- The machine has Node older than 20.19: version 18 is unsupported
- DOT subgraphs matter as groups: they are flattened on import
Example request
Draw our API layout: client, gateway, three services and a database, save it as api.excalidraw and export a dark mode PNGLimitations
- Node.js 20.19 or newer is required; Node 18 is no longer supported, so older machines need a Node update first.
- Node-level styling and extended arrows work from version 1.4.0; on earlier versions the `@fillStyle:` syntax will not apply.
- Graphviz DOT subgraphs are flattened on import; the supported attributes are listed in `man excalidraw-cli`.
- The `create` command does not write images: passing `-o file.png` is rejected and `convert` does the export.
How to disable. Run `npm uninstall -g @swiftlysingh/excalidraw-cli` or `brew uninstall excalidraw-cli`, then delete the `excalidraw-cli` skill folder from the agent skills directory.
FAQ
How do I install excalidraw-cli for Claude Code?
Run `npm install -g @swiftlysingh/excalidraw-cli`, then `npx skills add swiftlysingh/excalidraw-cli` for the skill. There is also a Claude Code plugin and a Homebrew install.
How do the input formats differ?
DSL fits short flowcharts and goes straight into `--inline`. JSON suits programmatic node generation. DOT is for graphs that already exist in Graphviz.
How do I get a PNG from a diagram?
Create the `.excalidraw` file with `create`, then run `excalidraw-cli convert diagram.excalidraw --format png`. Add `--dark` and `--scale 2` for a dark theme and double size.
How do I open the result?
Open the `.excalidraw` file on excalidraw.com through File and Open, then edit it like any drawing.
Do I need a global install?
No, `npx --yes @swiftlysingh/excalidraw-cli create ...` runs it without installing.
Discussion
No questions or reviews yet.
Related
CLI toolsExcalidraw CLI renders .excalidraw files and Mermaid diagrams to PNG and SVG locally with no account, and gives agents JSON.
A skill that draws an Excalidraw-style diagram from a text prompt and returns an editor link, an animation and a PNG.
Excalidraw MCP Server
Excalidraw MCP Server, CLI & Agent Skill
A live Excalidraw canvas for the agent: creates, edits and exports diagrams over MCP or CLI, sees its own work via screenshots and saves .excalidraw files into
A skill that builds Excalidraw diagrams from a description and checks their look with a Playwright render
A Codex plugin that redraws a scientific figure from a reference on the live draw.io canvas step by step, then validates and exports the file
Draw.io Skill
Draw.io Skill for Claude & Codex
Skills for draw.io diagrams: architecture, networks, flowcharts, import from Terraform and code, offline generation from YAML and PNG and SVG export
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| excalidraw-cli (this card) | no | 319 | ||
| Excalidraw Diagram Skill | no | 5,240 | a skill where the agent assembles Excalidraw diagrams and checks the result, while this is a ready command with a description language | |
| Excalidraw MCP Server | no | not required | 2,646 | an MCP server and CLI for a live Excalidraw canvas rather than file generation from text |
README in short
The page lists features and three install routes: npm, Homebrew and a source build. Next come running without install, wiring the skill to an agent and examples of building diagrams from DSL and DOT. The rest has the syntax table, export options and the programmatic API for embedding in other tools.
README badge
Original SKILL.md
---
name: excalidraw-cli
description: Create editable Excalidraw flowcharts and diagrams, or export .excalidraw files to PNG or SVG.
license: MIT
compatibility: Requires Node.js >=20.19.0 and excalidraw-cli (this repo after npm run build, a global install, or npx --yes @swiftlysingh/excalidraw-cli).
---
# Excalidraw CLI
Create editable `.excalidraw` diagrams from text, then optionally export PNG or SVG.
This skill lives with the CLI at https://github.com/swiftlysingh/excalidraw-cli.
## When to use
- User asks for a flowchart, architecture diagram, decision tree, or process visualization
- User mentions Excalidraw, `.excalidraw`, or this CLI
- User wants a diagram from a description or from code in the workspace
- User wants to preview or export an existing `.excalidraw` file as PNG or SVG
## Command
Use the first form that exists:
1. In this repo after `npm run build`: `node dist/cli.js`
2. Installed binary: `excalidraw-cli`
3. No install: `npx --yes @swiftlysingh/excalidraw-cli`
Examples below use `excalidraw-cli`. Substitute the form you are running.
`create` writes Excalidraw JSON only. It rejects `-o file.png` and `-o file.svg`. Export images with `convert` after `create`.
## Workflow
1. Extract nodes, decisions, and edges from the request.
2. Prefer DSL. Use DOT when the user already has Graphviz. Use JSON for programmatic node/edge lists.
3. Write a small `.dsl` file for anything beyond one line. Use `--inline` for short diagrams.
4. Run `create`, then `convert` if the user wants a PNG or SVG preview.
5. Tell the user the output path and that they can open the `.excalidraw` file at https://excalidraw.com via File > Open.
## DSL
| Syntax | Element |
|--------|---------|
| `[Label]` | Rectangle (process, action) |
| `{Label}` | Diamond (decision). A trailing `?` is just label text. |
| `(Label)` | Ellipse (start/end) |
| `[[Label]]` | Database |
| `![path]` | Local image node, default 100x100 |
| `` | Local image node with explicit size |
| `[Label @key:value]` | Styled node |
| `->` | Solid arrow |
| `<-` | Reverse solid arrow |
| `<->` | Bidirectional solid arrow |
| `-->` | Dashed arrow |
| `<--` | Reverse dashed arrow |
| `<-->` | Bidirectional dashed arrow |
| `-> "text" ->` | Labeled solid arrow (double quotes) |
| `-> 'text' ->` | Labeled solid arrow (single quotes) |