# Operator CLI reference

Manage policies, evidence, environments, keys, and checkpoints from a terminal or CI.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/reference/cli

## Install and authenticate

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

```sh
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](https://github.com/kastra-labs/kastra-edge-releases/releases).

## Command groups

| Group | Common operations |
| --- | --- |
| `policy` | list, get, validate, add, apply, activate, deactivate, rollback, promote, simulate |
| `evidence` | list, verify |
| `agent` | list, get, create, update, delete, scope |
| `env` | list, 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. Commands such as `policy list`, `env list`, `agent list`, `api-key list`, `checkpoint list`, `evidence verify` 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](https://docs.kastra.ai/policies/policy-as-code).

## Policy commands

Arguments in uppercase below are values you supply. Policy IDs come from `kastra policy list`; environment names come from `kastra env list`.

| Command | Arguments and flags | Result |
| --- | --- | --- |
| `kastra init [FILE]` | Optional path; `--force` overwrites that file | Creates a local policy starter |
| `kastra policy validate FILE` | `.kastra` file | Calls server schema validation and linting; requires login |
| `kastra policy add FILE` | Optional `--activate` | Creates a policy; activation is explicit |
| `kastra policy apply FILE` | Optional `--note TEXT` | Creates or updates by name and environment |
| `kastra policy get POLICY_ID` | Policy UUID | Reads the policy |
| `kastra policy activate POLICY_ID` | Required `--revision N` | Activates the selected revision |
| `kastra policy deactivate POLICY_ID` | Policy UUID | Removes its active revision from enforcement |
| `kastra policy rollback POLICY_ID` | Required `--revision N` | Rolls back to a reviewed revision |
| `kastra policy promote POLICY_ID` | Required `--to ENV`; optional `--activate`, `--note TEXT` | Copies to the target environment |
| `kastra policy simulate FILE` | Required `--against-traffic`; optional `--from`, `--to`, `--limit` | Replays stored decisions; does not activate the candidate |
| `kastra policy delete POLICY_ID` | Policy UUID | Deletes the selected policy |

Replay dates accept RFC3339 or `YYYY-MM-DD`. The replay limit defaults to 2,000 and is capped at 10,000; inspect the result's truncation flag. [Policy syntax and operators](https://docs.kastra.ai/reference/policy-attributes).

## Operational commands

| Task | Command and flags |
| --- | --- |
| Read decisions | `kastra evidence list --env ENV --limit 20` |
| Verify the decision chain | `kastra evidence verify` |
| Create an environment | `kastra env create NAME --display "Display name"`; optional `--prod`, `--retention-days N` |
| Delete an environment | `kastra env delete NAME_OR_ID` |
| Create a runtime key | `kastra api-key create NAME --env ENV` |
| Revoke a runtime key | `kastra api-key revoke KEY_ID` |
| Inspect an agent | `kastra agent get SLUG` |
| Restrict an agent's tools | `kastra agent scope SLUG --deny-tool TOOL_A,TOOL_B`; alternatively `--allow-tool` or `--clear` |
| Find pending approvals | `kastra checkpoint list --status pending` |
| Resolve an approval | `kastra checkpoint approve CHECKPOINT_ID --note "Reviewed"`; use `deny` to refuse or `cancel` to withdraw |
| Include resolved incidents | `kastra incident list --env ENV --all` |
| Activate a kill switch | `kastra incident kill-switch --scope ENVIRONMENT --env ENV --reason "Reason"` (OWNER) |
| Resolve an incident | `kastra incident resolve INCIDENT_ID` (OWNER) |
| Workspace summary | `kastra stats` |

Tool-scope changes affect the active policy immediately. An allow-list denies tools outside that list. Review [agent identities and scope](https://docs.kastra.ai/admin/agents) before changing an existing agent. Environment deletion and key revocation affect every integration using them.

## Global flags and exit codes

| Flag | Meaning |
| --- | --- |
| `--env NAME_OR_ID` | Environment on commands that support it; file metadata takes precedence |
| `--org WORKSPACE_ID` | Authorized workspace UUID |
| `--api URL` | Deployment root, such as `https://api.kastra.ai` |
| `--output json-v1` | Machine-readable output on supported commands |
| `--yes`, `-y` | Answer confirmation prompts; does not bypass server authorization |
| `--quiet` | Suppress normal plaintext output |
| `--help` | Show the selected command's arguments and flags |

Exit status is `0` for success, `1` for command failure, and `2` for invalid usage. Check it before processing output.

Machine output is supported for `auth status`, `auth create-ci-token`, `policy list`, `policy get`, `policy promote`, `policy simulate`, `env list`, `env create`, `api-key list`, `api-key create`, `agent list`, `agent get`, `evidence list`, `evidence verify`, `incident list`, `checkpoint list`, and `stats`. Other operations reject the flag.

```sh
kastra auth create-ci-token --name docs-ci --role admin --expires 720h
kastra policy list --output json-v1
kastra evidence list --env dev --limit 20 --output json-v1
```

The token-creation command prints a secret once. Keep it out of logs and source control. Supply that secret through `KASTRA_TOKEN` in CI; runtime API keys serve a different purpose.