![\"npm](\"https://img.shields.io/npm/v/@swiftlysingh/excalidraw-cli\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-blue\"){kind=icon}
\n\n
\n \n
\n Create Excalidraw flowcharts and diagrams from text-based DSL, JSON, or Graphviz DOT.\n
\n\n## Features\n\n- **Text-based DSL** for quick flowchart creation\n- **JSON API** for programmatic use\n- **Auto-layout** using ELK.js (Eclipse Layout Kernel)\n- **Multiple flow directions**: TB (top-bottom), BT, LR, RL\n- **Export to PNG & SVG** with dark mode, custom backgrounds, scale, and padding\n- **Programmable API** for integration into other tools\n\n## Installation\n\nRequires `Node >=20.19.0`. Node 18 is no longer supported.\n\nStyling and extended arrow syntax require version 1.4.0 or later.\nSee the [releases](https://github.com/swiftlysingh/excalidraw-cli/releases) for published versions.\n\n### Using npm\n\n```bash\nnpm install -g @swiftlysingh/excalidraw-cli\n```\n\n### Homebrew\n\nInstall from the tap:\n\n```bash\nbrew install swiftlysingh/tap/excalidraw-cli\n```\n\nHomebrew installs Node.js automatically. See the [tap README](https://github.com/swiftlysingh/homebrew-tap#readme)\nfor upgrades and switching from an existing npm installation.\n\n### From Source (Local Development)\n\n```bash\ngit clone https://github.com/swiftlysingh/excalidraw-cli.git\ncd excalidraw-cli\nnpm install\nnpm run build\nnpm link # Makes 'excalidraw-cli' available globally\n```\n\n### Run without a global install\n\n```bash\nnpx --yes @swiftlysingh/excalidraw-cli create --inline \"[A] -> [B]\" -o diagram.excalidraw\n```\n\n## Quick Start\n\n### Create from DSL\n\n```bash\n# Inline DSL\nexcalidraw-cli create --inline \"(Start) -> [Process] -> {Decision?}\" -o flow.excalidraw\n\n# From file\nexcalidraw-cli create flowchart.dsl -o diagram.excalidraw\n\n# From stdin\necho \"[A] -> [B] -> [C]\" | excalidraw-cli create --stdin -o diagram.excalidraw\n```\n\n### Create from DOT\n\n```bash\nexcalidraw-cli create --format dot --inline 'digraph { A [label=\"Start\"]; B [label=\"Process\"]; A -> B; }' -o flow.excalidraw\n```\n\nDOT subgraphs are flattened. See `man excalidraw-cli` for supported attributes\nand shape mappings.\n\n### Export to Image\n\n```bash\n# Convert an existing .excalidraw file to PNG\nexcalidraw-cli convert diagram.excalidraw --format png\n\n# Convert with options\nexcalidraw-cli convert diagram.excalidraw --format png --scale 2 --dark\n\n# Convert to SVG without background\nexcalidraw-cli convert diagram.excalidraw --format svg --no-export-background\n```\n\n### DSL Syntax\n\n| Syntax | Element | Description |\n|--------|---------|-------------|\n| `[Label]` | Rectangle | Process steps, actions |\n| `{Label}` | Diamond | Decisions, conditionals |\n| `(Label)` | Ellipse | Start/End points |\n| `[[Label]]` | Database | Data storage |\n| `![path]` | Image | Local image node, default size 100x100 |\n| `` | Image | Image node with an explicit size |\n| `[Label @fillStyle:hachure @backgroundColor:#a5d8ff]` | Styled node | Add inline node style attributes |\n| `[A] -> [B]` | Arrow | Forward connection |\n| `[A] <- [B]` | Reverse arrow | Connection from B to A |\n| `[A] <-> [B]` | Bidirectional arrow | Arrowheads on both ends |\n| `[A] --> [B]` | Dashed arrow | Dashed connection |\n| `[A] <-- [B]` | Dashed reverse arrow | Dashed connection from B to A |\n| `[A] <--> [B]` | Dashed bidirectional arrow | Dashed connection with arrowheads on both ends |\n| `[A] -> \"text\" -> [B]` | Labeled arrow | Double-quoted edge label |\n| `[A] -> 'text' -> [B]` | Labeled arrow | Single-quoted edge label |\n\n### Example DSL\n\n```\n(Start) -> [Enter Credentials] -> {Valid?}\n{Valid?} -> \"yes\" -> [Dashboard] -> (End)\n{Valid?} -> 'no' -> [Show Error] -> [Enter Credentials]\n[API] -> \"GET /users?name=\\\"pp\\\" \\\\ cache\" -> [Client]\n[Client] --> [Webhook]\n[Worker] <-- [Queue]\n[Service A] <--> [Service B]\n[Reviewer] <- [Approved]\n[Client] <-> [API]\n```\n\n### Edge label escaping\n\nEdge labels must use the fully specified form `[A] -> \"label\" -> [B]` (or single quotes instead of double quotes).\nMixed forms like `[A] --> \"x\" -> [B]` are rejected because they are ambiguous.\n\nShell escaping tips:\n\n```bash\n# easiest: wrap the whole DSL in single quotes, use double-quoted labels inside\nexcalidraw-cli create --inline '[API] -> \"GET /users?name=\\\"pp\\\"\" -> [Client]' -o api.excalidraw\n\n# if the label itself needs apostrophes, flip it\nexcalidraw-cli create --inline \"[Decision] -> 'team\\'s call' -> [Next]\" -o decision.excalidraw\n```\n\n### Node Styling\n\nAdd shape-level styling directly to nodes with inline `@key:value` attributes:\n\n```excalidraw\n(Start) -> [Enter Credentials @fillStyle:hachure @backgroundColor:#a5d8ff] -> {Valid?}\n{Valid?} -> \"no\" -> [Show Error @backgroundColor:#ffc9c9 @strokeStyle:dashed] -> [Enter Credentials]\n```\n\nFor repeated or shared nodes, define defaults with an `@node` block:\n\n```excalidraw\n@node [Enter Credentials]\n fillStyle: solid\n backgroundColor: #a5d8ff\n\n(Start) -> [Enter Credentials @fillStyle:hachure] -> {Valid?}\n```\n\nSupported node style keys:\n\n- `fillStyle`: `solid`, `hachure`, `cross-hatch`\n- `backgroundColor`\n- `strokeColor`\n- `strokeWidth`\n- `strokeStyle`: `solid`, `dashed`, `dotted`\n- `roughness`\n- `opacity`\n\nPrecedence rules:\n\n- `@node` blocks provide defaults for matching nodes\n- inline node attributes override block values\n- repeated references to the same node merge explicit style properties with later values winning per property\n\n### Directives\n\n```\n@direction LR # Left to Right (default: TB)\n@spacing 60 # Node spacing in pixels\n```\n\nUse `#` for comments outside node definitions and quoted labels.\n\nImages must be local files; relative paths resolve from the working directory.\nUse `![path]` for an image node. For positioning, decorations, stickers, and\nscatter directives, see the [man page](man/excalidraw-cli.1).\n\n## CLI Reference\n\n| Command | Purpose |\n|---------|---------|\n| `create [input]` | Generate an editable `.excalidraw` file. Accepts a file, `--inline`, or `--stdin`. |\n| `convert --format png\\|svg` | Export an existing `.excalidraw` file. |\n| `parse ` | Validate input and print its graph without generating a file. |\n\nUse `--help` with any command for its options, or `man excalidraw-cli` for the\nfull reference. `create -o -` writes to stdout.\n\nBoth `create` and `parse` detect `.json`, `.dot`, and `.gv` files. Other files\nand inline/stdin input default to DSL; use `--format json` or `--format dot`\nto override.\n\n## JSON API\n\nFor programmatic flowchart creation:\n\n```json\n{\n \"nodes\": [\n { \"id\": \"start\", \"type\": \"ellipse\", \"label\": \"Start\" },\n { \"id\": \"process\", \"type\": \"rectangle\", \"label\": \"Process\" },\n { \"id\": \"end\", \"type\": \"ellipse\", \"label\": \"End\" }\n ],\n \"edges\": [\n { \"from\": \"start\", \"to\": \"process\" },\n { \"from\": \"process\", \"to\": \"end\" }\n ],\n \"options\": {\n \"direction\": \"TB\",\n \"nodeSpacing\": 50\n }\n}\n```\n\n```bash\nexcalidraw-cli create flowchart.json -o diagram.excalidraw\n```\n\n## Programmatic Usage\n\n```typescript\nimport {\n createFlowchartFromDSL,\n createFlowchartFromJSON,\n} from '@swiftlysingh/excalidraw-cli';\n\n// From DSL\nconst dsl = '(Start) -> [Process] -> (End)';\nconst json = await createFlowchartFromDSL(dsl);\n\n// From JSON input\nconst json2 = await createFlowchartFromJSON({\n nodes: [\n { id: 'a', type: 'rectangle', label: 'Hello' },\n { id: 'b', type: 'rectangle', label: 'World' }\n ],\n edges: [{ from: 'a', to: 'b' }]\n});\n```\n\n### Export API\n\n```typescript\nimport { convertToSVG, convertToPNG } from '@swiftlysingh/excalidraw-cli';\nimport { readFileSync, writeFileSync } from 'fs';\n\n// Load an existing .excalidraw file\nconst file = JSON.parse(readFileSync('diagram.excalidraw', 'utf-8'));\n\n// Export to SVG\nconst svg = await convertToSVG(file, { padding: 20 });\nwriteFileSync('diagram.svg', svg);\n\n// Export to PNG with 2x scale and dark mode\nconst png = await convertToPNG(file, {\n scale: 2,\n dark: true,\n});\nwriteFileSync('diagram.png', png);\n```\n\nWhen no background is supplied, exports use `file.appState.viewBackgroundColor`\nand fall back to `#ffffff`. PNG scale values are clamped to `0.1` through `10`.\n\n## Examples\n\nHere are some flowcharts created with excalidraw-cli:\n\n### Simple Flow\n\n\n### iOS App Architecture\n\n\n### LeetCode Problem Solving Flow\n\n\nGenerated `.excalidraw` files open in [Excalidraw](https://excalidraw.com) and\ncan be imported into Obsidian's Excalidraw plugin.\n\n## Releasing\n\nRun the **Release** workflow from `main` to create the next minor version from the\nlatest stable tag. It tests the updated package, creates a release commit and tag,\nthen publishes npm, GitHub, and Homebrew. The version commit stays on the tag;\nprotected `main` is unchanged.\n\nTo resume a partially published release, choose **retry** and enter its existing\ntag. A retry does not bump the version.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}