kici-admin CLI reference

The kici-admin CLI manages the KiCI orchestrator: configuration, secrets, tokens, sources, database migrations, diagnostics, clustering, and service lifecycle. Most commands reach the orchestrator over its admin HTTP API using Bearer token authentication.

Some command groups deliberately bypass that API, because they must work while the orchestrator is down (or before it exists):

Direct database (--database-url, or KICI_DATABASE_URL): check-run, cluster, signing-key, dashboard-encryption-key, remote-source, and peer prune-credentials / reset-raft-state. host and the other peer verbs (create-token, list, revoke, revoke-all) also go straight to the database, but they read KICI_DATABASE_URL only. They carry no --database-url flag. Several API-backed commands offer a direct-DB mode through the same flag — each one says so in its guide entry.
Local host only (no orchestrator, no database): firecracker, scaler reap-orphans, inspect-bundle, and the agent / orchestrator service-lifecycle verbs (install, uninstall, start, stop, restart, status, logs, upgrade, plus agent package; orchestrator drain / resume are API-backed).
Own transport: join connects straight to the Platform relay or a peer orchestrator.

Installation

The kici-admin binary is provided by the kici-admin npm package, which re-exports the CLI from @kici-dev/orchestrator:

npm install -g kici-admin

The same package also installs a second binary, kici-agent, which runs the KiCI agent. That is what puts an agent on PATH for a bare-metal scaler’s binaryPath: — see the bare-metal quickstart.

For standalone packages that need no npm, see the Packaging guide.

Authentication

All API-backed commands require a Bearer token. Provide it via:

Environment variable (recommended): export KICI_ADMIN_TOKEN=<token>
CLI flag: --token <token> or -t <token>

The token is validated against the admin_tokens table in the orchestrator database. Tokens are stored as SHA-256 hashes and never persisted in plaintext.

Bootstrap token

On first startup, the orchestrator generates a bootstrap token with owner role and prints it to the logs:

KICI Admin Token: <token-value>

Save this token immediately — it is only shown once. To use a fixed token for automation, set KICI_BOOTSTRAP_ADMIN_TOKEN before starting the orchestrator:

export KICI_BOOTSTRAP_ADMIN_TOKEN=my-fixed-admin-token

With KICI_BOOTSTRAP_ADMIN_TOKEN set, every startup sets the bootstrap token to that value with the owner role, so a new value replaces the old token. Without it, the orchestrator generates a bootstrap token only when no unrevoked admin token exists.

Creating additional tokens

Use kici-admin token create to issue tokens with specific roles:

kici-admin token create ci-operator --role admin
kici-admin token create compliance-bot --role auditor

Global options

These options apply to every command:

Option	Environment variable	Default	Description
`--url <url>`, `-u`	`KICI_ADMIN_URL`	`http://localhost:4000`	Orchestrator HTTP URL
`--token <token>`, `-t`	`KICI_ADMIN_TOKEN`	(required)	Admin API Bearer token
`--version`, `-V`, `--cli-version`			Show CLI version

Running --help on any command works without a token. The help names the environment variable of an option, as in (env: KICI_ADMIN_TOKEN), and never prints its value, so you can share help output safely.

kici-admin --version prints the CLI version only when --version comes before the command name. After a command name, --version belongs to that command: kici-admin orchestrator upgrade --version 0.3.0 sets the target version of the upgrade. -V and --cli-version print the CLI version in any position.

Some commands declare their own option under a global flag: --url on orchestrator upgrade and agent upgrade, and --token on join, agent install, backend add and backend test. After the name of such a command, the flag sets the option of that command. For example, kici-admin orchestrator upgrade --url <archive-url> downloads the archive from that URL. To also give the global option to such a command, put --url or --token before the command name, use -u or -t, or set KICI_ADMIN_URL or KICI_ADMIN_TOKEN. After any other command, --url and --token set the global options.

Output streams

The kici-admin binary routes every diagnostic log line to stderr. Only command output — a table, or the payload of a --json / --format json run — goes to stdout. So you can pipe stdout straight into a parser:

kici-admin runs list --json | jq -r '.runs[].runId'

The CLI sets KICI_LOG_STDERR=1 for you when it starts. Set it yourself only if you invoke the orchestrator CLI module through some other entry point and want the same split.

Confirmation prompts

Some commands that delete or replace state ask for confirmation on stderr before they act. Answer y or yes to continue. Any other answer cancels the command. Pass --yes to skip the prompt, for example in a script. If stdin closes before an answer arrives, the command stops with a non-zero exit and changes nothing.

RBAC roles

Tokens are assigned one of three roles. The role determines which admin API operations are permitted:

Permission	owner	admin	auditor
context.create	yes	yes
context.read	yes	yes	yes
context.update	yes	yes
context.delete	yes	yes
secret.read	yes	yes
secret.write	yes	yes
secret.delete	yes	yes
secret.reveal	yes	yes
audit.read	yes	yes	yes
run.read	yes	yes	yes
run.cancel	yes	yes
event_log.read	yes	yes	yes
event_log.read_payload	yes	yes
access_log.read	yes	yes	yes
scheduled_job.trigger	yes	yes
event_dlq.read	yes	yes	yes
event_dlq.manage	yes	yes
attestation.retry	yes	yes
orchestrator.drain	yes	yes
ci_trust.read	yes	yes
ci_trust.admin	yes	yes
scaler.read	yes	yes	yes
scaler.manage	yes	yes
peer.manage	yes	yes
test_run.trigger	yes	yes
test_run.read	yes	yes	yes
token.manage	yes
key.rotate	yes

secret.reveal is the additional gate for kici-admin runs secret-outputs --reveal: decrypting stored secret-output values and returning plaintext is strictly narrower than generic “read a secret”, so owner + admin roles carry it explicitly and auditor tokens are rejected with 403.

owner — full access. Use for bootstrap and token management.
admin — day-to-day operations (secrets, sources, config). Cannot manage tokens or rotate keys.
auditor — read-only access to contexts, audit logs, run status, the event log (metadata only), the access log, the event dead-letter queue, internal events (event list / event show, which need event_dlq.read), and a node’s live Firecracker VMs (scaler orphans, which needs scaler.read), all without payload bodies. Cannot read secret values, event-log payloads, or mutate anything.

Note: These roles govern the orchestrator admin API only. They are entirely separate from the SaaS dashboard RBAC system (org member roles, custom roles, permission matrices) which is managed through the dashboard UI and applies to OIDC-authenticated users.

Command reference

The full command reference is split by area:

Configuration & database — config, db
Sources — source, remote-source
Secrets, tokens & context — secret, variable, backend, audit, api-key, token, rotate-key, context
Agents, peers & hosts — agent, peer, join, host
Runs, execution & events — runs, execution, check-run, queue, registration, workflow, event, event-dlq
Cluster & infrastructure — orchestrator, cluster, cluster-name, cluster-settings, scaler, firecracker
Org settings — org, org-settings, trust-policy, held-run
Inspection & recovery — cold-store, attestations, signing-key, dashboard-encryption-key, access-log, event-log, diagnose, debug-bundle, inspect-bundle

Each area page carries a ## Guide section (per-namespace concepts and worked examples) and a ## Reference section (the always-current generated signature list for that area’s commands).

Environment variables summary

Variable	Scope	Description
`KICI_ADMIN_URL`	CLI	Orchestrator URL (default: `http://localhost:4000`)
`KICI_ADMIN_TOKEN`	CLI	Admin API Bearer token (required)
`KICI_DATABASE_URL`	CLI	Postgres URL for direct-DB commands (or `--database-url`)
`KICI_BOOTSTRAP_ADMIN_TOKEN`	Orchestrator	Fixed bootstrap token (idempotent)
`KICI_SECRET_KEY`	Orchestrator	64-char hex AES-256 master key
`KICI_SECRET_KEY_FILE`	Orchestrator	Path to master key file
`KICI_SECRET_KEY_OLD`	Orchestrator	Previous key for dual-key rotation
`KICI_AUTO_MIGRATE`	Orchestrator	Set `false` to disable auto-migration
`KICI_AGENT_TOKEN`	Agent	Agent authentication token
`KICI_BACKEND_VAULT_URL`	CLI	Vault/OpenBao URL for backend commands
`KICI_BACKEND_ROLE_ID`	CLI	Vault AppRole role ID for backend commands
`KICI_BACKEND_SECRET_ID`	CLI	Vault AppRole secret ID for backend commands
`KICI_BACKEND_TOKEN`	CLI	Vault token for backend commands
`KICI_BACKEND_PG_URL`	CLI	PG connection string for backend commands