Create Excalidraw flowcharts and diagrams from text-based DSL or JSON.
- Text-based DSL for quick flowchart creation
- JSON API for programmatic use
- Auto-layout using ELK.js (Eclipse Layout Kernel)
- Multiple flow directions: TB (top-bottom), BT, LR, RL
- Export to PNG & SVG with dark mode, custom backgrounds, scale, and padding
- Programmable API for integration into other tools
Requires Node >=20.19.0. Node 18 is no longer supported.
npm i @swiftlysingh/excalidraw-cligit clone https://github.com/swiftlysingh/excalidraw-cli.git
cd excalidraw-cli
npm install
npm run build
npm link # Makes 'excalidraw-cli' available globally# Run directly with node
node dist/cli.js create --inline "[A] -> [B]" -o diagram.excalidraw# Inline DSL
excalidraw-cli create --inline "(Start) -> [Process] -> {Decision?}" -o flow.excalidraw
# From file
excalidraw-cli create flowchart.dsl -o diagram.excalidraw
# From stdin
echo "[A] -> [B] -> [C]" | excalidraw-cli create --stdin -o diagram.excalidraw# Convert an existing .excalidraw file to PNG
excalidraw-cli convert diagram.excalidraw --format png
# Convert with options
excalidraw-cli convert diagram.excalidraw --format png --scale 2 --dark
# Convert to SVG without background
excalidraw-cli convert diagram.excalidraw --format svg --no-export-background| Syntax | Element | Description |
|---|---|---|
[Label] |
Rectangle | Process steps, actions |
{Label} |
Diamond | Decisions, conditionals |
(Label) |
Ellipse | Start/End points |
[[Label]] |
Database | Data storage |
[Label @fillStyle:hachure @backgroundColor:#a5d8ff] |
Styled node | Add inline node style attributes |
-> |
Arrow | Connection |
--> |
Dashed Arrow | Dashed connection |
-> "text" -> |
Labeled Arrow | Connection with label |
(Start) -> [Enter Credentials] -> {Valid?}
{Valid?} -> "yes" -> [Dashboard] -> (End)
{Valid?} -> "no" -> [Show Error] -> [Enter Credentials]
Add shape-level styling directly to nodes with inline @key:value attributes:
(Start) -> [Enter Credentials @fillStyle:hachure @backgroundColor:#a5d8ff] -> {Valid?}
{Valid?} -> "no" -> [Show Error @backgroundColor:#ffc9c9 @strokeStyle:dashed] -> [Enter Credentials]
For repeated or shared nodes, define defaults with an @node block:
@node [Enter Credentials]
fillStyle: solid
backgroundColor: #a5d8ff
(Start) -> [Enter Credentials @fillStyle:hachure] -> {Valid?}
Supported node style keys:
fillStyle:solid,hachure,cross-hatchbackgroundColorstrokeColorstrokeWidthstrokeStyle:solid,dashed,dottedroughnessopacity
Precedence rules:
@nodeblocks provide defaults for matching nodes- inline node attributes override block values
- repeated references to the same node merge explicit style properties with later values winning per property
@direction LR # Left to Right (default: TB)
@spacing 60 # Node spacing in pixels
Create an Excalidraw flowchart.
excalidraw-cli create [input] [options]Options:
-o, --output <file>- Output file path (default: flowchart.excalidraw)-f, --format <type>- Input format: dsl, json, dot (default: dsl)--inline <dsl>- Inline DSL string--stdin- Read from stdin-d, --direction <dir>- Flow direction: TB, BT, LR, RL-s, --spacing <n>- Node spacing in pixels--verbose- Verbose output
Convert an existing .excalidraw file to PNG or SVG.
excalidraw-cli convert <input> [options]Options:
--format <format>- (required) Export format:pngorsvg-o, --output <file>- Output file path (default: input file with swapped extension)--export-background / --no-export-background- Include or exclude background--background-color <color>- Background color (default: #ffffff)--dark- Export with dark mode theme--embed-scene- Embed scene data in exported image--padding <n>- Padding around content in pixels (default: 10)--scale <n>- Scale factor for PNG export (default: 1)--verbose- Verbose output
Parse and validate input without generating output.
excalidraw-cli parse <input> [options]For programmatic flowchart creation:
{
"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
}
}excalidraw-cli create flowchart.json -o diagram.excalidrawimport {
createFlowchartFromDSL,
createFlowchartFromJSON,
convertToSVG,
convertToPNG,
} from '@swiftlysingh/excalidraw-cli';
// From DSL
const dsl = '(Start) -> [Process] -> (End)';
const json = await createFlowchartFromDSL(dsl);
// From JSON input
const input = {
nodes: [
{ id: 'a', type: 'rectangle', label: 'Hello' },
{ id: 'b', type: 'rectangle', label: 'World' }
],
edges: [{ from: 'a', to: 'b' }]
};
const json2 = await createFlowchartFromJSON(input);import { convertToSVG, convertToPNG } from '@swiftlysingh/excalidraw-cli';
import { readFileSync, writeFileSync } from 'fs';
// Load an existing .excalidraw file
const file = JSON.parse(readFileSync('diagram.excalidraw', 'utf-8'));
// Export to SVG
const svg = await convertToSVG(file, { padding: 20 });
writeFileSync('diagram.svg', svg);
// Export to PNG with 2x scale and dark mode
const png = await convertToPNG(file, {
scale: 2,
dark: true,
});
writeFileSync('diagram.png', png);@excalidraw/utils remains a required runtime dependency for image export. The CLI uses its exportToSvg() implementation for SVG generation, and reuses the bundled Excalidraw font assets so server-side PNG rendering keeps text output close to the browser version.
Here are some flowcharts created with excalidraw-cli:
The generated .excalidraw files can be:
- Opened directly in Excalidraw (File > Open)
- Imported into Obsidian with the Excalidraw plugin
- Used with any tool that supports the Excalidraw format
With the convert command, you can also generate:
- SVG — scalable vector graphics, ideal for embedding in docs or web pages
- PNG — raster images at any scale (1×, 2×, 3×, etc.) for presentations or sharing
MIT