Back to Docs
CLI
DrawIt CLI
The DrawIt command-line tool for generating, inspecting, exporting, and automating diagrams. AI-first workflows and full scripting support.
Installation
npm install -g @chamuka-labs/drawit-cli
Verify the install:
drawit --version
Quick Start
Generate a diagram from a prompt and export it as PNG:
# Generate from prompt drawit gen "microservices architecture with API gateway" --out arch.drawit # Export to PNG drawit export arch.drawit --format png --out arch.png # Open interactive inspector drawit inspect arch.drawit
Create a diagram from a Mermaid file:
drawit new my.drawit --from diagram.mmd
Global Flags
These flags work with every command.
| Flag | Description | Default |
|---|---|---|
| --json | Output machine-readable JSON. Disables color and spinners. | false |
| --quiet | Suppress all non-essential output. Only errors and the final result are printed. | false |
Creation & AI
drawit new <file>
Create a new empty diagram file.
drawit new my.drawit drawit new flow.drawit --template flowchart drawit new arch.drawit --from diagram.mmd # Import from Mermaid
| Flag | Description | Default |
|---|---|---|
| --template <name> | Template hint: flowchart | arch | mindmap | erd | timeline | orgchart | wireframe | infographic | network | sequence | — |
| --from <file> | Import from a Mermaid (.mmd) source file instead of creating empty. | — |
drawit gen <prompt>
AI-generate a diagram from a natural-language prompt.
drawit gen "user authentication flow with OAuth" drawit gen "AWS cloud architecture" --template arch --out infra.drawit drawit gen "system design" --model claude-3-5-sonnet drawit gen "flowchart" --model ollama:llama3.2 # Local, no key drawit gen "diagram" --model pollinations # Free, no key drawit gen "arch" --race "gemini-2.5-flash,gpt-4o" # Race models
| Flag | Description | Default |
|---|---|---|
| --template <name> | Template hint for generation style. | — |
| --model <model> | AI model: gemini-2.5-flash | gpt-4o | claude-3-5-sonnet | pollinations | ollama[:<model>] | pollinations |
| --out <file> | Output file path. Default: prints JSON to stdout. | — |
| --hybrid | Semantic + layout hybrid generation mode. | — |
| --race <m1,m2> | Race multiple models, use the fastest result. | — |
| --via-mcp | Route generation through the local MCP server. | — |
| --json | Stream elements as NDJSON. | — |
drawit improve <file>
AI-improve an existing diagram based on instructions.
drawit improve arch.drawit --prompt "make it cleaner and add error handling paths" drawit improve flow.drawit --model gpt-4o
| Flag | Description | Default |
|---|---|---|
| --prompt <text> | Improvement instructions. | — |
| --model <model> | AI model override. | — |
drawit ask <file> <question>
Ask AI a question about a diagram.
drawit ask arch.drawit "What are the single points of failure?" drawit ask flow.drawit "How many decision nodes are there?" --json
Import & Export
drawit import <input>
Import an SVG, Figma JSON, or Mermaid file into a .drawit diagram.
drawit import diagram.svg drawit import figma-export.json --format figma drawit import flowchart.mmd --out my.drawit # Figma with personal access token drawit import frame.json --format figma --token $FIGMA_TOKEN --page 0
| Flag | Description | Default |
|---|---|---|
| --format <fmt> | Source format: svg | figma | mermaid. Auto-detected from extension if omitted. | — |
| --out <path> | Output .drawit file path. | — |
| --token <tok> | Figma personal access token (or set FIGMA_TOKEN env var). | — |
| --page <n> | Figma page index to import. | 0 |
drawit export <file>
Export a diagram to PNG, SVG, JSON, Mermaid, or DOT.
drawit export arch.drawit --format png drawit export arch.drawit --format svg --out arch.svg drawit export arch.drawit --format mermaid drawit export arch.drawit --format dot | dot -Tpng -o arch.png drawit export arch.drawit --format png --scale 3 --padding 60
| Flag | Description | Default |
|---|---|---|
| --format <fmt> | Output format: png | svg | json | mermaid | dot | drawit | png |
| --out <path> | Output file path. Default: derived from input filename. | — |
| --scale <n> | PNG scale factor. | 2.0 |
| --padding <px> | PNG padding in pixels. | 40 |
drawit convert <input> <output>
Convert between diagram formats by file extension.
drawit convert diagram.mmd output.drawit drawit convert arch.drawit arch.svg drawit convert flow.drawit flow.png
Inspection & Analysis
drawit validate <file>
Validate a diagram file for integrity errors.
drawit validate arch.drawit drawit validate arch.drawit --strict # Also verify round-trip integrity drawit validate arch.drawit --json
drawit info <file>
Show diagram statistics: element count, page count, bounds.
drawit info arch.drawit drawit info arch.drawit --json
drawit diff <file-a> <file-b>
Semantic diff between two diagram files.
drawit diff arch-v1.drawit arch-v2.drawit drawit diff old.drawit new.drawit --json
drawit inspect <file>
Launch an interactive TUI element browser.
drawit inspect arch.drawit
Transformation
drawit layout <file>
Apply an automatic layout algorithm to arrange diagram elements.
drawit layout arch.drawit drawit layout arch.drawit --algo force --direction lr drawit layout arch.drawit --algo radial --out arranged.drawit
| Flag | Description | Default |
|---|---|---|
| --algo <name> | Layout algorithm: hierarchical | force | tree | radial | hierarchical |
| --direction <dir> | Flow direction: tb | lr | bt | rl | tb |
| --node-gap <px> | Gap between sibling nodes in pixels. | 60 |
| --rank-gap <px> | Gap between hierarchy levels in pixels. | 80 |
| --out <path> | Write to a different file instead of modifying in-place. | — |
Elements
Programmatic element inspection and manipulation.
| drawit elements list <file> | List all elements. Filter with --type node|edge|group. |
| drawit elements find <file> --text <str> | Find elements by label text. |
| drawit elements get <file> --id <id> | Get a single element by ID. |
| drawit elements edit <file> --id <id> --prop label=New | Edit element properties. |
| drawit elements delete <file> --id <id> | Delete one or more elements. |
| drawit elements align <file> --id <id> --how center | Align elements: left|center|right|top|middle|bottom. |
| drawit elements duplicate <file> --id <id> | Duplicate elements with an offset. |
# Edit element label and fill color drawit elements edit arch.drawit --id mm-A --prop label="API Gateway" --prop fill=#3b82f6 # Generate a background image and apply it drawit elements edit arch.drawit --id mm-B --image-prompt "dark server room" # Align multiple elements to center drawit elements align arch.drawit --id mm-A --id mm-B --id mm-C --how center
Pages
Multi-page document management.
| drawit pages list <file> | List all pages in a diagram. |
| drawit pages add <file> --name "Page 2" | Add a new page. |
| drawit pages switch <file> --id <page-id> | Switch the active page. |
| drawit pages rename <file> --id <page-id> --to "New Name" | Rename a page. |
Snapshots
Named save/restore points for a diagram file.
| drawit snapshot create <file> | Create a named snapshot. |
| drawit snapshot create <file> --name "before refactor" | Create a snapshot with a custom name. |
| drawit snapshot list <file> | List all snapshots. |
| drawit snapshot restore <file> --id <snap-id> | Restore to a snapshot. |
| drawit snapshot diff <file> --id <snap-id> | Diff the current state against a snapshot. |
| drawit snapshot delete <file> --id <snap-id> | Delete a snapshot. |
Themes
Apply built-in themes or set individual design tokens.
| drawit theme list | List all built-in themes. |
| drawit theme apply <file> --name dark-tech | Apply a theme. Options: dark-tech | corporate-blue | pastel | mermaid |
| drawit theme apply <file> --name pastel --mode light | Apply with color mode override. |
| drawit theme token <file> --key primary-color --value "#3b82f6" | Set an individual design token. |
Batch Processing
Run operations on multiple files matching a glob pattern. Uses all CPU cores in parallel.
# Export all diagrams in a folder to PNG drawit batch export "designs/*.drawit" --format png --scale 2 # Validate all diagram files recursively drawit batch validate "**/*.drawit" --strict # Apply hierarchical layout to all drawit batch layout "*.drawit" --algo hierarchical # Convert all to SVG drawit batch convert "*.drawit" --to svg
Watch & Serve
drawit watch <file>
Watch a diagram and auto-export on every save.
drawit watch arch.drawit --format png drawit watch arch.drawit --format svg --out arch.svg --diff drawit watch arch.drawit --exec "open $FILE" # Open after each export
| Flag | Description | Default |
|---|---|---|
| --format <fmt> | Export format on change: png | svg | json | mermaid | png |
| --out <path> | Output path. | — |
| --diff | Show element diff on each change. | — |
| --exec <cmd> | Shell command to run after each export ($FILE = output path). | — |
| --debounce <ms> | Debounce delay. | 200 |
drawit serve
Start the local MCP server so AI agents can edit diagrams.
drawit serve # HTTP on port 3847 drawit serve --port 4000 # Custom port drawit serve --stdio # Claude Desktop stdio transport drawit serve --background # Daemonize
AI Images
Generate images via Pollinations — no API key required.
# Generate and download an image drawit image generate "dark tech server room" --out bg.png # Just print the URL drawit image generate "circuit board abstract" --url-only # Custom size and model drawit image generate "gradient blue abstract" --width 1200 --height 800 --model flux-realism # Apply a generated image as an element background drawit image bg arch.drawit --id mm-A --prompt "AWS cloud data center"
| Flag | Description | Default |
|---|---|---|
| --width <px> | Image width. | 800 |
| --height <px> | Image height. | 600 |
| --model <name> | Pollinations model: flux | flux-realism | flux-anime | flux-3d | turbo | flux |
| --out <file> | Download and save to file. | — |
| --url-only | Only print the URL, do not download. | — |
Developer Tools
drawit doctor
Diagnose your DrawIt environment: API keys, MCP server, WASM build health.
drawit doctor drawit doctor --fix # Attempt to auto-fix fixable issues
drawit completions <shell>
Generate shell completions.
drawit completions zsh > ~/.zsh/completions/_drawit drawit completions bash > ~/.bash_completion.d/drawit drawit completions fish > ~/.config/fish/completions/drawit.fish
Piping & Scripting
# Pipe NDJSON elements in
echo '{"kind":"node","label":"Hello"}' | drawit pipe > out.drawit
# Add elements from stdin
cat elements.ndjson | drawit add existing.drawit
# Round-trip integrity test
drawit roundtrip arch.drawitConfiguration
User configuration lives in ~/.drawit/config.toml.
| drawit config list | List all configuration keys and current values. |
| drawit config get defaults.export_scale | Get the value of a key. |
| drawit config set defaults.export_scale 3 | Set a configuration value. |
| drawit config reset | Reset all configuration to factory defaults. |
| drawit config path | Print the path to the configuration file. |
API keys can also be set via environment variables: OPENAI_API_KEY, GEMINI_API_KEY, FIGMA_TOKEN.