Skip to main content
A guide can mark its shell commands as runnable. make verify then replays them against the real local stack, so a change in the API breaks the guide in CI instead of leaving it silently wrong. Your first search is the reference example.

​
Mark a block

Tag a shell fence with runnable, and follow it with the output it must print, tagged output:
  • The command runs with bash -eo pipefail in an empty temporary folder, with QUIVR_URL (the API address) and QUIVR_KEY (a key with every action on the whole Organization) set. A non-zero exit fails the block.
  • The output block is optional and must come right after its command, with only prose in between. A json output block is compared as JSON; any other output block is compared as trimmed text.
  • sh runnable retry reruns the command, once a second for up to 60 seconds, until its output matches. Use it where the reader waits too: a Receipt resolving, a Record becoming searchable.
  • Fences without runnable, such as the reader’s own export lines, are not run. A kept value (below) that a later block uses must be exported in such a fence before that block, or the page is refused: readers copying it would miss it.

​
Expected JSON

The expected output asserts only what it shows, so write the stable fields a reader relies on and leave the rest out. A kept value is exported as $NAME to the page’s later blocks. Tell readers to do the same with a plain sh block, for example export CORPUS_ID=<the corpus_id above>.

​
How pages are replayed

scripts/guides.py reads every page declared in the documentation inventory (docs/inventory.toml). In make verify, after the timed scenarios, it replays each page with runnable blocks in order, in its own Organization, and stops a page at its first failing block because later blocks depend on it. Results are written to guides.json in the verification folder. A failure names the page, the block and the difference:
Against a stack you started with make dev, with a key of an Organization the page has not run in yet: idempotency keys are fixed, so a second run replays the first one’s results and a page that changes content, like the first-search guide, no longer matches (make reset starts over):
Runnable blocks are the only request and response examples a guide should show; link to openapi.yaml for the rest.