excalidraw-cli

Create Excalidraw flowcharts and diagrams from text-based DSL or JSON.

Features

- 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
- Programmable API for integration into other tools

Installation

$3

``bash
npm i @swiftlysingh/excalidraw-cli
`

$3

`bash
git clone https://github.com/swiftlysingh/excalidraw-cli.git
cd excalidraw-cli
npm install
npm run build
npm link # Makes 'excalidraw-cli' available globally
`

$3

`bash


Run directly with node


node dist/cli.js create --inline "[A] -> [B]" -o diagram.excalidraw
`

Quick Start

$3

`bash


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
`

$3

| Syntax | Element | Description |
|--------|---------|-------------|
| [Label] | Rectangle | Process steps, actions |
| {Label} | Diamond | Decisions, conditionals |
| (Label) | Ellipse | Start/End points |
| [[Label]] | Database | Data storage |
| -> | Arrow | Connection |
| --> | Dashed Arrow | Dashed connection |
| -> "text" -> | Labeled Arrow | Connection with label |

$3

`
(Start) -> [Enter Credentials] -> {Valid?}
{Valid?} -> "yes" -> [Dashboard] -> (End)
{Valid?} -> "no" -> [Show Error] -> [Enter Credentials]
`

$3

`
@direction LR # Left to Right (default: TB)
@spacing 60 # Node spacing in pixels
`

CLI Reference

$3

#### create

Create an Excalidraw flowchart.

`bash
excalidraw-cli create [input] [options]
`

Options:
- -o, --output - Output file path (default: flowchart.excalidraw)
- -f, --format - Input format: dsl, json (default: dsl)
- --inline - Inline DSL string
- --stdin - Read from stdin
- -d, --direction

- Flow direction: TB, BT, LR, RL
- -s, --spacing - Node spacing in pixels
- --verbose - Verbose output

#### parse

Parse and validate input without generating output.

`bash
excalidraw-cli parse [options]
`

JSON API

For programmatic flowchart creation:

`json
{
"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
}
}
`

`bash
excalidraw-cli create flowchart.json -o diagram.excalidraw
`

Programmatic Usage

`typescript
import { createFlowchartFromDSL, createFlowchartFromJSON } from '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);
`

Examples

Here are some flowcharts created with excalidraw-cli:

$3

!Simple Flow

$3

!iOS App Architecture

$3

!LeetCode Flow

Output

The generated .excalidraw` files can be:

1. Opened directly in Excalidraw (File > Open)
2. Imported into Obsidian with the Excalidraw plugin
3. Used with any tool that supports the Excalidraw format

License

MIT