Skip to content

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 ​

CommandPurpose
doctorCheck local prerequisites.
repositoriesPreview 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.
devRun infrastructure in Docker and applications as native processes.
statusInspect container status.
logs [--tail N] [-f]Read recent logs or follow with -f.
local-status / local-logs / local-downInspect, follow logs or stop native processes.
credentialsShow first-login credentials locally.
context-public-keyPrint the public key used by business backends to verify Gateway Context.
reload-routesReload managed routes in local Compose.
down / resetdown stops and retains data. reset deletes local platform data after confirmation.
deploy-init / helpFetch the optional GitOps repository or show launcher help.

Sessions and projects ​

CommandPurpose
login [--client NAME] [--local]Authorize this client. --local attempts local approval. Remote approval belongs to the account holder.
whoami / logoutInspect 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 CODEStop that business stack and retain its data.
project entry CODE LABEL SERVICE_URLRegister 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 ​

CommandPurpose
access members CODE / access roles CODE / access permissions CODEList 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 USERRemove a project member.

Product & frontend repository scripts ​

Run these commands inside a repo created from kaiwu-web-starter or Project Factory:

CommandPurpose
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 devStart dev server in Mock mode by default; open /__mock/ to switch personas and reset in-memory data.
pnpm dev:realDisable Mock and proxy /api, /{code}-api, and /{code}-svc to KAIWU_GATEWAY (http://127.0.0.1:8088 by default).
pnpm verify:mockProduct-stage gate: typecheck, dictionaries, @/kaiwu lock, rule/scenario/mock linkage, log redaction, constraints, and dist isolation check.
pnpm verifyIntegration-stage gate: verify:mock plus three-way permission parity against backend @RequirePermission annotations.
pnpm test:scenarios / pnpm test:browserRun HTTP scenario tests / Chromium E2E tests against an isolated mock server.
pnpm test:proxyVerify 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" CODEVerify 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.

Apache License 2.0