Skip to main content

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:

CommandPurpose
k9o initInteractive setup — authenticate and pick an active project
k9o loginSign in as an operator
k9o logoutClear local credentials
k9o whoamiPrint 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:

  1. --project <slug> (-P) flag — per-invocation override
  2. K9O_PROJECT environment variable
  3. 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​

CommandPurpose
k9o orgOrg-level resources — members, roles, SMTP, identity providers (create · invite · grant · revoke · configure · list · …)
k9o meYour 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 idpEnd-user sign-in providers for a project
k9o cryptoServer-side encryption — mode --crypt · federated-token · keys

Local dev​

CommandPurpose
k9o stackManage the local dev stack — up · down · status · logs
k9o showroomProvision a demo / showroom project
k9o doctorCheck 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​

CommandPurpose
k9o configLocal CLI profile config — get · set · list · unset
k9o ledger verifyOffline audit-ledger integrity verification (see below)
k9o completionEmit 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:

FlagEnv defaultDescription
--project <slug>, -PK9O_PROJECTProject context override
--org <slug>, -OK9O_ORGOrg context override
--output human|jsonK9O_OUTPUTOutput format (default human)
--profile <name>, -pK9O_PROFILEProfile selector (default default)
—K9O_SERVICE_TOKENService 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>}, exit 0.
  • Failure: stderr receives the KError shape {"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:

CodeMeaning
0Success
1Generic / unexpected (rare catch-all)
2CLI usage error — bad flags / unknown command, before any API call
64Local config error (~/.k9o config or credentials malformed)
65Missing context (MISSING_PROJECT_CONTEXT / MISSING_ORG_CONTEXT)
66Auth — unauthenticated (401 family)
67Auth — forbidden (403 family)
68Not found (404 / *_NOT_FOUND)
69Conflict (409 / *_CONFLICT / *_ALREADY_*)
70Validation — parse-time (400 / malformed input)
71Validation — semantic (422)
72Capacity (429 / K9O_TIER_CAP_HIT)
73Service unreachable (5xx family)
74Token expired (410 / K9O_SESSION_EXPIRED)
75Lifecycle (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​