14. The `plota` command line

plota renders, splits and checks diagrams without a browser: the same reader, layout and exporter as the editor, so a file rendered in CI looks like the one you export by hand. It reads Mermaid (every type in chapter 13), Plota JSON and the diagram language.

Getting it#

The plota CLI will be available on npm soon. The rest of this chapter describes how it works, so you can plan for it.

It runs on Node 22 or newer.
PNG output needs the sharp image library to be installable on the machine; SVG, JSON and Mermaid output need nothing extra.

plota --version prints the version; plota --help is the full reference.

Commands#

plota render flow.mmd -o flow.svg              # format from -o's extension, or -f
plota render flow.mmd -o flow.png
cat flow.mmd | plota render - -f svg > flow.svg  # "-" reads stdin
plota render docs/diagrams --out-dir out -f png  # batch: a directory …
plota render 'docs/**/*.mmd' --out-dir out       # … or a glob
plota render flow.mmd --watch                    # live preview in the browser
plota views big.mmd --out-dir pages -f png       # overview + one page per section
plota render big.mmd --views auto --out-dir pages
plota critique flow.mmd                          # readability score and problems
plota bootstrap . -o arch.mmd                    # draft an architecture diagram for a folder

Command	What it does
`render <input…>`	Draws the input as `svg`, `png`, `json` (editable in the editor) or `mermaid`
`views <input>`	Splits a sectioned flowchart into an overview page and one page per section, written as `01-<page>.svg`, `02-…`
`critique <input…>`	Reports the readability score and the problems found; can fail a build (below)
`bootstrap [dir]`	Drafts an architecture Mermaid diagram from a project folder

An input is a file, - for stdin, a directory (every .mmd, .mermaid, .json, .plota and .dsl file in it) or a glob. Several inputs, a directory or a glob make a batch: one ok in -> out line per file.

Options#

Option	Meaning
`-o, --output <file>`	Output file (default: stdout)
`--out-dir <dir>`	Output directory for a batch, `views`, or a multi-page render
`-f, --format <fmt>`	`svg`, `png`, `json` or `mermaid` (default: from `-o`, else `svg`)
`-d, --direction <dir>`	`TD`, `LR`, `RL` or `BT`
`--views <mode>`	`single`, `overview-detail` or `auto` (render only)
`--compact-legend[=auto]`	Move long node text into a legend table
`--embed-fonts`	Embed the fonts in an SVG (a PNG always has them)
`--no-watermark`	Leave out the "Made with Plota" mark
`--watch`, `--port <n>`	Live-reload preview; a syntax error keeps the last good drawing on screen
`--json`	Machine-readable output for `critique` and `views`
`--max-score <n>`, `--fail-on <list>`	Gates for `critique` (below)

Unknown options and bad values are rejected with a "did you mean" hint, never ignored.

Exit codes#

Code	Meaning
`0`	Success
`1`	The work failed: unreadable or unparseable input, a failed write, a failed `critique` gate, or any file in a batch failed
`2`	Usage error: unknown command or option, or a bad value

Every failure prints one plota: … line to stderr.

Checking diagrams in CI#

critique gives each diagram a readability score — lower is better — and names what costs it points: crossing connectors, connectors running through shapes, overlaps, wasted page space and so on. Add a gate and it exits 1 when a drawing is worse than you allow:

plota critique 'docs/**/*.mmd' --max-score 1.5 --fail-on D7,crossings,feasibility

--max-score <n> fails a file whose score is above n.
--fail-on fails a file that has any of the named problems: a defect code (D7_page_empty, or just D7), crossings, or feasibility (overlaps, lost connectors, routing failures).

With several files each one is reported and the exit code is 1 if any fails. critique --json gives a stable object per file (score, the problems with their counts, and passed / failures); fields are only ever added.

In a CI job, once plota is available there:

- run: plota critique 'docs/**/*.mmd' --max-score 1.5
- run: plota render docs --out-dir build/diagrams -f png

The watermark#

SVG, PNG and PDF exports carry a small "Made with Plota" mark in the bottom right corner. --no-watermark leaves it out; JSON and Mermaid output never have it.

14. The plota command line