Command line
umlimator.py turns a model into files: an interactive page, still pictures, a PDF, an animated story. It also checks models, imports diagrams you already have, and compares versions.
Requirements. Python 3.9+ (standard library only); Google Chrome or Chromium for stills, check, record and pdf; Node 18+ for diff, drift, trace and mcp. Get it by cloning the repository at a release tag:
git clone --depth 1 --branch v0.44.0 https://github.com/zintaen/umlimator.gitA command that fails leaves its previous output as it was.
Pages and pictures
python3 umlimator.py render examples/umlimator-atlas.json --out page.html # the interactive page, then its layout check
python3 umlimator.py stills page.html --out stills/ # every view as SVG and PNG
python3 umlimator.py stills page.html --out stills/ --views overview,api --scale 1.5 --theme light
python3 umlimator.py render examples/sales-classes.json --out classes.html # a class diagram's page; stills, check and pdf take it toorenderwrites the standalone page, then runs the layout check on it.stillsskips a view whose inputs have not changed since its last export (--allexports every view), and exits 1, saying why, when a view can't be exported.- In
stills,checkandpdf,--viewstakes view ids, and a trailing*is a prefix; a name that matches no view is an error.
Checks
python3 umlimator.py check page.html --views 'pic-*' # the layout check on chosen views
python3 umlimator.py check page.html --expand # also each view with each stacked card unfoldedcheck reports crossings, shared lines, detours, labels on lines and text that overflows its card, and each rule the model breaks. It exits 1 when the model breaks a rule (one --ignore does not leave out) or when the check itself fails; crossings, detours and the other layout problems are reported with exit 0. Run it in CI to fail a build on a broken rule. For a model with cloud diagrams, it also compares the model's iconPacks with the release's (Icons and icon packs).
PDF
python3 umlimator.py pdf page.html --out map.pdf # every view in one PDF: a cover, each view with its tables, the rulespdf prints the map through Chrome's own print, as a document to hand in for a review (the Umlimator Atlas's, as CI builds it). A cover has the title, the date, the model's file, a summary line and the contents with each view's page. Each view starts a page of its own, under its path ("Umlimator › The module's packages, in build order"): its picture in vectors, as large as the page allows, the legend of what it draws, and tables of its cards, lines and boxes, which go on over the next pages with their header row when they are long. The rules follow as a table, when the model has any, each holding or broken in the views printed. Every page ends in the title and "page N of M". It takes --views and --theme, as stills does, and --paper a4|letter (A4 is the default; both across).
Record
python3 umlimator.py record page.html --story pull-request --out pr.png # the atlas's story as an animated PNG, its tours ridingrecord writes an animated PNG, which browsers and GitHub show as it is. It takes --size, --scale and --theme. For a GIF or an MP4 (for chat or slides), convert it with ffmpeg:
ffmpeg -f apng -i pr.png -vf "split[a][b];[a]palettegen[p];[b][p]paletteuse" pr.gif
ffmpeg -f apng -i pr.png -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -pix_fmt yuv420p pr.mp4Change over time
python3 umlimator.py diff before.json after.json --out diff.html --stills diff/ # what changed, marked and in words
python3 umlimator.py diff --base origin/main --out diff/ # every model changed since a ref, and a summary.md
python3 umlimator.py drift model.json traffic.json --out drift.html # drawn vs. seen (a Jaeger or Tempo dependency list)
python3 umlimator.py timelapse model.json --out history.html # the latest 30 versions in git history (--limit N), on a sliderGitHub Action and diff has the details, and the Action that posts a diff on pull requests.
Traces
python3 umlimator.py trace model.json trace.json --view checkout --match match.json --out model.json # an OTLP trace kept as a numbered view; match.json (your own) maps services to cards
python3 umlimator.py trace model.json trace.json --view checkout --match match.json --diagram uml.sequence --out traced.json # ... as a UML sequence diagram, in a version-2 modelImport and export
python3 umlimator.py import workspace.dsl --out model.json # a diagram you have already, as a model
python3 umlimator.py import order.bpmn --out order.json # BPMN XML, as a BPMN diagram (needs Node and bpmn-moddle, installed by you)
python3 umlimator.py export order.json --out order.bpmn # a model's BPMN as BPMN XML, laid outImport and export lists every format.
Icons
python3 umlimator.py pack list # the cloud icon packs: each one's label, and whether it is fetched and accepted
python3 umlimator.py pack fetch gcp # Google Cloud's icons: their terms first, then your yes
python3 umlimator.py pin-icons # records each new logo's sha256See Icons and icon packs.
An AI assistant
python3 umlimator.py mcp model.json # an MCP server over stdio, for an AI assistantSee MCP server.