CLI

Design contract

The CLI is built for humans and agents. Every command supports --json, diagnostics go to stderr, and failures exit nonzero. Interactive terminals can choose projects and environments; non-interactive callers receive exact usage plus available keys.

Install and build

The package is private until its go-live npm publication. Build it from the workspace:

pnpm --dir packages/cli build
node packages/cli/dist/index.js --help

Onboard

Mint an editor or viewer token in the dashboard, then store it in OS secure storage:

krillswitch onboard \
  --base-url https://switch.openclaw.ai \
  --token ksat_...

Non-secret settings live in ~/.krillswitch.json. The token lives in macOS Keychain, Windows Credential Manager, or the Linux keyring.

Common commands

krillswitch projects list --json
krillswitch flags list -p clawhub -e production --json
krillswitch flags get souls -p clawhub -e production --json
krillswitch flags toggle souls -p clawhub -e production --off --json
krillswitch eval -p clawhub -e production -k user-123 --attr role=admin --json
krillswitch log tail --project clawhub --limit 75 --json

Use krillswitch completion install zsh, bash, or fish for persistent shell completion.

Configuration precedence

Token: command flag → KRILLSWITCH_TOKEN → secure-storage reference → legacy plaintext config.

An explicit --token or KRILLSWITCH_TOKEN skips secure storage entirely, so either override works even when the saved keychain is unavailable.

Base URL: command flag → KRILLSWITCH_URL → config file → http://localhost:8799.

API requests, including response-body reads, abort after 30 seconds. Set KRILLSWITCH_TIMEOUT_MS to a decimal integer from 1 to 2147483647 to use a different deadline in milliseconds, or 0 to disable it and retain the previous unlimited wait. Existing slow API or Cloudflare Access paths may need a higher value after upgrading. Invalid values are reported as configuration errors. A timeout does not mean a mutation was rolled back; check its result before retrying.

Changing the stored base URL without a new token clears the old token reference. This prevents a credential minted for one origin from being sent to another.

Cloudflare Access

The production admin host also requires a Cloudflare Access service token for non-browser automation:

export KRILLSWITCH_CF_ACCESS_CLIENT_ID=...
export KRILLSWITCH_CF_ACCESS_CLIENT_SECRET=...
krillswitch projects list --json

Those credentials satisfy only the edge gate. KrillSwitch still requires a valid editor or viewer access token.

Roles

Viewer tokens read flags, projects, environments, and the change log. Editor tokens can also create and change flags. Tokens cannot create projects, manage environments, rotate eval keys, grant roles, or mint admin authority.

See Access tokens and Auth and roles.