CLI
oke and create-oke commands — scaffold, develop, ship, and operate an okengine app.
The CLI is how you scaffold, run, and operate an app. create-oke writes the project;
oke is the day-to-day binary (dev loop, schema, vault, docker, doctor).
For developers who already know the model — look up a command, its flags, and what it writes.
The one rule
Prefer the CLI for environment wiring (oke dev, oke db, oke docker). Put behavior in Flows
and oke.config.ts — never invent a ninth element or hand-edit the Manifest.
Smallest Example
Scaffold an app
bunx create-oke@latest notes --yes
cd notesRun the dev loop
bun run devbun run dev is the portable form (bunx oke dev is the same). Bare oke needs node_modules/.bin on PATH — PowerShell does not add it.
Compose comes up (pull / create / start progress streams into the boot status
lines), the backend listens on 6530, Console on 6533, app MCP on 6535,
docs MCP on 6536. Open http://localhost:6533. Quit with Ctrl+C.
On a TTY, after schema push, oke dev also:
- Prompts one-by-one for any Vault boot gaps (writes
.env.local) — e.g.OPENROUTER_API_KEYwhen create-oke /oke ai setup/ Keel declared the OpenRouter contract without a value. - Asks to run
oke db seedwhen a seed module exists and.oke/state.jsonhas not recorded that seed identity yet. Runoke db seedanytime later.
Progressive Patterns
oke dev # watch · Console · client types · Docker Compose
oke test # bun test with PGLite posture
oke doctor # secrets · ports · schema drift
oke doctor --diff # CI gate: undeclared contract breaksPort Map
| Port | Surface | Who starts it |
|---|---|---|
| 6530 | Backend API | oke dev / oke start |
| 6533 | Developer Console | oke dev |
| 6535 | App MCP | oke dev |
| 6536 | Docs MCP (read-only) | oke dev |
Override app / console / mcp listen ports in oke.config.ts ports — see
Configuration.
oke Commands
| Command | Purpose | Key flags / subs |
|---|---|---|
dev | Watch · hot reload · Console · client types (Docker Compose) | --docker|-d [roles], --no-db-push, --entry|-e |
test | Run bun test with PGLite test posture | |
start | Production entry (Docker CMD) | --entry|-e, --port|-p |
doctor | Secrets · ports · stub/domain schema drift | --manifest, --diff, --before, --after, --base, --json |
stack | Preview images / tags / ports (writes nothing) | --config, --json |
schema | Core + plugin tables → .oke/schema/oke.ts | generate (--check, --manifest, --out) |
db | Domain schema | push · generate · migrate · seed · studio · search-backfill |
client | Ambient types for a separate frontend repo | add <url> (--out) |
vault | Secrets | set · list · import · key · init · status · seal · unseal · rotate · rotate-master · audit · purge-expired · backup · restore |
docker | Derive compose · clean leftover stacks | --prod|-p, --out, --config, --manifest; sub clean |
images | List / pin digests | list · pin |
build | Tree-shaken bundle | --target|-t bun|node|edge, --entry, --outdir |
eval | Prompt eval sets (CI gate) | --manifest |
ai | Configure AI driver + models | setup (--provider, --chat, --vision, --embed, --yes) |
branch | Fork journaled state | <name>, --at|-a |
replay | Re-invoke a past Flow from Runs | --request-id|-r, --entry, --dry-run, --live |
privacy | Crypto-shred subject data | erase (--subject|-s) |
upgrade | Breaking-change codemods + diff | --apply|-a |
console | Console helpers | claim-code (--json) |
gates | Gate catalogue from Manifest | list (--manifest, --json) |
completion | Shell completion script | bash · zsh · fish |
mode | Deprecated — oke dev always uses Docker Compose | --help |
Bare oke (TTY) opens the interactive board; oke --help prints the catalogue.
oke db detail
Shared flags on push / generate / migrate / studio: --config\|-c, --env name
(dev · test · prod). Seed adds --force, --entry. Search-backfill adds
--batch n and a <table> positional.
oke db push --env dev
oke db migrate --env prod
oke db seed --force
oke db search-backfill notes --batch 500create-oke
| Flag | Meaning |
|---|---|
-t, --template <id> | standard (default) or advanced |
--sql <id> | Store SQL dialect — only postgres (test stays pglite) |
-y, --yes | No prompts; defaults + bun install (no oke dev) |
--install / --no-install | Run or skip bun install after scaffold |
--agents-md / --no-agents-md | Write AGENTS.md (default on) |
--ai / --no-ai / --ai skip | Configure or skip AI setup |
--locales <tags> | Extra languages beyond English (e.g. ar or ar,fr) |
--pgdog / --no-pgdog | Pin PgDog in front of Postgres |
--proxy <id> / --no-proxy | none · caddy · traefik · nginx |
-h, --help | Show help |
Troubleshooting
PowerShell has no local oke on PATH. Use bun run dev or bunx oke dev. New Cursor/VS Code
terminals inherit node_modules/.bin from .vscode/settings.json. Global: bun install -g okengine.
oke resolved to %USERPROFILE%\.bun\install\global\node_modules\okengine. From a framework
checkout run bun install then bun run dev:keel — not a global oke. Keel links with a Windows
junction; a plain symlink needs Developer Mode and fails with EPERM.
Interrupting install or bun run dev used to delete a folder create-oke had just created. On
Windows that wipe often failed mid-tree (EBUSY) and left an empty or half-deleted project.
After scaffold, Ctrl+C only stops the process. cd into the folder and run bun run dev again.
Missing docker is a separate install — Compose needs it on PATH.
:6533 is up but the SPA files were not found. Published okengine ships them. Upgrade past the
Windows path bug (file:// /C:/… lookup), then restart bun run dev. From a framework
checkout, run bun run build or keep oke dev so Vite HMR attaches.
Postgres was initialized with an older password than .env.local — usual after deleting and
recreating the folder. oke dev resets that project's volumes when it sees this.
Already failed? From the app folder: oke docker clean then bun run dev. Run commands
inside the project (o1), not the parent oke directory.
The app child had no Manifest to stamp effects (main.health). oke dev now hands the parent
extract to the child. A failed extract appends Manifest extract failed — … (oxc-parser).
Set package.json okengine.entry or main, pass --entry, or keep a conventional
src/app.ts. Production imports that module; the app must call createBunRuntime().serve itself.
oke schema generate emits framework / plugin stub tables under .oke/schema/. oke db generate
emits versioned domain SQL via Drizzle. Use db for your app tables; use schema when the stub
drifted after a plugin change.
oke mode is deprecated. oke dev always starts Docker Compose. There is no soft-compat for old
local / docker env map keys — rename to dev / test / prod in
Configuration.
Domain tables are missing in prod (no auto-DDL). Run oke db migrate against that environment —
see Errors.
The setup claim code prints on the oke dev TTY board and is mirrored to gitignored
.oke/claim-code. Run oke console claim-code while setup is open.
Learn more
- Configuration —
oke.config.tsdrivers and ports - Environment Variables — what Compose writes
- Security — Host / Origin /
allowedHosts - The Architecture — one contract;
oke doctor --diffreviews it - Vault —
oke vaultrotate / unseal