drawio

$27

If no format is mentioned, just write the .drawio file and open it in draw.io. The user can always ask to export later.

Supported export formats

Format

Embed XML

Notes

png

Yes (-e)

Viewable everywhere, editable in draw.io

svg

Yes (-e)

Scalable, editable in draw.io

pdf

Yes (-e)

Printable, editable in draw.io

jpg

No

Lossy, no embedded XML support

PNG, SVG, and PDF all support --embed-diagram — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.

draw.io CLI

The draw.io desktop app includes a command-line interface for exporting.

Locating the CLI

First, detect the environment, then locate the CLI accordingly:

#### WSL2 (Windows Subsystem for Linux)

WSL2 is detected when /proc/version contains microsoft or WSL:

grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2"

On WSL2, use the Windows draw.io Desktop executable via /mnt/c/...:

DRAWIO_CMD=`/mnt/c/Program Files/draw.io/draw.io.exe`

The backtick quoting is required to handle the space in Program Files in bash.

If draw.io is installed in a non-default location, check common alternatives:

# Default install path

`/mnt/c/Program Files/draw.io/draw.io.exe`

# Per-user install (if the above does not exist)

`/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe`

#### macOS

/Applications/draw.io.app/Contents/MacOS/draw.io

#### Linux (native)

drawio   # typically on PATH via snap/apt/flatpak

#### Windows (native, non-WSL2)

"C:\Program Files\draw.io\draw.io.exe"

Use which drawio (or where draw.io on Windows) to check if it's on PATH before falling back to the platform-specific path.

Export command

drawio -x -f <format> -e -b 10 -o <output> <input.drawio>

WSL2 example:

`/mnt/c/Program Files/draw.io/draw.io.exe` -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio

Key flags:

• -x / --export: export mode

• -f / --format: output format (png, svg, pdf, jpg)

• -e / --embed-diagram: embed diagram XML in the output (PNG, SVG, PDF only)

• -o / --output: output file path

• -b / --border: border width around diagram (default: 0)

• -t / --transparent: transparent background (PNG only)

• -s / --scale: scale the diagram size

• --width / --height: fit into specified dimensions (preserves aspect ratio)

• -a / --all-pages: export all pages (PDF only)

• -p / --page-index: select a specific page (1-based)

Opening the result

Environment

Command

macOS

open <file>

Linux (native)

xdg-open <file>

WSL2

cmd.exe /c start "" "$(wslpath -w <file>)"

Windows

start <file>

WSL2 notes:

• wslpath -w <file> converts a WSL2 path (e.g. /home/user/diagram.drawio) to a Windows path (e.g. C:\Users\...). This is required because cmd.exe cannot resolve /mnt/c/... style paths.

• The empty string "" after start is required to prevent start from interpreting the filename as a window title.

WSL2 example:

cmd.exe /c start "" "$(wslpath -w diagram.drawio)"

File naming

• Use a descriptive filename based on the diagram content (e.g., login-flow, database-schema)

• Use lowercase with hyphens for multi-word names

• For export, use double extensions: name.drawio.png, name.drawio.svg, name.drawio.pdf — this signals the file contains embedded diagram XML

• After a successful export, delete the intermediate .drawio file — the exported file contains the full diagram

XML format

A .drawio file is native mxGraphModel XML. Always generate XML directly — Mermaid and CSV formats require server-side conversion and cannot be saved as native files.

Basic structure

Every diagram must have this structure:

<mxGraphModel adaptiveColors="auto">

  <root>

    <mxCell id="0"/>

    <mxCell id="1" parent="0"/>

    <!-- Diagram cells go here with parent="1" -->

  </root>

</mxGraphModel>

• Cell id="0" is the root layer

• Cell id="1" is the default parent layer

• All diagram elements use parent="1" unless using multiple layers

XML reference

For the complete draw.io XML reference including common styles, edge routing, containers, layers, tags, metadata, dark mode colors, and XML well-formedness rules, fetch and follow the instructions at:

https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md

Troubleshooting

Problem

Cause

Solution

draw.io CLI not found

Desktop app not installed or not on PATH

Keep the .drawio file and tell the user to install the draw.io desktop app, or open the file manually

Export produces empty/corrupt file

Invalid XML (e.g. double hyphens in comments, unescaped special characters)

Validate XML well-formedness before writing; see the XML well-formedness section below

Diagram opens but looks blank

Missing root cells id="0" and id="1"

Ensure the basic mxGraphModel structure is complete

Edges not rendering

Edge mxCell is self-closing (no child mxGeometry element)

Every edge must have <mxGeometry relative="1" as="geometry" /> as a child element

File won't open after export

Incorrect file path or missing file association

Print the absolute file path so the user can open it manually

CRITICAL: XML well-formedness

• **NEVER include ANY XML comments (<!-- -->) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.

• Escape special characters in attribute values: &, <, >, "

• Always use unique id values for each mxCell