/excalidraw-cli

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) |

Nodes are deduplicated by label and type. Chains such as `[A] -> [B] -> [C]` create one edge per hop. Use `#` for comments outside node definitions and quoted labels.

Labeled edges must be fully specified. Mixed forms such as `[A] --> "x" -> [B]` are rejected.

(Start) -> [Enter Credentials] -> {Valid?}
{Valid?} -> "yes" -> [Dashboard] -> (End)
{Valid?} -> 'no' -> [Show Error] -> [Enter Credentials]
[API] -> "GET /users?name=\"pp\" \\ cache" -> [Client]
[Client] --> [Webhook]
[Worker] <-- [Queue]
[Service A] <--> [Service B]
[Reviewer] <- [Approved]
[Client] <-> [API]

Node styling

Inline attributes:

(Start) -> [Enter Credentials @fillStyle:hachure @backgroundColor:#a5d8ff] -> {Valid?}
{Valid?} -> "no" -> [Show Error @backgroundColor:#ffc9c9 @strokeStyle:dashed] -> [Enter Credentials]

Shared defaults with an `@node` block. Inline attributes override the block. Later explicit values win per property.

@node [Enter Credentials]
  fillStyle: solid
  backgroundColor: #a5d8ff

(Start) -> [Enter Credentials @fillStyle:hachure] -> {Valid?}

Supported keys: `fillStyle` (`solid`, `hachure`, `cross-hatch`), `backgroundColor`, `strokeColor`, `strokeWidth`, `strokeStyle` (`solid`, `dashed`, `dotted`), `roughness`, `opacity`.

Directives

| Directive | Meaning | |-----------|---------| | `@direction TB\|BT\|LR\|RL` | Flow direction. Default `TB`. | | `@spacing N` | Node spacing in pixels. | | `@image path at X,Y` | Place a local image at absolute coordinates. | | `@image path near (NodeLabel) [anchor]` | Place a local image relative to a node. | | `@decorate path [anchor]` | Attach a decoration to the preceding node. Default anchor `top-right`. | | `@sticker name` | Sticker at `0,0`. | | `@sticker name at X,Y` | Sticker at absolute coordinates. | | `@sticker name near (NodeLabel) [anchor]` | Sticker relative to a node. | | `@library path` | Directory used to resolve sticker names. | | `@scatter path count:N [width:W] [height:H]` | Repeat an image across the canvas. |

Decoration anchors: `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right`.

Images must be local files. Relative paths resolve from the working directory. HTTP and HTTPS URLs parse but are skipped during generation with a warning.

Ready-made DSL lives in [examples/](examples/).

CLI

excalidraw-cli --help
excalidraw-cli --version
excalidraw-cli help create

`create [input]`

Generate an `.excalidraw` file from a file, `--inline`, or `--stdin`.

| Flag | Meaning | |------|---------| | `-o, --output <file>` | Output path. Default `flowchart.excalidraw`. Use `-` for stdout. | | `-f, --format <type>` | `dsl`, `json`, or `dot`. Default `dsl`. | | `--inline <input>` | Inline DSL, JSON, or DOT string. | | `--stdin` | Read input from stdin. | | `-d, --direction <dir>` | Override direction: `TB`, `BT`, `LR`, `RL`. | | `-s, --spacing <n>` | Override node spacing. Non-negative integer. | | `--verbose` | Print parse and layout progress. |

Input source order: `--inline`, then `--stdin`, then the positional file. One of the three is required.

When the positional file is used and `--format` is omitted, `.json` selects JSON and `.dot` or `.gv` selects DOT. Any other extension is DSL. `--inline` and `--stdin` stay DSL unless `--format` is set. An explicit `--format` always wins.

`--direction` and `--spacing` override values from DSL directives, JSON `options`, or DOT `rankdir` / spacing attributes.

excalidraw-cli create --inline "(Start) -> [Process] -> {Decision?}" -o flow.excalidraw

excalidraw-cli create --inline "$(cat <<'EOF'
(Start)