CLI
k9o is Kilimanjaro's terminal companion to the SDKs and Console. Every invocation maps to one or more platform API calls — nothing bypasses the platform's authentication, RBAC, or policy layers — and --output json emits the identical {data, meta} / KError wire shape the SDKs deliver, so the CLI is scriptable end-to-end.
This page is the command reference. It lists the full command surface exactly as the CLI's own k9o --help groups it; each group's exhaustive per-subcommand flags live behind k9o <command> --help, which is the authoritative source for your installed version.
1. Installation
npm install -g @k9o/cli # cross-platform (Node 20+)
pnpm add -g @k9o/cli
Verify, and check which API major the CLI speaks:
k9o --version
# k9o/<ver> api/v2
A CLI built for api/v2 does not talk to v3 endpoints — k9o --version is the quick check when troubleshooting a version mismatch. k9o ledger verify needs the separate kibo-ledger-verify binary, which the npm package does not ship.
2. Getting started — k9o init
k9o init is the interactive first step on a new machine or project: it runs authentication, lets you pick an org and an active project, and persists the binding so later commands don't need repeated flags.
k9o init
After init, commands like k9o migration apply and k9o function deploy know which project to target. The getting-started group:
| Command | Purpose |
|---|---|
k9o init | Interactive setup — authenticate and pick an active project |
k9o login | Sign in as an operator |
k9o logout | Clear local credentials |
k9o whoami | Print the active identity |
3. Authentication & context
Interactive login
k9o login --base-url https://acme.api.k9o.io -O acme -P member-portal
login signs in as the operator with email and password. The password is read without echo, from the prompt or from K9O_PASSWORD; there is no --password flag. The email comes from K9O_EMAIL if not prompted. Other secret prompts, such as the byos cred and vault secret values, are read without echo too and writes credentials to the active profile's local store. When the org requires multi-factor authentication, pass the authenticator code with --mfa-code (or K9O_MFA_CODE). --project is optional. Subsequent commands exchange the stored token for short-lived access tokens transparently. k9o whoami prints the active identity; k9o logout clears it. The base URL, org, and project each fall back to an environment variable (§6) when the flag is omitted.
:::note CI / non-interactive auth
In CI, skip k9o login and set K9O_SERVICE_TOKEN together with K9O_ORG and K9O_PROJECT. A service token is not accepted by k9o ext, which needs an operator sign-in.
:::
Project context resolution
Every command that touches project data resolves its context in this order:
--project <slug>(-P) flag — per-invocation overrideK9O_PROJECTenvironment variable- The active project persisted by
k9o init/k9o project set-active
If nothing resolves, the command exits 65 (MISSING_PROJECT_CONTEXT) and prints the precedence list.
4. Command surface — project resources
The commands that operate on a project. Run k9o <command> --help for each one's full flag set.
project — projects and active context
k9o project list # list projects in the active org
k9o project get <slug> # show one project
k9o project create <slug> [--name <display name>] [--region <code>] [--custody-mode PLATFORM_MANAGED|SKR|BYOK|HYOK]
k9o project set-active <slug> # persist the active-project binding
Project deletion is Console-only today — the CLI's delete flow is reserved and not yet implemented.
migration — schema migrations
k9o migration apply <file.json> # { "migrations": [{ "version", "slug", "up", "down" }] }
k9o migration list # applied migrations
k9o migration pending # queued migrations awaiting apply
k9o migration apply-pending <pendingId>
IRREVERSIBLE_ACTION_GATE operations still run through the project's configured Maker-Checker policies during apply; the CLI does not bypass governance.
function — serverless functions
k9o function deploy --name my-fn --runtime bun --tier sandbox --version 1 --artifact ./fn.tar # or a <manifest.json>
k9o function list
k9o function get <name>
k9o function invoke <name> --payload '{"x":1}' # or --payload-file <file>
k9o function delete <name>
deploy uploads one artifact. The tier is sandbox, and the runtime is one of bun, rust, go, tinygo, zig, assemblyscript, c or cpp: Firelock's Bun guest runs bun, and its Wasmtime guest runs the WASI labels. --packaging bundle|image chooses how the code ships (default bundle).
invoke takes --payload as a JSON string for a one-off test call:
k9o function invoke compute --payload '{"x":1,"y":2}'
policy — policy bundles
k9o policy apply <file> [<file> ...] # create a draft bundle
k9o policy validate <file> [<file> ...] # check without persisting
k9o policy publish <id> # publish a draft (may need a second approver)
k9o policy list [--status draft|published|superseded]
k9o policy get <id>
k9o policy current
audit — audit events
k9o audit tail [--since-minutes 5] [--limit 100] # recent events, fetched once
k9o audit query [--event-type <t>] [--actor <id>] [--after <iso>] [--before <iso>] [--limit <n>] [--cursor <c>]
k9o audit export <file.ndjson> [same filters]
Exported ledgers verify cryptographically with k9o ledger verify.
ext-admin and ext — extensions
ext-admin is the project-owner surface (list, enable, disable, config); ext runs a specific installed extension's own commands.
k9o ext-admin list # extensions installed on the project
k9o ext-admin --help # list / enable / disable / config (+ publisher verbs with @k9o/extension-cli)
k9o ext <slug> --help # a specific extension's own command surface (operator sign-in required)
5. Command surface — org, account, local dev, utility
Org & account
| Command | Purpose |
|---|---|
k9o org | Org-level resources — members, roles, SMTP, identity providers (create · invite · grant · revoke · configure · list · …) |
k9o me | Your own operator profile, sessions, and tokens (get · update · revoke · …). k9o me api-tokens create --tier readonly|readwrite|admin mints a personal access token at that scope tier |
k9o idp | End-user sign-in providers for a project |
k9o crypto | Server-side encryption — mode --crypt · federated-token · keys |
Local dev
| Command | Purpose |
|---|---|
k9o stack | Manage the local dev stack — up · down · status · logs |
k9o showroom | Provision a demo / showroom project |
k9o doctor | Check your local dev environment for issues |
These three commands run run.sh from a k9o-core checkout, so they work only where one is present; the npm package does not ship it.
Utility
| Command | Purpose |
|---|---|
k9o config | Local CLI profile config — get · set · list · unset |
k9o ledger verify | Offline audit-ledger integrity verification (see below) |
k9o completion | Emit a shell completion script — bash | zsh | fish |
k9o ledger verify is a thin launcher over the kibo-ledger-verify Rust binary; no verification logic is re-implemented in the CLI. The npm package does not include that binary, so install it separately:
k9o ledger verify --file export.ndjson # verify a ledger file
cat export.ndjson | k9o ledger verify --stdin # verify from stdin
k9o ledger verify --file export.ndjson --format json # structured output for CI
The launcher resolves the binary from $K9O_LEDGER_VERIFY_BIN, then the bundled vendor path, then kibo-ledger-verify on $PATH (the standalone offline-auditor case).
6. Global flags & environment
Every command accepts these flags, and each has an environment-variable default:
| Flag | Env default | Description |
|---|---|---|
--project <slug>, -P | K9O_PROJECT | Project context override |
--org <slug>, -O | K9O_ORG | Org context override |
--output human|json | K9O_OUTPUT | Output format (default human) |
--profile <name>, -p | K9O_PROFILE | Profile selector (default default) |
| — | K9O_SERVICE_TOKEN | Service token for CI; use instead of k9o login |
--no-color | — | Disable ANSI colours |
--quiet / -q | — | Suppress non-essential output |
--verbose / -v | — | Emit debug diagnostics to stderr |
--help / -h | — | Show help for the command |
K9O_BASE_URL sets the default --base-url for login. In CI, K9O_SERVICE_TOKEN replaces login (§3).
Profiles
Named profiles keep multiple environments separate:
k9o migration apply migrations.json -p staging
export K9O_PROFILE=staging # or set it for the shell
7. Output and exit codes
--output json (or K9O_OUTPUT=json) is the canonical contract for scripting — do not parse human output.
- Success: stdout receives
{"data": <result>, "meta": <meta>}, exit0. - Failure: stderr receives the
KErrorshape{"code", "message", "context", "recommendation"}, exit non-zero per the table.
k9o migration apply migrations.json --output json | jq '.data'
The exit codes map deterministically from the platform's error-family taxonomy, so a script can branch on the code alone:
| Code | Meaning |
|---|---|
0 | Success |
1 | Generic / unexpected (rare catch-all) |
2 | CLI usage error — bad flags / unknown command, before any API call |
64 | Local config error (~/.k9o config or credentials malformed) |
65 | Missing context (MISSING_PROJECT_CONTEXT / MISSING_ORG_CONTEXT) |
66 | Auth — unauthenticated (401 family) |
67 | Auth — forbidden (403 family) |
68 | Not found (404 / *_NOT_FOUND) |
69 | Conflict (409 / *_CONFLICT / *_ALREADY_*) |
70 | Validation — parse-time (400 / malformed input) |
71 | Validation — semantic (422) |
72 | Capacity (429 / K9O_TIER_CAP_HIT) |
73 | Service unreachable (5xx family) |
74 | Token expired (410 / K9O_SESSION_EXPIRED) |
75 | Lifecycle (K9O_PROJECT_SOFT_DELETED, etc.) |
8. Shell completion & CI
k9o completion bash > /usr/local/etc/bash_completion.d/k9o
k9o completion zsh > "${fpath[1]}/_k9o" # then restart the shell
k9o completion fish > ~/.config/fish/completions/k9o.fish
The structured-output and exit-code contract makes the CLI scriptable in CI. The shape of a migration step, using --output json and a service token with the target org and project:
- name: Apply migrations
env:
K9O_SERVICE_TOKEN: ${{ secrets.K9O_SERVICE_TOKEN }}
K9O_ORG: acme
K9O_PROJECT: member-portal
run: k9o migration apply migrations.json --output json
Check the exit code against §7 to branch on family-appropriate outcomes. See §3 for CI authentication.
9. See also
- Gate — Auth — the authentication surface
k9o loginuses. - Data — Migrations — the migration surface
k9o migrationcomposes against. - Compute — Functions — the function lifecycle
k9o functionuses. - Security — Audit Log — the surface
k9o auditandk9o ledgeroperate against. - Kibo → CLI — Kibo vault secrets and offline ledger verification in the Kibo context.