CLI overview

Manage agents, policies, keys, and live decisions from the terminal. The Checkrd CLI is the same surface as the dashboard — scriptable.

CLI overview

checkrd is a single static binary for managing the Checkrd control plane from the terminal. Anything you can do in the dashboard you can do with checkrd: create agents, publish policies, rotate API keys, flip the kill switch, tail decisions live.

The CLI talks to the same /v1/* REST API as the dashboard, with the same RBAC, the same audit log, and the same idempotency guarantees.

Install

bash

brew install checkrd-io/homebrew-tap/checkrd-cli
# or
curl -fsSL https://checkrd.io/install.sh | sh

See Install for the full matrix (Homebrew, shell installer, manual download), checksum verification, and shell completions.

First run

bash

checkrd login                          # browser-based auth
checkrd agents list                    # see your agents
checkrd policies publish my-agent.yaml # ship a policy
checkrd events tail --agent my-agent   # live decisions

checkrd login opens your browser, signs you in via WorkOS, and stores a long-lived API key in your OS keychain. Set CHECKRD_API_KEY in CI to skip the browser flow — the CLI checks the environment before the keychain.

Common commands

Command	What it does
`checkrd agents`	Create, list, get, kill-switch agents
`checkrd policies`	Validate, publish, diff, test, analyze policies
`checkrd keys`	Create, list, revoke API keys
`checkrd events`	Tail or query the decision stream
`checkrd alerts`	Manage alert rules
`checkrd audit-log`	Query the org audit log
`checkrd orgs`	Switch between organizations
`checkrd login` / `logout`	Manage stored credentials
`checkrd debug`	Collect a support bundle
`checkrd docs`	Open these docs in your browser

Every command supports --help. The full reference is in Commands.

Configuration

The CLI reads configuration in this order (later wins):

Built-in defaults (https://api.checkrd.io, no agent).
~/.checkrd/config.toml.
Environment variables (CHECKRD_API_KEY, CHECKRD_BASE_URL, CHECKRD_AGENT_ID, CHECKRD_ORG_ID).
Command-line flags.

See Configuration for the complete schema.

Output formats

Default output is human-formatted (tables, colors, ANSI). For scripts, pass --output json:

bash

checkrd agents list --output json | jq '.[] | select(.status == "active")'

JSON output is stable: fields are documented, deprecations follow the same SemVer policy as the SDK. Use it freely in CI.

Exit codes

The CLI follows BSD sysexits.h conventions so scripts can react without parsing stderr:

Code	Meaning
`0`	Success
`1`	Generic API error (4xx that's not auth)
`64`	Bad input (malformed flag, invalid JSON)
`70`	Internal CLI error (file an issue)
`75`	Temporary failure — safe to retry (network, 5xx)
`77`	Authentication problem

Example: a CI job that retries on transient failures only:

bash

checkrd policies publish sales-agent ./policy.yaml || (
  code=$?
  if [ "$code" = "75" ]; then
    sleep 30 && checkrd policies publish sales-agent ./policy.yaml
  else
    exit $code
  fi
)

Telemetry

The CLI sends anonymous usage telemetry by default (command names, exit codes, durations — no arguments, no payloads). Disable per-run with CHECKRD_CLI_TELEMETRY=off or persistently with checkrd telemetry off. See Telemetry for the exact schema and the verification recipe.

Where to next

Install — set up the binary, verify it
Authentication — login flow, CI keys, keychain
Commands — every subcommand and flag
Configuration — config file format and env vars
Recipes — copy-paste workflows (CI publish, fleet rotation, on-call drills)
Dev mode — run a local control plane for testing

Cloudflare Workers Install