CLI

Kumiko has two command-line surfaces. Which one you use depends on where you work:

• In your app you use the published @cosmicdrift/kumiko-cli package, the package scripts that kumiko new app writes, and a few binaries from the framework packages. This is all an app developer needs.
• In the framework repository (kumiko-framework) contributors use bun kumiko <verb>. Most of its commands start Docker services, run guards or manage the framework’s own test databases. They do not exist in an app.

In your app

Create an app and add features with the published CLI:

bunx @cosmicdrift/kumiko-cli@latest new app my-app
bunx @cosmicdrift/kumiko-cli add feature notes
bunx @cosmicdrift/kumiko-cli check

Day to day you run the scripts in the app’s package.json:

Script	Runs	Purpose
bun dev	bun --watch bin/dev.ts	Dev server with the welcome banner
bun run boot	bin/main.ts in dry-run mode	Validate features and env without a database
bun run test	bun test with the unit bunfig	Unit tests
bun run test:integration	kumiko-testing integration	Integration tests against Postgres
bun run schema:generate <name>	kumiko-schema generate	Write a SQL migration
bun run schema:apply	kumiko-schema apply	Apply pending migrations
bun run build	kumiko-build	Production build into dist/ and dist-server/
bun run start	bin/main.ts	Run the production server

Commands available in an app

Command	Comes from	Page
kumiko new app, kumiko add feature	@cosmicdrift/kumiko-cli	new, add
kumiko check	@cosmicdrift/kumiko-cli	check
kumiko project, kumiko consumer	@cosmicdrift/kumiko-cli	project, consumer
kumiko agent lint	@cosmicdrift/kumiko-cli	agent
kumiko sync-managed, kumiko ports	@cosmicdrift/kumiko-cli	sync-managed, ports
kumiko api-docs	@cosmicdrift/kumiko-cli	api-docs
kumiko-upgrade	@cosmicdrift/kumiko-cli, @cosmicdrift/kumiko-dev-server	upgrade
kumiko-schema, kumiko-build, kumiko-init-deploy	@cosmicdrift/kumiko-dev-server	schema, build, init-deploy
kumiko-testing	@cosmicdrift/kumiko-testing	Testing standard

In the production image

bun run build also bundles a small CLI into dist-server/kumiko.js. It only knows schema and consumer and needs no dev dependencies:

bun /app/kumiko.js schema apply
bun /app/kumiko.js consumer list

See Deploy: Docker.

In the framework repository

The commands below live in kumiko-framework/bin/. Run them from a framework checkout as bun kumiko <verb>. The pages marked framework repository only describe commands an app does not have.

bun kumiko dev        # boot Postgres, Redis, Meilisearch and MinIO (docker compose up -d)
bun kumiko doctor     # is everything healthy?
bun kumiko create myFeature   # scaffold a new feature workspace
bun kumiko test       # run unit tests (bun:test)
bun kumiko check      # full quality pass (lint + types + guards + tests)
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

Commands are grouped into two roles:

• app-dev, the default. Hides framework-maintenance commands.
• maintainer, auto-detected inside the framework workspace. 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 build, production build
• kumiko codemod, code migrations (maintainer)
• kumiko upgrade, what changed since your version
• kumiko changes, author changelog entries

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 the enterprise evaluation package)

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

Each command is a single file under kumiko-framework/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.