CLI

The kumiko CLI is the main command-line tool for Kumiko apps. It boots local Docker services, runs codegen, applies database migrations, manages event consumers and projections, runs tests, and builds for production. Each operation uses a kumiko <verb> command.

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 upgrade    # what changed since your pinned version
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.