CLI recipes

Short, copyable sequences for the workflows we use every day. Each recipe ends with the “and now I’m done” command so you can stop scrolling.

Bring a fresh checkout to life

bun install
cp .env.example .env
kumiko dev          # boot postgres + redis + meilisearch
kumiko doctor       # sanity-check env vars + services
kumiko migrate apply
kumiko test

If doctor shows red marks, the hint next to each ✗ tells you exactly what to run. The most common ones are bun install and cp .env.example .env.

Add a new feature

kumiko create myFeature                     # scaffold workspace
# edit samples/recipes/my-feature/src/feature.ts
bun install                                # picks up the new workspace
kumiko codegen                              # regenerate type maps
kumiko migrate generate                     # if you added entities
kumiko migrate apply
kumiko test samples/recipes/my-feature/     # path-filtered run

Validate before pushing

The pre-push hook calls check. To run it manually:

kumiko check:fast    # iterates fast: parallel biome/ts/guards + bun test --changed
# … if green:
kumiko check         # full pass — same scope as CI

check:fast is safe for pre-commit because it parallelises the four quality gates and only runs tests on changed files. CI uses the full check (or ci:guards for the guard-only job split).

Recover from a stuck event consumer

A consumer with status=poisoned is blocking the read-model rebuild:

kumiko consumer list                         # see them all
kumiko consumer status <consumer-name>       # detail + last error
kumiko consumer restart <consumer-name>      # release lock + retry
# … if it's truly a bad event:
kumiko consumer skip <consumer-name>         # advance cursor past it

skip is the nuclear option — it bumps the cursor past the current event without processing it. Use only when the event is genuinely unprocessable (corrupt payload, dropped entity reference, etc.).

Prune the events table

Events older than 30 days can be safely deleted once all consumers have caught up — kumiko events prune refuses to delete anything that would put a consumer behind the cutoff:

kumiko events prune --older-than 90 --dry-run   # preview
kumiko events prune --older-than 90              # do it

If you get ConsumerLagError, see the consumer-recovery recipe above.

Reset to a clean slate

Tabula rasa — drops all docker volumes, then restarts services:

kumiko reset
kumiko migrate apply

Useful when a test run left the DB in a weird state, or when migrations got out of sync with what’s in drizzle/migrations/.

Production build

cd samples/apps/my-app
kumiko build
# → dist/ ready to ship

Convention-driven (Bun.build + Tailwind + public-folder copy). No config required. kumiko build <path> builds an app outside the current directory.