CLI reference
Prefix the following commands with ./kaiwu in the entry repository. Replace uppercase arguments with actual values. Brackets indicate optional arguments and a slash separates alternatives. Choose one alternative when executing a command. For a first installation, start here.
Platform runtime
| Command | Purpose |
|---|---|
doctor | Check local prerequisites. |
repositories | Preview repository source and version policy. |
init [--with-deploy] | Fetch runtime repositories, optionally including GitOps. |
up [--build / --no-build] | Start the platform. A release normally pulls images. Use --build for source builds. |
dev | Run infrastructure in Docker and applications as native processes. |
status | Inspect container status. |
logs [--tail N] [-f] | Read recent logs or follow with -f. |
local-status / local-logs / local-down | Inspect, follow logs or stop native processes. |
credentials | Show first-login credentials locally. |
context-public-key | Print the public key used by business backends to verify Gateway Context. |
reload-routes | Reload managed routes in local Compose. |
down / reset | down stops and retains data. reset deletes local platform data after confirmation. |
deploy-init / help | Fetch the optional GitOps repository or show launcher help. |
Sessions and projects
| Command | Purpose |
|---|---|
login [--client NAME] [--local] | Authorize this client. --local attempts local approval. Remote approval belongs to the account holder. |
whoami / logout | Inspect identity or revoke the CLI session. |
project new CODE --name NAME [--package PKG] [--description TEXT] | Register a project and generate its scaffold once. |
project status CODE [--wait] | Inspect progress, optionally waiting for completion. |
project pull CODE [--dir DIR] | Download and unpack both repositories and initialize Git. |
project adopt FRONTEND [--apply] | Register an existing product frontend, sync manifests/initial roles, and generate the companion backend (ADOPT_FRONTEND). |
project-up BACKEND [FRONTEND] | Build the business project and connect it to the local platform. |
project-down CODE | Stop that business stack and retain its data. |
project entry CODE LABEL SERVICE_URL | Register the entry label and service root URL. |
project sync MANIFEST_REPO [--apply] [--with-access] | Preview or sync kaiwu/*.yml (from a backend or adopted frontend repo). Include role grants explicitly with --with-access. |
workflow sync FRONTEND [--apply] | Preview or import kaiwu/workflows/ definitions (requires compatible Workflow service). |
Members and grants
| Command | Purpose |
|---|---|
access members CODE / access roles CODE / access permissions CODE | List members, roles or grantable permissions. |
access role-create CODE ROLE --name NAME [--description TEXT] | Create a project role. |
access role-grant CODE ROLE (--permissions p1,p2 / --clear) | Replace the role’s permission set. Use --clear to empty it. |
access member-set CODE USER --roles r1,r2 [--disabled] | Replace the member’s roles and enable membership by default. --disabled disables it. |
access member-remove CODE USER | Remove a project member. |
Product & frontend repository scripts
Run these commands inside a repo created from kaiwu-web-starter or Project Factory:
| Command | Purpose |
|---|---|
node scripts/kaiwu-init.mjs --code CODE --name NAME [--example booking] | Initialize a standalone business frontend from kaiwu-web-starter (blank by default; optional booking or purchase example). |
pnpm dev | Start dev server in Mock mode by default; open /__mock/ to switch personas and reset in-memory data. |
pnpm dev:real | Disable Mock and proxy /api, /{code}-api, and /{code}-svc to KAIWU_GATEWAY (http://127.0.0.1:8088 by default). |
pnpm verify:mock | Product-stage gate: typecheck, dictionaries, @/kaiwu lock, rule/scenario/mock linkage, log redaction, constraints, and dist isolation check. |
pnpm verify | Integration-stage gate: verify:mock plus three-way permission parity against backend @RequirePermission annotations. |
pnpm test:scenarios / pnpm test:browser | Run HTTP scenario tests / Chromium E2E tests against an isolated mock server. |
pnpm test:proxy | Verify path and project header forwarding against a local echo server, or real Gateway responses when KAIWU_GATEWAY is set. |
sh scripts/check-runtime-image.sh "$IMAGE" CODE | Verify the built production frontend container serves the app index and returns 404 on /__mock/. |
Backend annotation checks require the paired backend in the expected adjacent directory or an explicit KAIWU_SERVICE_DIR. Check the output to confirm the comparison ran.
System launcher extensions
Prefix these commands with ./workspace/kaiwu-system-service/scripts/kaiwu.sh. Use local-up for an existing Nacos environment. Use storage accounts to list accounts, storage bindings [CODE] to list bindings and storage test ACCOUNT to write and delete a probe. storage bind CODE --account ACCOUNT supports --name, --max-mb and --types. Use storage bind-status ID --status ACTIVE with ACTIVE, READ_ONLY or DISABLED. Storage walkthrough
Set KAIWU_URL to select a remote platform, KAIWU_REPOSITORY_REF to pin checkout versions and KAIWU_REPOSITORY_BASE_URL to select a fork’s repository group.