Guides

Check and deliver

Start a deck, measure it in a real browser, photograph it, and turn it into the file you hand over.

What the command line is for

A deck is plain HTML, so you can write one and present it without ever opening a terminal. The command line covers the three moments where that is not enough: starting a deck with its runtime already in place, finding out what is wrong with it before a room does, and producing the artefact you actually deliver · a single file, a PDF, or a set of pictures.

Two audiences need it. Authors reach for init at the start and for export or bundle at the end. Agents and CI jobs live on check and render, which are the only two commands that report what a deck looks like in a form a program can read.

Every command runs from an install, with no clone and no build step. The package declares bin.rikiki, so npx rikiki … works as soon as rikiki-deck is a dependency.

What each command needs

All of them need Node ^20.19.0 || >=22.12.0, the range the package declares under engines. Three of them need a browser, as doesscene plan --measure, and two need a bundler. Both are optional peer dependencies: a deck that only loads the runtime never pays for them.

CommandBeyond NodeInstall line
initnothing else·
init --standalonerolldown ^1.1.1npm i -D rolldown
checkplaywright ^1.60.0npm i -D playwright && npx playwright install chromium
renderplaywright ^1.60.0npm i -D playwright && npx playwright install chromium
bundlerolldown ^1.1.1npm i -D rolldown
exportplaywright ^1.60.0npm i -D playwright && npx playwright install chromium
assemblenothing else·
skillsnothing else·
scenenothing else·
scene plan --measureplaywright ^1.60.0npm i -D playwright && npx playwright install chromium

A missing peer is reported as a sentence with the line that installs it, not as a stack trace.

init · start a deck

Writes a deck you can edit, plus the runtime it loads, next to it.

terminal
npx rikiki init index.html

# a single self-contained file instead of a source deck
npx rikiki init index.html --standalone --title "My talk"

The default form produces index.html and copiesdist, tokens.css, themes andfonts into rikiki/ beside it. Serve that folder overhttp://; ES modules do not load from file://.

With --standalone you get one self-contained file instead, and the command exits non-zero if that file would still fetch anything at runtime. A second init on an existing name refuses to overwrite unless you pass --force.

FlagEffect
--standaloneemit one self-contained file instead of a source deck
--title "…"deck title · defaults to the file name
--theme rikiki|siliceumstarting theme · a source deck copies fonts/ either way, and under --standalone only siliceum has local fonts to inline (rikiki reads its typefaces from Google Fonts)
--with-mermaid, --with-shikialso carry the mermaid runtime or the Shiki highlighter
--no-fontsdrop the fonts rather than inline them
--forceoverwrite a deck that is already there

check · measure the deck

Loads the deck in a real browser, measures it, and reports each finding with a stable code, the slide it belongs to and the number that justifies it.

terminal
npx rikiki check index.html

# the same report as JSON on stdout, for a script or an agent
npx rikiki check index.html --json

# only the slides you are working on: a number, an id, an interval
npx rikiki check index.html --slides 4
npx rikiki check index.html --slides 2,pricing,6-9

The human report goes to stderr, one finding at a time, and ends with a count of errors and warnings.

stderr · an example report
! TEXT_TOO_SMALL · slide 4 (#pricing)
    text renders at 15px · the back row will not read it
    at  deck-split#pricing > deck-md
    try raise the size, or move the detail into deck-notes

index.html · 12 slide(s) · 0 error(s), 1 warning(s)
Design quality · not-run · NOT VERIFIED

Exit codes

CodeMeaning
0the deck was measured and no finding has error severity
1the deck was measured and at least one finding is an error
2the deck could not be read at all · the path is missing or is not a file

The split matters to whoever calls the command: 1 says fix the deck, 2 says fix the call.

The JSON report

With --json, stdout carries the report and nothing else, so it pipes without stripping anything · including when the deck is broken. Notes stay on stderr. The report is versioned by a schema field and carries the deck name, the slide count, the thresholds that were applied, anerror and warning summary, the diagnostics, and anotChecked list naming what nobody looked at.

Review the design and the story

Measurements do not approve a slide. The last line of the report says so: the design stays NOT VERIFIED until someone has looked at every screenshot. --quality-out captures each slide and each reveal state, then writes a request.json with a review template: six criteria per state (hierarchy, typography, readability, composition, visual evidence, theme coherence), each needing a verdict and the visible evidence behind it.

terminal
# capture every slide and reveal state, and write review/request.json
npx rikiki check index.html --quality-out review

# import the filled-in review; fail unless it passes
npx rikiki check index.html --quality-review review.json --require-quality

A review is tied to the deck it describes: edit the deck and the old review is refused as stale. Every failed criterion becomes an error diagnostic (QUALITY_HIERARCHY, QUALITY_TYPOGRAPHY, and so on) and must carry a concrete correction.

FlagEffect
--quality-out <dir>capture every state and prepare the design review
--quality-review <file>import a completed screenshot-based review
--require-qualityadd a QUALITY_REQUIRED error until an imported review is complete
--narrative-out <file>prepare the material for a review of the story, slide by slide
--narrative-review <file>import that structured review

What it looks at

CategoryCodes
the deck never ranRUNTIME_NOT_LOADED, NO_DECK_ROOT, NO_SLIDES, PAGE_ERROR, RESOURCE_MISSING
markup that renders as nothingUNKNOWN_ELEMENT, STRAY_MARKUP, CONTENT_NOT_RENDERED, UNKNOWN_ATTRIBUTE, DUPLICATE_SLIDE_ID
what fits on the slideCONTENT_CLIPPED, SLIDE_DENSE, SLIDE_TOP_HEAVY, TEXT_TOO_SMALL
diagram geometryGRAPH_NODE_OUT_OF_BOUNDS, GRAPH_EDGE_CROSSES_NODE
what a diagram demonstratesthe INT_* findings of a diagram written as an intent · errors, each with its measurement and what was expected
illustrations that look alikeILL_REPEATED_LOOK · a warning about the deck, never an error of a slide · ILL_PAIR_*, ILL_ZOOM_FROM_TARGET, ILL_ACT_DRIFT · what the deck declares between its slides
the talk and what it pulls inTALK_SHORTER_THAN_ANNOUNCED, EXTERNAL_DEPENDENCY

SLIDE_TOP_HEAVY comes from a pixel pass that takes one screenshot per slide and measures where the ink sits.--no-visual skips that pass; the report then says the pixels were not measured. --width and --height set the canvas the deck is measured against.

Illustrations that look alike

A deck can pass every rule slide by slide and still show one picture thirty times with other words. check compares its illustrations with each other, on what they are made of: their structure (the intent, the layouts, the kinds of marks, how the arrows connect), their look (surfaces, tones, a coarse thumbnail of the ink) and their time (clicks, what moves). The distance is 0.5 structure + 0.3 visual + 0.2 time; two drawings closer than 0.15 are ILL_REPEATED_LOOK. The report adds a diversity line and object (distinct structures, intents covered, the largest family, the pairs alike), and--diversity adds every distance and each drawing's nearest neighbour.

A repetition that moves on is no repeat: when the later drawing keeps half of the earlier one's named marks and stands at a later step of the act, adds marks around them, or changes their figures or their state while keeping some as they were, the pair is a motif of the deck. It is listed apart (progressing, « motif(s) that progress ») and never warned about · an incident and its remedy, a chapter that widens. What a deck declares between its slides is checked too, always: ILL_PAIR_TARGETand ILL_PAIR_MARKS (a pair whose remedy is missing, comes first or drops the incident's marks), ILL_ZOOM_FROM_TARGET(a camera that opens from a slide that is not the one before, or that does not draw the mark) and ILL_ACT_DRIFT (one act written two ways).

Illustrations with something to see

A clean, varied drawing can still say nothing: three pale boxes named « Service A », « Service B », « Service C ». Each illustration of the report carries a richness out of 100, on five criteria of 20 points:content (two precise facts of two kinds, when, which and how much, and a deck-source on the slide), demonstration(two devices of relation: a link, a flow, a gate, a scale, a marker, a callout, a state that turns), story (the system running, the break, the proof after it), paint (as many flat fills as roles, up to three) and result (a lasting proof, or the figure in the thing put forward). Each gives its measurement and how to earn the rest. A criterion that does not apply is left out: a still of a share is not judged as a story. More marks, colours or seconds earn nothing.

It is a measure, not a verdict: no score changes and nothing fails. The report adds a Richness line; --richness prints each drawing's points and says three warnings, ILL_GENERIC (no precise fact), ILL_FLAT_PAINT (roles painted alike) andILL_MODEL_REPEAT (the same graphic model a third time in five illustrated slides, unless it is a motif that moves on, as above). Measured on the story decks, they average 95; the galleries written before them, 61; pictures poor on purpose, 20.

Checking only some slides

--slides measures the slides you name and leaves the others alone, which turns a minute-long run on a long deck into a few seconds while you work on one slide. It takes the same list as render: a 1-based number (3), a slide id (pricing), an interval (4-9, -3 for the first three,8- for the last ones) or two ends joined by ..(intro..pricing, each end a number or an id), separated by commas. The report keeps the whole deck's slideCount, lists the positions it measured in slidesChecked, and says innotChecked that the other slides were not looked at. A name that matches no slide stops before anything is measured, names what the deck holds, and exits with 2. Run the whole deck, without the flag, before you ship.

Choosing the rules · for the deck, some slides, some elements

Every rule has a code (TEXT_TOO_SMALL) and a name (text-too-small); --list-checks prints them all, whether the deck keeps each and why. The policy lives inrikiki.config.json, under check: every such file from the deck's folder up applies, outermost first, until one that says"root": true or the repository's root. checks drops or takes back rules in order (-slide-dense, -ill-*,-*,content-*), severity sets one toerror, warning or off,warningsAsErrors fails the run on some warnings,limits moves a threshold (minTextPx,ill.words), and overrides do the same for the slides, the kinds of slide, the tagged slides (data-tags="annexe") or the elements (a CSS selector) they name. On the command line,--checks, --severity rule=level,--warnings-as-errors, --limit name=value and--check-option CODE.option=value speak after the files.

A deck may write an exception on itself, which only silences a warning and only with its reason:data-check-off="slide-dense" data-check-reason="grille contractuelle"on deck-root, a slide or an element.--no-inline-exceptions ignores them all, for a CI. Nothing is lost: what the policy silences is listed under suppressed with what silenced it and why (--show-suppressed in the human report), an exception without a reason, naming no rule or silencing nothing is said, and a page that threw or a file that did not load is reported whatever the policy says. The reference shipped with the package (docs/llms/rikiki-reference.md, « A check policy ») gives every key.

What it does not test

The report is a set of measurements, not a verdict on the deck, and it says so in its own notChecked list:

  • accessibility · no contrast, focus order or screen-reader check is run.
  • revealed steps · only the opening state of each slide is measured.
  • wording, facts and figures · nothing here reads the content.
  • design quality · judged only by a screenshot review you import.
  • other viewports · the deck is measured at its own canvas size.
  • text inside a diagram · an SVG scales by its viewBox, which is not measured.

render · one picture per slide

Photographs the deck so that something without eyes on the screen, a review thread or an agent, can look at it.

terminal
npx rikiki render index.html

# a chosen few, each revealed state, into a directory you name
npx rikiki render index.html --slides 2,pricing --steps --out shots/

The pictures land in index.shots/ unless --outnames another directory. Beside them sit a gallery page,index.html, that opens offline from a file manager, and amanifest.json that ties every picture back to the slide it came from: its index, its id, its tag, its title and its file name. That manifest is what turns "the third picture" into an element you can edit.

FlagEffect
--out dirwhere the pictures go · defaults to the deck name plus .shots
--slides a,bwhich slides · 1-based numbers, slide ids, intervals (4-9, -3, 8-) or two ends (intro..pricing), in deck order · an unknown name is an error · rikiki check takes the same list
--stepsone picture per revealed state · without it a stepped slide is caught in its opening state
--width, --heightcanvas size in pixels

bundle · one file to send

Folds an existing deck, its theme, its runtime and its images into a single HTML file with no external reference.

terminal
npx rikiki bundle index.html

# an explicit name, or - to write the file to stdout
npx rikiki bundle index.html talk.html

Without a second argument the file lands next to the deck asindex.bundle.html; - writes it to stdout instead. The bundle is curated to the components the deck uses and to the icons it draws, and the HTML and CSS stay readable so the result is still editable. If anything in the produced file would still be fetched at runtime, the command says what and exits non-zero · a bundle that fetches is a broken deliverable, not a warning.

FlagEffect
--with-mermaid, --with-shikiinline the mermaid runtime or the Shiki highlighter · needed when the deck uses them
--allcarry every component instead of the ones the deck uses
--include a,bforce-include components that only appear from JS
--no-fontsdrop the fonts and fall back to system ones
--minify-css, --minify-htmltrade readability for size
--no-minify-jskeep the framework JS readable

export · a PDF, one page per slide

Prints the deck for the people who asked for the slides afterwards.

terminal
npx rikiki export index.html

# choose the file name
npx rikiki export index.html --output talk.pdf

The file lands as index.pdf unless --output (or-o) names another one. Page geometry and page breaks come from the deck's own print stylesheet, backgrounds are printed, and the PDF is tagged with one outline entry per slide so a reader can jump around. Anything the deck could not load is listed before the file is announced, because a page that printed without an image is worth saying out loud.

assemble · one deck from many files

Joins ordered partials into the single deck file the rest of the commands expect.

terminal
npx rikiki assemble deck.config.js

The config lists a title, a theme href, a runtime href and the ordered parts; .html parts are inlined as they are and .mdparts split into slides. The output is a normal deck, socheck, render, bundle andexport all take it. A second argument names the output file, and- sends it to stdout. SeeMulti-file decks for the manifest and the partial formats.

skills · the agent skills

Copies the skills shipped with the package into a project, so a coding agent discovers them on its own.

terminal
npx rikiki skills

The installed skills are rikiki-deck,rikiki-theme, rikiki-debug,rikiki-illustrate and rikiki-scenes. They land in.claude/skills/ unless --dir names another location, an existing skill is left alone unless you pass--force, and the command reports what it wrote.

scene · from a brief to a slide

Turns what a slide must prove into the animated scenes that can show it. You write a brief, a JSON file that names the claim, the relation between the items (parallel, sequence,compare-size, before-after…), the figures and their source. The shape follows from the relation, never the other way round.

brief.json
{
  "schema": "rikiki.scene-brief/1",
  "claim": "The cache cuts the build by two thirds",
  "relation": "compare-size",
  "items": [
    { "label": "No cache", "value": 42 },
    { "label": "Shared cache", "value": 14 }
  ],
  "unit": "min",
  "focus": "Shared cache",
  "source": { "text": "Invented figures", "nature": "illustration" }
}
terminal
# the shapes that can say the brief, written and sized
npx rikiki scene plan brief.json

# draw each one in Chromium, keep the plan, the fragments and a picture of each
npx rikiki scene plan brief.json --measure --out plan/

# the slide of the candidate you chose
npx rikiki scene compile brief.json --candidate bars --out slide.html

# how many characters each field of a shape holds, at a width
npx rikiki scene budgets cards --width 752

rikiki scene plan validates the brief, then lists each candidate with its shape, whether it fits, the modules it loads and what the scene lint and the measured character table say about it, followed by the shapes it left out and why. Nothing here calls a model: the same brief always gives the same plan, and choosing a candidate stays with you. With --measure, each candidate is also drawn in Chromium in the theme's fonts (--theme rikiki|siliceum), its height and the problems the scenes report once drawn are added under measured, a picture is taken, and a candidate with an error found that way no longer fits. --out writes candidates.json, one<id>.html fragment and, when measured, one<id>.png per candidate.

rikiki scene compile writes the whole slide of the candidate you name: the claim as its title, the scene, the source and the notes, headed by a comment that lists the <script> tags to add once to the deck. rikiki scene budgets prints the narrowest width a shape draws cleanly at, and how many characters each field holds for each number of items.

FlagEffect
--jsonplan, budgets: the result on stdout and nothing else, an invalid brief included
--out dirplan: where the plan, the fragments and the pictures go · compile: the file the slide is written to
--measureplan: draw and photograph each candidate · without --out the pictures go to a temporary directory, named on stderr
--candidate idcompile: the candidate to write · an unknown one is refused with the list of those the plan has
--width unitsbudgets: the scene's width in drawing units (default 1600, the whole canvas)
CodeMeaning
0plan: at least one candidate fits · compile, budgets: done
1plan: no candidate fits
2the call cannot be carried out · a brief missing, not JSON or not valid (each error is listed by its path), an unknown candidate or shape

intent · from a sentence to a diagram that proves it

Prints the skeleton of a deck-diagram written as an intent: the relation the picture demonstrates, one of sixteen (cause,barrier, bottleneck, accumulate,transform, feedback, scale,contain, parallel, propagate,threshold, tradeoff, drift,compare, partition, merge), and the part each mark plays in it (role="…"). The intent chooses the layout, the one thing put forward and the order things come in, each its own way, so two intents never draw alike; the skeleton holds no coordinate and no duration.

terminal
# the skeleton of the intent a sentence points at
npx rikiki intent "Six files arrive, review handles two, the rest wait"

# the skeleton of one intent, by name
npx rikiki intent bottleneck

# the sixteen intents, what each demonstrates and what it looks like
npx rikiki intent --list

Given a sentence, it looks for the cues of each intent in it (it cuts, it waits, it piles up, it loops, it spreads, past a line, at the cost of, before and after) and prints the closest one; nothing calls a model, so the same sentence always gives the same skeleton. Above the diagram, a comment lists its roles with their bounds, the intents it composes with (also="…") or why it takes none, and the mistakesrikiki check rejects, the INT_* findings: a gate that leaves a lane out, a neck as wide as what feeds it, a loop that never comes back, a crowd under ten times its unit, parts that do not add up to the whole, a wave that jumps a rank, a gap that does not widen. A defect of meaning is an error, whatever the drawing's score. --list names the sixteen intents with what each demonstrates and what it looks like. A sentence that tells a story rather than a relation (an incident, a remedy, a zoom out) exits with 3 and names the closestrecipes; a sentence with no cue at all exits with1 and names the intents. With an intent found, the comment also names the recipes near it.

recipe · a graphic model, filled from a brief

Prints one of twelve recipes: a skeleton of deck-diagram told as a story played on entry, taken from a graphic model (incident frise, lanes and a gate, a probe, wiring, a switch-over, a race, records through a filter, lanes of versions, an escalation, a pulse and its threshold, rings of scope, a replay of data). Its marks are named for the part they play, its {{fields}} are the facts of a brief and its beats are the sequence the model imposes. Above the skeleton, a comment lists the brief to fill (each field, what it holds, an example), the sequence, whatrikiki check guarantees, when not to use it, its neighbours and its pitfalls.

terminal
# the twelve recipes, their graphic model and their tempo
npx rikiki recipe --list

# the closest recipe to a sentence · its brief, its sequence, its pitfalls, its skeleton
npx rikiki recipe "Tout est vert, et 19 h sans un lead"

# the example brief as JSON, then your brief drawn as a slide
npx rikiki recipe incident-band --brief > brief.json
npx rikiki recipe incident-band --fill brief.json

# the slide its example brief draws
npx rikiki recipe incident-band --example

The brief comes first: the real system and its actors, its normal pace, the dated event, the exact cause, the consequence counted, the proof.--fill refuses a brief (exit 1, each field said) when a field is empty, generic, longer than its place holds, or when the brief holds fewer than two precise values (a date, an hour, a number, an identifier). Like intent, a sentence is read by its cues and nothing calls a model: the same sentence always gives the same recipe.

Next

  • Theming · the tokens behind --theme, and how to write a theme of your own.
  • Multi-file decks · the manifest assemble reads.