Operator CLI reference

Install and authenticate

The operator command is kastra, distinct from the endpoint tool kastra-edge.

brew install kastra-labs/tap/kastra
kastra auth login
kastra auth status

Homebrew supports macOS and Linux operators. Windows uses the Kastra Scoop bucket followed by scoop install kastra/kastra. Platform-specific archives are available from the public release repository.

Command groups

Group	Common operations
policy	list, get, validate, add, apply, update, activate, deactivate, rollback, promote, export, simulate
evidence	list, get, verify, export
agent	list, get, create, update, delete, scope
env	list, get, create, delete
api-key	list, create, revoke
checkpoint	list, approve, deny, cancel
incident	list, kill-switch, resolve
stats	Governance activity summary

Use command help for required IDs and flags. Policy writes require an administrator, and some incident operations require OWNER. Destructive or production changes can prompt for confirmation.

Scope and machine output

Use --output json-v1 on supported operations for a versioned { "schema_version": 1, "data": ... } envelope. Lists use arrays, including []; pagination and metadata are preserved when supplied. Unsupported commands reject machine output before performing work. Supported writes in machine mode require --yes.

--env accepts an environment name or an authorized UUID only on commands with environment scope. Workspace-wide commands such as policy list, env list, agent list, api-key list and stats reject it. .kastra file metadata uses environment names and takes precedence over the flag. --org selects a workspace UUID; --api is a deployment root, without an added /api or /v1 endpoint suffix.

CI authentication

An administrator can mint an operator token using kastra auth create-ci-token with a name, requested role, and expiry. Store the returned secret in the CI system and supply it as KASTRA_TOKEN. The role cannot exceed the issuer’s authority. Revoke it when no longer needed.

Start CI with read-only validation. Applying or activating production policy is a separate authorized operation. Policy-as-code guide.