.nornir/status-badge-guide.md · nordisk/dwarves

status badge — guide

Class: guide · how to USE the dwarves badge verb + the Badge RPC. What it IS: status-badge-design.md.

A status badge is a shields-style SVG pill for a pipeline's latest run. Render it from the CLI (local or against a server) and drop the SVG into a README, a dashboard, or a CI comment.

Fat — badge from the local warehouse

# render the newest `smoke-ci` run's badge to stdout
dwarves badge smoke-ci

# a friendlier label + write straight to a file
dwarves badge smoke-ci --label "smoke ci" -o badge.svg

# disambiguate a pipeline name shared across projects
dwarves badge ci --project nornir

--warehouse <dir> (or $DWARVES_WAREHOUSE, else ~/.dwarves/warehouse) selects the run history read.

Thin — badge from a running server

dwarves --server 127.0.0.1:7900 badge smoke-ci
# or: DWARVES_SERVER=127.0.0.1:7900 dwarves badge smoke-ci

The server runs the same selector + renderer over its warehouse and returns the SVG in a BadgeReply — byte-identical to the fat render (a client --label just re-renders with the reported status).

The exit code is a gate

latest run	stdout	exit
green (`passed`)	passing SVG	`0`
recorded non-green (`failed`/`running`/`skipped`)	that SVG	`1`
no run recorded	grey unknown SVG	`2`

So dwarves badge smoke-ci >/dev/null && echo green doubles as a status check, and a still-cold pipeline renders a valid grey pill instead of erroring.

Colours

passed→green #4c1 · running→amber #dfb317 · skipped→grey #9f9f9f · failed→red #e05d44 · unknown→grey #9f9f9f.

Embed it

The SVG is self-contained (no external fetch), so:

<img src="badge.svg" alt="smoke-ci: passing">

or serve the Badge RPC's svg field straight from a dashboard.