The command line

usage: drawspec [-h] [--version]
                {render,validate,theme,schema,kinds,example,mcp} ...

Nothing is printed to stdout but the thing that was asked for — the SVG, the schema, or a one-line confirmation — so drawspec render doc.json > doc.svg is safe. Refusals go to stderr in full: the message names the remedy as well as the fault, and a build script that truncates it to a summary line is a build script whose author ends up guessing.

Exit codes

The split is worth stating: 2 is about the invocation, 1 is about the content. A misspelt flag or an unknown profile is 2 — nothing was read, so nothing can be said about it. A document that cannot be read, cannot be parsed, or cannot be fitted is 1, and a refusal is an outcome, not a crash.

Code	Meaning
0	It worked.
1	The document, the theme or the fit was refused.
2	The command line itself was wrong.

Global options

Legal before the command name.

Argument	What it does
--version	Show program’s version number and exit.

Commands

drawspec render

Read a document, draw it, and write the SVG to stdout or to a file. With –format png, or an -o ending in .png, write a PNG instead (needs pip install ‘drawspec[png]’). With –format text, or an -o ending in .txt, write the diagram as plain text, refused when it is wider than –width.

usage: drawspec render [-h] [-o OUT] [--theme THEME] [--width WIDTH]
                       [--height HEIGHT] [--profile {inline,standalone}]
                       [--format {svg,png,text}] [--charset {unicode,ascii}]
                       [--scale SCALE] [--background {light,dark,transparent}]
                       document

Argument	What it does
document	The document to render.
-o, --out	Write here instead of stdout.
--theme	A bundled theme name or a theme file.
--width	Override the document’s width; with –format text, the most terminal cells a line may take (default 80, or 100 for lanes and sequence).
--height	Override the document’s height.
--profile	The embedding profile. One of inline, standalone. Default inline.
--format	What to write: svg; png, a raster image of the standalone drawing; or text, the diagram as plain text for a code block or a terminal (files, tree, sequence, gantt, timeline, board, stack, rag, meter, flow, states, lanes). Default: from the -o extension, else svg. One of svg, png, text.
--charset	For text: box-drawing characters, or ASCII only (default unicode). One of unicode, ascii.
--scale	For png: pixels per SVG unit, at most 8 (default 2).
--background	For png: theme ink on white, light ink on near-black, or no page (default light). One of light, dark, transparent.

drawspec validate

Parse and check a document, drawing nothing. Every violation is printed with the JSON pointer of the place it was written.

usage: drawspec validate [-h] [--theme THEME] document

Argument	What it does
document	The document to validate.
--theme	A bundled theme name or a theme file.

drawspec theme

Tools for the files that decide appearance.

usage: drawspec theme [-h] {check,from} ...

drawspec theme check

Load a theme and run its invariants, the greyscale role pairing included.

usage: drawspec theme check [-h] theme

Argument	What it does
theme	A bundled theme name or a theme file.

drawspec theme from

Read CSS custom properties (a .css file) or W3C design tokens (a .json or .tokens file) and write the theme they map onto, as TOML. Fonts, the accent and muted colours, a corner radius and a stroke weight are taken; every token left out is reported on stderr with the reason. A colour that would not read at 3:1 on both a white and a near-black page is darkened or lightened until it does. Local files only: no URL is fetched.

usage: drawspec theme from [-h] [-o OUT] [--name NAME] [--strict]
                           brand [brand ...]

Argument	What it does
brand	A .css or design-tokens file; a later file wins a tie.
-o, --out	Write here instead of stdout.
--name	The theme’s name; the first file’s name by default.
--strict	Refuse a colour that would need adjusting, instead of adjusting it.

drawspec schema

Write the published document JSON Schema, for editor completion.

usage: drawspec schema [-h] [--out OUT]

Argument	What it does
--out	Write here instead of stdout.

drawspec kinds

One line per kind: the claim that kind of diagram makes.

usage: drawspec kinds [-h]

drawspec example

Write the smallest document of that kind that renders, to stdout. Pipe it straight back in: drawspec example flow

drawspec validate -

usage: drawspec example [-h]
                        {flow,tree,cycle,stack,timeline,columns,matrix,pyramid,rings,funnel,chart,quadrant,scatter,curve,files,states,sequence,lanes,entities,gantt,board,fishbone,venn,journey,treemap,sankey,numberline,barmodel,waterfall,pie,mindmap,argument,familytree,meter,rag,clock}

Argument	What it does
kind	Which kind to write. One of flow, tree, cycle, stack, timeline, columns, matrix, pyramid, rings, funnel, chart, quadrant, scatter, curve, files, states, sequence, lanes, entities, gantt, board, fishbone, venn, journey, treemap, sankey, numberline, barmodel, waterfall, pie, mindmap, argument, familytree, meter, rag, clock.

drawspec mcp

The MCP server; needs the extra: pip install ‘drawspec[mcp]’.

usage: drawspec mcp [-h]

Embedding profiles

render --profile takes inline, standalone.

• inline — for pasting into a Markdown or HTML page. Strokes are currentColor, so the drawing inherits the page’s ink and follows it into dark mode; there is no <style> block to leak, and every id is scoped so two diagrams on one page cannot collide.
• standalone — for a linked .svg, a PDF conversion, or anywhere there is nothing to inherit from. currentColor is resolved to the theme’s [canvas] ink, because a converter’s own default is not a design decision.

Themes

--theme takes a bundled theme name or the path of a TOML file. See the theme reference for every key a theme may set, and the guide for how to write one.