Excalidraw CLI

Website: https://excalidraw.com CLI Tool: excalidraw-cli Repository: https://github.com/tommywalkie/excalidraw-cli NPM Package: @tommywalkie/excalidraw-cli

Description

Excalidraw CLI is an experimental tool that converts Excalidraw JSON schemas (*.excalidraw) into PNG images. It enables batch processing of Excalidraw drawings from the command line without needing a browser. Uses node-canvas and Rough.js to mimic Excalidraw's rendering.

Install

npm install -g @tommywalkie/excalidraw-cli

Or run directly with npx:

npx @tommywalkie/excalidraw-cli [INPUT] [OUTPUT]

Alpine/Docker

For Alpine-based Docker images, install required native dependencies:

FROM node:alpine
RUN apk update
RUN apk add --no-cache python g++ build-base cairo-dev jpeg-dev pango-dev \
    musl-dev giflib-dev pixman-dev pangomm-dev libjpeg-turbo-dev freetype-dev

Usage

excalidraw-cli [INPUT] [OUTPUT]

• INPUT: Excalidraw file path or directory path (default: current directory)
• OUTPUT: Output PNG file path or directory path (default: current directory)

Commands

Options

Examples

Convert Single File

# Convert drawing.excalidraw to drawing.png in current directory
excalidraw-cli drawing.excalidraw

# Convert with specific output path
excalidraw-cli drawing.excalidraw ./output/diagram.png

Batch Convert Directory

# Convert all .excalidraw files in drawings/ to PNGs in output/
excalidraw-cli ./drawings ./output

# Convert all files in current directory
excalidraw-cli . ./exported

Docker Usage

# Add to .bashrc or .zshrc for convenient usage
function excalidraw-cli {
  docker run --rm -it -v $PWD:/data excalidraw-cli $@
}

# Then use normally
excalidraw-cli drawings/my-drawing.excalidraw .

Integration with CI/CD

# GitHub Actions example
- name: Convert Excalidraw to PNG
  run: |
    npm install -g @tommywalkie/excalidraw-cli
    excalidraw-cli ./docs/diagrams ./docs/images

Notes

• File format: Input files must be valid Excalidraw JSON (.excalidraw extension)
• Output format: Currently only supports PNG output
• Rendering: Uses Rough.js to mimic Excalidraw's hand-drawn style
• Native dependencies: Requires cairo, pango, and other native libs (auto-installed on most systems via node-canvas)
• Headless: Runs without browser/window context using node-canvas