Skip to content
Back to search

excalidraw-cli

SkillWorks with Claude CodeGitHub

Claude Code plugin for creating Excalidraw diagrams from DSL, JSON, or Graphviz DOT.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/swiftlysingh--excalidraw-cli/badge.svg)](/listings/swiftlysingh--excalidraw-cli)

HTML

<a href="/listings/swiftlysingh--excalidraw-cli"><img src="/api/listings/swiftlysingh--excalidraw-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires `Node >=20.19.0`. Node 18 is no longer supported.

Styling and extended arrow syntax require version 1.4.0 or later. See the [releases](https://github.com/swiftlysingh/excalidraw-cli/releases) for published versions.

Using npm

npm install -g @swiftlysingh/excalidraw-cli

Homebrew

Install from the tap:

brew install swiftlysingh/tap/excalidraw-cli

Homebrew installs Node.js automatically. See the [tap README](https://github.com/swiftlysingh/homebrew-tap#readme) for upgrades and switching from an existing npm installation.

From Source (Local Development)

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

Run without a global install

npx --yes @swiftlysingh/excalidraw-cli create --inline "[A] -> [B]" -o diagram.excalidraw

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "excalidraw-cli",
  3. "description": "Claude Code plugin for creating Excalidraw diagrams from DSL, JSON, or Graphviz DOT.",
  4. "owner": {
  5. "name": "Pushpinder Singh",
  6. "url": "https://github.com/swiftlysingh"
  7. },
  8. "plugins": [
  9. {
  10. "name": "excalidraw-cli",
  11. "source": "./",
  12. "description": "Create Excalidraw flowcharts and diagrams from DSL, JSON, or Graphviz DOT, then export PNG or SVG."
  13. }
  14. ]
  15. }
README.md · README · 340 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # excalidraw-cli
  2. <p>
  3. <a href="https://www.npmjs.com/package/@swiftlysingh/excalidraw-cli"><img src="https://img.shields.io/npm/v/@swiftlysingh/excalidraw-cli" alt="npm version"></a>
  4. <a href="https://github.com/swiftlysingh/excalidraw-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
  5. </p>
  6. Generate Excalidraw diagrams from DSL, JSON, or Graphviz DOT. Built for agents and scripts.
  7. <p align="center">
  8. <img alt="This repository's src/ turned into an architecture diagram with excalidraw-cli" src="docs/demo.gif" />
  9. </p>
  10. ## Features
  11. - **Text-based DSL** for quick flowchart creation
  12. - **JSON API** for programmatic use
  13. - **Auto-layout** using ELK.js (Eclipse Layout Kernel)
  14. - **Multiple flow directions**: TB (top-bottom), BT, LR, RL
  15. - **Export to PNG & SVG** with dark mode, custom backgrounds, scale, and padding
  16. - **Programmable API** for integration into other tools
  17. ## Installation
  18. Requires `Node >=20.19.0`. Node 18 is no longer supported.
  19. Styling and extended arrow syntax require version 1.4.0 or later.
  20. See the [releases](https://github.com/swiftlysingh/excalidraw-cli/releases) for published versions.
  21. ### Using npm
  22. ```bash
  23. npm install -g @swiftlysingh/excalidraw-cli
  24. ```
  25. ### Homebrew
  26. Install from the tap:
  27. ```bash
  28. brew install swiftlysingh/tap/excalidraw-cli
  29. ```
  30. Homebrew installs Node.js automatically. See the [tap README](https://github.com/swiftlysingh/homebrew-tap#readme)
  31. for upgrades and switching from an existing npm installation.
  32. ### From Source (Local Development)
  33. ```bash
  34. git clone https://github.com/swiftlysingh/excalidraw-cli.git
  35. cd excalidraw-cli
  36. npm install
  37. npm run build
  38. npm link # Makes 'excalidraw-cli' available globally
  39. ```
  40. ### Run without a global install
  41. ```bash
  42. npx --yes @swiftlysingh/excalidraw-cli create --inline "[A] -> [B]" -o diagram.excalidraw
  43. ```
  44. ## Use with AI agents
  45. Install the [Excalidraw skill](skills/excalidraw-cli) for Claude Code, Codex, or Cursor:
  46. ```bash
  47. npx skills add swiftlysingh/excalidraw-cli
  48. ```
  49. Or copy `skills/excalidraw-cli` into `~/.claude/skills`, `~/.cursor/skills`, or `~/.codex/skills`.
  50. Gemini CLI:
  51. ```bash
  52. gemini extensions install https://github.com/swiftlysingh/excalidraw-cli
  53. ```
  54. Claude Code plugin:
  55. ```
  56. /plugin marketplace add swiftlysingh/excalidraw-cli
  57. /plugin install excalidraw-cli@excalidraw-cli
  58. ```
  59. The same marketplace add works from a shell as `claude plugin marketplace add swiftlysingh/excalidraw-cli`.
  60. ## Quick Start
  61. ### Create from DSL
  62. ```bash
  63. # Inline DSL
  64. excalidraw-cli create --inline "(Start) -> [Process] -> {Decision?}" -o flow.excalidraw
  65. # From file
  66. excalidraw-cli create flowchart.dsl -o diagram.excalidraw
  67. # From stdin
  68. echo "[A] -> [B] -> [C]" | excalidraw-cli create --stdin -o diagram.excalidraw
  69. ```
  70. ### Create from DOT
  71. ```bash
  72. excalidraw-cli create --format dot --inline 'digraph { A [label="Start"]; B [label="Process"]; A -> B; }' -o flow.excalidraw
  73. ```
  74. DOT subgraphs are flattened. See `man excalidraw-cli` for supported attributes
  75. and shape mappings.
  76. ### Export to Image
  77. ```bash
  78. # Convert an existing .excalidraw file to PNG
  79. excalidraw-cli convert diagram.excalidraw --format png
  80. # Convert with options
  81. excalidraw-cli convert diagram.excalidraw --format png --scale 2 --dark
  82. # Convert to SVG without background
  83. excalidraw-cli convert diagram.excalidraw --format svg --no-export-background
  84. ```
  85. ### DSL Syntax
  86. | Syntax | Element | Description |
  87. |--------|---------|-------------|
  88. | `[Label]` | Rectangle | Process steps, actions |
  89. | `{Label}` | Diamond | Decisions, conditionals |
  90. | `(Label)` | Ellipse | Start/End points |
  91. | `[[Label]]` | Database | Data storage |
  92. | `![path]` | Image | Local image node, default size 100x100 |
  93. | `![path](WxH)` | Image | Image node with an explicit size |
  94. | `[Label @fillStyle:hachure @backgroundColor:#a5d8ff]` | Styled node | Add inline node style attributes |
  95. | `[A] -> [B]` | Arrow | Forward connection |
  96. | `[A] <- [B]` | Reverse arrow | Connection from B to A |
  97. | `[A] <-> [B]` | Bidirectional arrow | Arrowheads on both ends |
  98. | `[A] --> [B]` | Dashed arrow | Dashed connection |
  99. | `[A] <-- [B]` | Dashed reverse arrow | Dashed connection from B to A |
  100. | `[A] <--> [B]` | Dashed bidirectional arrow | Dashed connection with arrowheads on both ends |
  101. | `[A] -> "text" -> [B]` | Labeled arrow | Double-quoted edge label |
  102. | `[A] -> 'text' -> [B]` | Labeled arrow | Single-quoted edge label |
  103. ### Example DSL
  104. ```
  105. (Start) -> [Enter Credentials] -> {Valid?}
  106. {Valid?} -> "yes" -> [Dashboard] -> (End)
  107. {Valid?} -> 'no' -> [Show Error] -> [Enter Credentials]
  108. [API] -> "GET /users?name=\"pp\" \\ cache" -> [Client]
  109. [Client] --> [Webhook]
  110. [Worker] <-- [Queue]
  111. [Service A] <--> [Service B]
  112. [Reviewer] <- [Approved]
  113. [Client] <-> [API]
  114. ```
  115. ### Edge label escaping
  116. Edge labels must use the fully specified form `[A] -> "label" -> [B]` (or single quotes instead of double quotes).
  117. Mixed forms like `[A] --> "x" -> [B]` are rejected because they are ambiguous.
  118. Shell escaping tips:
  119. ```bash
  120. # easiest: wrap the whole DSL in single quotes, use double-quoted labels inside
  121. excalidraw-cli create --inline '[API] -> "GET /users?name=\"pp\"" -> [Client]' -o api.excalidraw
  122. # if the label itself needs apostrophes, flip it
  123. excalidraw-cli create --inline "[Decision] -> 'team\'s call' -> [Next]" -o decision.excalidraw
  124. ```
  125. ### Node Styling
  126. Add shape-level styling directly to nodes with inline `@key:value` attributes:
  127. ```excalidraw
  128. (Start) -> [Enter Credentials @fillStyle:hachure @backgroundColor:#a5d8ff] -> {Valid?}
  129. {Valid?} -> "no" -> [Show Error @backgroundColor:#ffc9c9 @strokeStyle:dashed] -> [Enter Credentials]
  130. ```
  131. For repeated or shared nodes, define defaults with an `@node` block:
  132. ```excalidraw
  133. @node [Enter Credentials]
  134. fillStyle: solid
  135. backgroundColor: #a5d8ff
  136. (Start) -> [Enter Credentials @fillStyle:hachure] -> {Valid?}
  137. ```
  138. Supported node style keys:
  139. - `fillStyle`: `solid`, `hachure`, `cross-hatch`
  140. - `backgroundColor`
  141. - `strokeColor`
  142. - `strokeWidth`
  143. - `strokeStyle`: `solid`, `dashed`, `dotted`
  144. - `roughness`
  145. - `opacity`
  146. Precedence rules:
  147. - `@node` blocks provide defaults for matching nodes
  148. - inline node attributes override block values
  149. - repeated references to the same node merge explicit style properties with later values winning per property
  150. ### Directives
  151. ```
  152. @direction LR # Left to Right (default: TB)
  153. @spacing 60 # Node spacing in pixels
  154. ```
  155. Use `#` for comments outside node definitions and quoted labels.
  156. Images must be local files; relative paths resolve from the working directory.
  157. Use `![path]` for an image node. For positioning, decorations, stickers, and
  158. scatter directives, see the [man page](man/excalidraw-cli.1).
  159. ## CLI Reference
  160. | Command | Purpose |
  161. |---------|---------|
  162. | `create [input]` | Generate an editable `.excalidraw` file. Accepts a file, `--inline`, or `--stdin`. |
  163. | `convert <input> --format png\|svg` | Export an existing `.excalidraw` file. |
  164. | `parse <input>` | Validate input and print its graph without generating a file. |
  165. Use `--help` with any command for its options, or `man excalidraw-cli` for the
  166. full reference. `create -o -` writes to stdout.
  167. Both `create` and `parse` detect `.json`, `.dot`, and `.gv` files. Other files
  168. and inline/stdin input default to DSL; use `--format json` or `--format dot`
  169. to override.
  170. ## JSON API
  171. For programmatic flowchart creation:
  172. ```json
  173. {
  174. "nodes": [
  175. { "id": "start", "type": "ellipse", "label": "Start" },
  176. { "id": "process", "type": "rectangle", "label": "Process" },
  177. { "id": "end", "type": "ellipse", "label": "End" }
  178. ],
  179. "edges": [
  180. { "from": "start", "to": "process" },
  181. { "from": "process", "to": "end" }
  182. ],
  183. "options": {
  184. "direction": "TB",
  185. "nodeSpacing": 50
  186. }
  187. }
  188. ```
  189. ```bash
  190. excalidraw-cli create flowchart.json -o diagram.excalidraw
  191. ```
  192. ## Programmatic Usage
  193. ```typescript
  194. import {
  195. createFlowchartFromDSL,
  196. createFlowchartFromJSON,
  197. } from '@swiftlysingh/excalidraw-cli';
  198. // From DSL
  199. const dsl = '(Start) -> [Process] -> (End)';
  200. const json = await createFlowchartFromDSL(dsl);
  201. // From JSON input
  202. const json2 = await createFlowchartFromJSON({
  203. nodes: [
  204. { id: 'a', type: 'rectangle', label: 'Hello' },
  205. { id: 'b', type: 'rectangle', label: 'World' }
  206. ],
  207. edges: [{ from: 'a', to: 'b' }]
  208. });
  209. ```
  210. ### Export API
  211. ```typescript
  212. import { convertToSVG, convertToPNG } from '@swiftlysingh/excalidraw-cli';
  213. import { readFileSync, writeFileSync } from 'fs';
  214. // Load an existing .excalidraw file
  215. const file = JSON.parse(readFileSync('diagram.excalidraw', 'utf-8'));
  216. // Export to SVG
  217. const svg = await convertToSVG(file, { padding: 20 });
  218. writeFileSync('diagram.svg', svg);
  219. // Export to PNG with 2x scale and dark mode
  220. const png = await convertToPNG(file, {
  221. scale: 2,
  222. dark: true,
  223. });
  224. writeFileSync('diagram.png', png);
  225. ```
  226. When no background is supplied, exports use `file.appState.viewBackgroundColor`
  227. and fall back to `#ffffff`. PNG scale values are clamped to `0.1` through `10`.
  228. ## Examples
  229. Here are some flowcharts created with excalidraw-cli:
  230. ### Simple Flow
  231. ![Simple Flow](assets/up.png)
  232. ### iOS App Architecture
  233. ![iOS App Architecture](assets/ios-app-architecture.png)
  234. ### LeetCode Problem Solving Flow
  235. ![LeetCode Flow](assets/leetcode.png)
  236. Generated `.excalidraw` files open in [Excalidraw](https://excalidraw.com) and
  237. can be imported into Obsidian's Excalidraw plugin.
  238. ## Releasing
  239. Run the **Release** workflow from `main` to create the next minor version from the
  240. latest stable tag. It tests the updated package, creates a release commit and tag,
  241. then publishes npm, GitHub, and Homebrew. The version commit stays on the tag;
  242. protected `main` is unchanged.
  243. To resume a partially published release, choose **retry** and enter its existing
  244. tag. A retry does not bump the version.
  245. ## License
  246. MIT
  247. ## Other apps
  248. I also build [Holder](https://apps.apple.com/app/id6475649492) for storing cards and [RetroBudget](https://apps.apple.com/app/id6743363764) for tracking spending on iPhone.

Version history

  • v1.0.010/27/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.