CLI

The kumiko CLI is the daily-driver surface for working with a Kumiko app. It boots local Docker services, runs codegen, migrates the database, manages event consumers and projections, runs tests, and ships production builds — all with a single kumiko <verb> entry point.

The 30-second tour

bun kumiko dev        # boot Postgres + Redis + Meilisearch (docker compose up -d)
bun kumiko doctor     # is everything healthy?
bun kumiko create myFeature   # scaffold a new feature workspace
bun kumiko codegen    # regenerate .kumiko/define.ts + types.generated.d.ts
bun kumiko schema generate my-change   # generate a migration
bun kumiko schema apply                # apply pending migrations
bun kumiko test       # run unit tests (bun:test)
bun kumiko check      # full quality pass (lint + types + guards + tests)
bun kumiko build      # production build
bun kumiko stop       # bring services down (volumes stay)

Running kumiko with no arguments opens an interactive TUI (Ink-based) for discovering commands. Pipe-friendly contexts (CI, scripts) fall back to a plain help screen.

Roles

The CLI is role-aware. Commands are grouped into two roles:

• app-dev — what you get when you run kumiko inside an app workspace. Hides framework-maintenance commands you don’t need.
• maintainer — auto-detected inside cosmicdriftgamestudio/. Adds ES-ops, code mods, CI guards, AI-eval delegation.

Override with --as <role>:

kumiko events prune --as maintainer

Commands

Lifecycle

• kumiko dev — boot local Docker services
• kumiko stop — stop services (data stays)
• kumiko reset — wipe volumes + restart
• kumiko status — services + git at a glance
• kumiko doctor — health check
• kumiko docs — open these docs in your browser

Code

• kumiko new app — scaffold a runnable app workspace
• kumiko add feature — add a feature to the current app
• kumiko create <name> — scaffold a recipe/feature workspace
• kumiko init-deploy — Dockerfile + migrate step templates
• kumiko codegen — regenerate per-app codegen
• kumiko build — production build
• kumiko codemod — code migrations (maintainer)

Quality

• kumiko check — full quality pass
• kumiko check:fast — fast iteration loop (maintainer)
• kumiko test — bun:test / Playwright runner

Ops

Maintainer-only unless you pass --as maintainer:

• kumiko schema — DB schema migrations
• kumiko events — events table (prune) (maintainer)
• kumiko consumer — event consumers (maintainer)
• kumiko project — projections (list/status/rebuild)
• kumiko ops — ES seed workflow (maintainer)
• kumiko clean-test-dbs — drop orphan test DBs (maintainer)

Framework-internal (maintainer only)

• kumiko ci:guards — CI job splitter
• kumiko eval — L2 AI eval (delegates to kumiko-enterprise)

Help

kumiko help                # role-filtered command list
kumiko help <command>      # per-command usage + docs URL
kumiko <command> --help    # same as `kumiko help <command>`
kumiko docs <command>      # open the docs page for one command

Where the CLI lives

The CLI lives in kumiko-framework/bin/. Each command is a single file under bin/commands/ that registers itself via defineCommand at import time. Adding a new command is a one-file change plus a side-effect import in bin/commands/index.ts.

The legacy 1600-LOC monolith (bin/kumiko-legacy.ts) hosts the parallel-lock + tee-logging machinery for check/check:fast/ci:guards until Sprint C extracts it. End users never call it directly.