Always use when user asks to create, generate, draw, or design a diagram, flowchart, architecture diagram, ER diagram, sequence diagram, class diagram, network diagram, mockup, wireframe, or UI sketch, or mentions draw.io, drawio, drawoi, .drawio files, or diagram export to PNG/SVG/PDF.
Generate draw.io diagrams as native .drawio files. Optionally export to PNG, SVG, or PDF with the diagram XML embedded (so the exported file remains editable in draw.io).
.drawio file in the current working directory using the Write toolnpx @drawio/postprocess is available, run it on the .drawio file to optimize edge routing (simplify waypoints, fix edge-vertex collisions, straighten approach angles). Skip silently if not available — do not install it or ask the user about it--embed-diagram, then delete the source .drawio file. If the CLI is not found, keep the .drawio file and tell the user they can install the draw.io desktop app to enable export, or open the file directly.drawio.drawio file otherwise. If the open command fails, print the file path so the user can open it manuallyCheck the user's request for a format preference. Examples:
/drawio create a flowchart → flowchart.drawio/drawio png flowchart for login → login-flow.drawio.png/drawio svg: ER diagram → er-diagram.drawio.svg/drawio pdf architecture overview → architecture-overview.drawio.pdfIf no format is mentioned, just write the .drawio file and open it in draw.io. The user can always ask to export later.
| 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.
The draw.io desktop app includes a command-line interface for exporting.
First, detect the environment, then locate the CLI accordingly:
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`
/Applications/draw.io.app/Contents/MacOS/draw.io
drawio # typically on PATH via snap/apt/flatpak
"C:\Program Files\draw.io\draw.io.exe"
Use which drawio (or where drawio on Windows) to check if it's on PATH before falling back to the platform-specific path.
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)| 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."" 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)"
login-flow, database-schema)name.drawio.png, name.drawio.svg, name.drawio.pdf — this signals the file contains embedded diagram XML.drawio file — the exported file contains the full diagramA .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.
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>
id="0" is the root layerid="1" is the default parent layerparent="1" unless using multiple layersFor 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: