Excalidraw CLI
Generate editable Excalidraw diagrams from a text DSL, JSON, or Graphviz DOT — built for agents and scripts.
- Source repo
- swiftlysingh/excalidraw-cli
- Stars
- ★ 315
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 67/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who want to generate a flowchart from one line of DSL in a script, then refine it in Excalidraw.
- Not a fit if
- Users who want manual drag-and-drop drawing or live collaboration in a browser
- Environments that cannot install Node.js 20.19+
- Source review
- 67/100 · Some gaps
What does this agent do, and when should you use it?
excalidraw-cli is a Node.js command-line tool that turns a text DSL, JSON, or Graphviz DOT into an editable .excalidraw file. It uses ELK.js for automatic layout, supports top-bottom, bottom-top, left-right, and right-left directions, and can export existing files to PNG or SVG. Beyond the CLI, it exposes a programmatic API with createFlowchartFromDSL, createFlowchartFromJSON, convertToSVG, and convertToPNG. The repository also ships skills for Claude Code, Codex, and Cursor, a Gemini CLI extension, and a Claude Code plugin. Output files open in Excalidraw or Obsidian's Excalidraw plugin for further editing.
When you run excalidraw-cli create, the tool reads a file, an --inline string, or stdin, parses DSL, JSON, or DOT input, builds a node-and-edge graph, computes layout with ELK.js, and writes a .excalidraw file. The DSL supports [Label] rectangles, {Label} diamonds, (Label) ellipses, [[Label]] databases, and ![path] image nodes, along with ->, <-, <->, --> arrow forms and quoted edge labels. Directives such as @direction and @spacing, plus @node style blocks, control flow direction, spacing, and fill styling. The convert subcommand exports an existing .excalidraw file to PNG or SVG with --scale, --dark, and --no-export-background options. The parse subcommand validates input and prints the graph without writing a file.
- Developers who want to generate a flowchart from one line of DSL in a script, then refine it in Excalidraw.
- Claude Code, Codex, or Cursor users who install the skill and let an agent draft architecture diagrams from code.
- Teams migrating existing Graphviz DOT diagrams into editable Excalidraw files.
- Engineering teams that batch-convert
.excalidrawfiles to PNG or SVG in CI or docs pipelines. - TypeScript developers generating diagrams programmatically via createFlowchartFromJSON.
How do you install or deploy this agent?
Requires Node.js >=20.19.0.
Install globally via npm:
npm install -g @swiftlysingh/excalidraw-cliOr via Homebrew (installs Node.js automatically):
brew install swiftlysingh/tap/excalidraw-cliRun without a global install:
npx --yes @swiftlysingh/excalidraw-cli create --inline "[A] -> [B]" -o diagram.excalidrawBuild from source:
git clone https://github.com/swiftlysingh/excalidraw-cli.git
cd excalidraw-cli
npm install
npm run build
npm linkInstall the agent skill:
npx skills add swiftlysingh/excalidraw-cliClaude Code plugin:
/plugin marketplace add swiftlysingh/excalidraw-cli
/plugin install excalidraw-cli@excalidraw-cliHow do you use this agent?
Create from inline DSL:
excalidraw-cli create --inline "(Start) -> [Process] -> {Decision?}" -o flow.excalidrawCreate from a file or stdin:
excalidraw-cli create flowchart.dsl -o diagram.excalidraw
echo "[A] -> [B] -> [C]" | excalidraw-cli create --stdin -o diagram.excalidrawCreate from DOT:
excalidraw-cli create --format dot --inline 'digraph { A [label="Start"]; B [label="Process"]; A -> B; }' -o flow.excalidrawExport to PNG or SVG:
excalidraw-cli convert diagram.excalidraw --format png --scale 2 --dark
excalidraw-cli convert diagram.excalidraw --format svg --no-export-backgroundJSON input example:
{
"nodes": [
{ "id": "start", "type": "ellipse", "label": "Start" },
{ "id": "process", "type": "rectangle", "label": "Process" },
{ "id": "end", "type": "ellipse", "label": "End" }
],
"edges": [
{ "from": "start", "to": "process" },
{ "from": "process", "to": "end" }
],
"options": { "direction": "TB", "nodeSpacing": 50 }
}Programmatic call:
import { createFlowchartFromDSL } from '@swiftlysingh/excalidraw-cli';
const json = await createFlowchartFromDSL('(Start) -> [Process] -> (End)');What are this agent's strengths and limitations?
- ELK.js auto-layout produces tidy diagrams without manually placing nodes.
- One CLI accepts DSL, JSON, and Graphviz DOT, lowering migration effort.
- Exports PNG/SVG in addition to
.excalidraw, with dark mode, scaling, and padding. - Ships skills for Claude Code, Codex, and Cursor plus a Claude Code plugin, so agent integration is documented.
- MIT-licensed with both an npm package and a Homebrew tap.
- Requires Node.js >=20.19.0; Node 18 is no longer supported.
- Image nodes are local files only;
![path]does not accept remote URLs. - DOT subgraphs are flattened, so complex Graphviz attributes may not be preserved.
- Edge labels must use the fully specified
[A] -> "label" -> [B]form; mixed forms are rejected. - No in-repo AGENTS.md or extra integration guide; agent-side behavior is documented only in the README.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Excalidraw CLI This agent | 67 · Some gaps | CLIFree | ★ 315 | today | TypeScript | Codex · Claude Code |
| Microsoft Learn MCP Server | 43 · Major gaps | MCP serverFree | ★ 2k | 6d ago | TypeScript | ChatGPT · Codex · Claude Code · Claude.ai |
| CC Workflow Studio | 50 · Major gaps | IDE extensionFree + model costs | ★ 5.4k | 3mo ago | TypeScript | ChatGPT · Codex · Claude Code |
| Deep Code CLI | 49 · Major gaps | CLIFree + model costs | ★ 2.2k | today | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Local CLI tool with a small permission surface, reading/writing only user-specified files (least_privilege 2); however create/convert write files directly with no overwrite confirmation or dry-run (user_confirmation 1) and no rollback mechanism (rollback 1). Data flow is largely transparent: input from file/inline/stdin, output to a path or stdout (data_flow_transparency 2). Image nodes are restricted to local files, but no sensitive-data handling policy is documented (sensitive_data_handling 1). Dependencies include jsdom, @resvg/resvg-js, elkjs with no lockfile audit or vulnerability-scan evidence (dependency_security 1). External effects are limited to local file writes with no network egress (external_effects 2). Source attribution is clear in README/package.json (source_attribution 2).
README CLI reference, DSL syntax, and tests are mutually consistent (self_consistency 2). Dependencies are public npm packages with explicit version ranges and a clear Node engine constraint (dependency_availability 2). Tests show explicit error messages for invalid options, unterminated DSL, and wrong output extensions (failure_messages 3).
Targets agents, scripts, and developers with DSL/JSON/DOT inputs and PNG/SVG export, covering scenarios well (audience_and_scenarios 3). Boundaries are partly documented (DOT subgraph flattening, local-only images) but advanced features defer to the man page (capability_boundaries 2). Trigger precision relies on file extensions and --format overrides; rules are clear but the rejection of mixed edge-label forms requires inference (trigger_precision 2). Environment fit is limited to Node>=20.19.0 with Homebrew bundling Node, but no platform notes for Windows (environment_fit 2).
README is well-structured with install, quick start, CLI reference, API, and examples (information_architecture 3). Multiple install paths (npm/Homebrew/source/npx) are thoroughly documented (install_notes 3). Naming and version are consistent between package.json and README, but versioning policy relies on the release workflow without an explicit semver commitment (naming_stability 2). Examples are rich across DSL, JSON, and export (examples_and_faq 3). Known limitations are only mentioned in passing with no dedicated section (known_limitations 1). MIT license file is complete (license 3). A release workflow and version number exist but no CHANGELOG file (versioning_changelog 2). Maintenance rests on a single author with an automated release flow but no governance notes (maintenance_responsibility 2).
Output is editable .excalidraw plus PNG/SVG usable directly in Excalidraw/Obsidian (output_usability 3). It has real value for agent-generated diagrams, though similar tools exist, so marginal value is moderate (marginal_value 2). Install and usage cost is low but dependencies are heavy (jsdom, resvg) (cost_benefit 2).
README claims partially map to tests and workflows (claim_traceability 2). Tests and CI workflow corroborate some behaviors (cross_source_corroboration 2). However, some README capabilities (e.g., scatter directives, man page contents) are not present in the provided files, blurring the fact/inference boundary (fact_inference_separation 1).
- create/convert write files directly with no overwrite confirmation or dry-run; users must guard against accidental overwrites.
- Dependencies are heavy (jsdom, @resvg/resvg-js, elkjs) with no lockfile audit or vulnerability-scan evidence; verify dependencies before installing.
- README mentions scatter directives and man page contents not present in the provided files, so some capability claims cannot be statically verified.
- No CHANGELOG; version changes must be inferred from the release workflow and GitHub Releases.
- Publisher identity is not verified by the FollowAgents enterprise registry, and maintenance rests on a single author.
FAQ
Does it call an external LLM or paid API?
Where can I open the generated files?
.excalidraw files open directly in Excalidraw on the web and can be imported into Obsidian's Excalidraw plugin.How complete is Graphviz DOT support?
man excalidraw-cli, and complex attributes may not survive intact.What are the PNG export limits?
appState.viewBackgroundColor and fall back to #ffffff; PNG scale is clamped between 0.1 and 10.