excalirender

CLI tool that converts Excalidraw .excalidraw files to PNG, SVG, and PDF. Runs as a standalone binary compiled with Bun, available as a Docker image or a self-contained native Linux binary.

Get Started

Docker (Linux, Mac, Windows)

Convert an Excalidraw file to PNG:

docker run --rm -v "$(pwd):/data" -w /data jonarc06/excalirender diagram.excalidraw

This creates diagram.png in the current directory.

Native Linux Binary

Install with a single command — no Docker or system dependencies required:

curl -fsSL https://raw.githubusercontent.com/JonRC/excalirender/main/install.sh | sh

Then run:

excalirender diagram.excalidraw

The install script downloads a self-contained binary from GitHub Releases that bundles all libraries. Works on any Linux x64 system. Run the install command again to update to the latest version.

See docs/LINUX-INSTALLATION.md for install options and uninstall instructions.

Usage

excalirender <input> [options]

Options

Flag	Description	Default
-r, --recursive	Convert all .excalidraw files in directory	false
-o, --output <path>	Output file path (.png, .svg, or .pdf); format inferred from extension	<input>.png
-s, --scale <number>	Export scale factor	1
-b, --background <color>	Background color (hex)	From file or #ffffff
-d, --dark	Enable dark mode export	false
--transparent	Transparent background (no fill)	false
--format <type>	Output format when using stdout (-o -): png, svg	png

Examples

excalirender drawing.excalidraw -o output.png      # Custom output path
excalirender drawing.excalidraw -s 2               # 2x resolution
excalirender drawing.excalidraw --dark             # Dark mode
excalirender drawing.excalidraw -b "#f0f0f0"       # Custom background
excalirender drawing.excalidraw --transparent       # Transparent background
excalirender drawing.excalidraw -o out.svg         # SVG output
excalirender drawing.excalidraw -o out.pdf         # PDF output (vector)

Recursive Conversion

Convert all .excalidraw files in a directory and its subdirectories:

excalirender -r ./diagrams              # Output alongside input files
excalirender -r ./diagrams -o ./output  # Output to specific directory
excalirender -r ./diagrams --dark -s 2  # With options

For Docker, prefix commands with docker run --rm -v "$(pwd):/data" -w /data jonarc06/excalirender.

Piping (stdin/stdout)

Use - as input to read from stdin, and -o - to write to stdout. This enables composability with other CLI tools.

# Read from stdin
cat diagram.excalidraw | excalirender - -o output.png
excalirender - -o output.svg < diagram.excalidraw

# Write to stdout
excalirender diagram.excalidraw -o - > output.png
excalirender diagram.excalidraw -o - --format svg > output.svg

# Full pipe (stdin + stdout)
cat diagram.excalidraw | excalirender - -o - > output.png
cat diagram.excalidraw | excalirender - -o - --format svg | other-tool

# Diff with stdin (one file only)
cat old.excalidraw | excalirender diff - new.excalidraw -o diff.png
excalirender diff old.excalidraw - -o - < new.excalidraw > diff.png

When writing to stdout (-o -), use --format to specify the output format (png or svg). Defaults to png. Status messages are redirected to stderr so they don't corrupt the binary output.

Diff Command

Compare two Excalidraw files and generate a visual diff highlighting added, removed, and modified elements:

excalirender diff old.excalidraw new.excalidraw

Flag	Description	Default
-o, --output <path>	Output file (.png, .svg, .pdf, .gif, or .excalidraw)	<old>_vs_<new>.png
-s, --scale <number>	Export scale factor	1
-d, --dark	Enable dark mode export	false
--transparent	Transparent background (no fill)	false
--hide-unchanged	Don't render unchanged elements	false
--no-tags	Don't render status tags	false
--delay <ms>	GIF frame delay in milliseconds	1000
--format <type>	Output format when using stdout (-o -): png, svg	png

Examples:

excalirender diff v1.excalidraw v2.excalidraw                # Creates v1_vs_v2.png
excalirender diff old.excalidraw new.excalidraw -o diff.svg  # SVG output
excalirender diff old.excalidraw new.excalidraw -o diff.pdf  # PDF output
excalirender diff old.excalidraw new.excalidraw --dark       # Dark mode
excalirender diff old.excalidraw new.excalidraw --transparent    # Transparent background
excalirender diff old.excalidraw new.excalidraw --hide-unchanged
excalirender diff old.excalidraw new.excalidraw -o diff.gif          # Animated GIF
excalirender diff old.excalidraw new.excalidraw -o diff.gif --delay 2000  # 2s delay

See docs/DIFF.md for algorithm details and visual output documentation.

Info Command

Display metadata about an .excalidraw file without rendering. Shows element counts by type, canvas dimensions, fonts, color palette, frames, and embedded files.

excalirender info diagram.excalidraw              # Human-readable output
excalirender info diagram.excalidraw --json        # JSON output
cat diagram.excalidraw | excalirender info -       # Read from stdin

Flag	Description	Default
--json	Output metadata as JSON	false

Combine Command

Combine multiple .excalidraw files into a single image, placed side by side or stacked vertically:

excalirender combine a.excalidraw b.excalidraw                    # Side by side (combined.png)
excalirender combine a.excalidraw b.excalidraw -o out.png         # Custom output
excalirender combine a.excalidraw b.excalidraw --layout vertical  # Stacked vertically
excalirender combine a.excalidraw b.excalidraw --labels           # Show filenames below each panel
excalirender combine a.excalidraw b.excalidraw --dark --gap 60    # Dark mode, 60px gap

Flag	Description	Default
-o, --output <path>	Output file path (.png or .pdf)	combined.png
-l, --layout <type>	Layout: horizontal or vertical	horizontal
--gap <pixels>	Gap between panels in pixels	40
--labels	Show filename labels below each panel	false
-s, --scale <number>	Export scale factor	1
-d, --dark	Enable dark mode export	false
--transparent	Transparent background (no fill)	false

See docs/COMBINE.md for implementation details.

Watch Command

Watch .excalidraw file(s) and preview in the browser with live reload. The number of input files determines the mode: 1 file for export, 2 files for diff.

excalirender watch diagram.excalidraw                              # Export mode
excalirender watch old.excalidraw new.excalidraw                   # Diff mode
excalirender watch diagram.excalidraw --dark --scale 2 --port 8080 # With options
excalirender watch old.excalidraw new.excalidraw --hide-unchanged  # Diff options

Flag	Description	Default
-p, --port <number>	HTTP server port	3333
-s, --scale <number>	Export scale factor	1
-d, --dark	Enable dark mode	false
--transparent	Transparent background	false
-b, --background <color>	Background color	From file
-f, --frame <name>	Export specific frame (export mode only)	-
--no-open	Don't auto-open browser	false
--hide-unchanged	Don't render unchanged elements (diff mode)	false
--no-tags	Don't render status tags (diff mode)	-

Editing and saving the .excalidraw file auto-refreshes the browser preview. Parse errors are logged without crashing — the last good render is preserved. Press Ctrl+C to stop the server.

See docs/WATCH.md for architecture and implementation details.

How It Works

The rendering pipeline reads .excalidraw JSON files and draws elements to a server-side canvas using the same libraries Excalidraw uses:

• Rough.js for hand-drawn shapes
• perfect-freehand for pressure-sensitive strokes
• node-canvas for server-side rendering

See docs/CONVERSION.md for the full rendering pipeline documentation.

License

MIT