kici-admin CLI reference

The kici-admin CLI manages the KiCI orchestrator: configuration, secrets, tokens, sources, database migrations, diagnostics, clustering, and service lifecycle. It communicates with the orchestrator’s admin HTTP API using Bearer token authentication.

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

For standalone (single-executable) deployments, see 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

The bootstrap token creation is idempotent: if one already exists, it is reused.

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:8080`	Orchestrator HTTP URL
`--token <token>`, `-t`	`KICI_ADMIN_TOKEN`	(required)	Admin API Bearer token
`-V`, `--cli-version`			Show CLI version

Running --help on any command works without a token.

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
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, and run status. Cannot read secret values.

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-settings
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:8080`)
`KICI_ADMIN_TOKEN`	CLI	Admin API Bearer token (required)
`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