checkrd

Configuration

Output formats, profiles, env vars, and the precedence rules between flags / env / keychain.

Configuration

The CLI is driven by three things: command-line flags, environment variables, and the OS keychain. Flags always win.

Output formats

Set with --output (or -o). Two values:

human (default)

Rich, color-coded output. Tables for list commands, formatted blocks for single objects, dimmed status hints to stderr.

bash
checkrd agents list
# ┌──────────────┬───────────────┬─────────┬──────────────────────┐
# │ ID           │ NAME          │ STATUS  │ CREATED              │
# ├──────────────┼───────────────┼─────────┼──────────────────────┤
# │ abc-123-…    │ sales-bot     │ active  │ 2026-01-15T10:00:00Z │
# │ def-456-…    │ support-bot   │ killed  │ 2026-02-01T09:30:00Z │
# └──────────────┴───────────────┴─────────┴──────────────────────┘

Color is enabled when stdout is a TTY and NO_COLOR is unset. Pipes and redirects automatically render uncolored.

json

JSON pretty-printed for list/get commands. NDJSON (newline-delimited, one object per line) for streaming commands like events tail.

bash
checkrd agents list --output json | jq '.data[] | select(.kill_switch_active)'

--no-color

Force-disable color even on a TTY. Honors the NO_COLOR env var per spec — any non-empty value disables color across the entire CLI.

bash
NO_COLOR=1 checkrd agents list

--query (JMESPath projection)

Apply a JMESPath expression to JSON output before printing — same UX as aws --query. Compile-checked at parse time so a bad expression fails before any HTTP request runs.

bash
# Just the names from a list of agents
checkrd -o json --query '[*].name' agents list

# Filter to active agents
checkrd -o json --query "[?active==\`true\`]" agents list

# Per-event filter on the live stream — drops events that don't match
checkrd -o json --query "[?event=='kill_switch']" events tail --agent sales-bot

--query requires --output json. Combining with --output human is rejected because the human renderer is a rich table built per command and the projection has no well-defined semantics there.

For streaming commands (events tail), the expression is applied per emitted record. Events whose projection is empty (null, [], {}, "") are dropped from the stream.

Environment variables

VariableWhat
CHECKRD_API_KEYAPI key. Used when no --api-key flag and no profile in keychain.
CHECKRD_PROFILEDefault profile (default: default). Override with --profile.
CHECKRD_BASE_URLOverride the default https://api.checkrd.io. Self-hosted / local.
CHECKRD_LOGTracing filter for the CLI's own logs. Default: warn.
NO_COLORDisable color output. Per no-color.org.

Example: pin a CI run to a specific workspace + base URL without flags:

yaml
- run: |
    export CHECKRD_API_KEY=${{ secrets.CHECKRD_KEY }}
    export CHECKRD_BASE_URL=https://api.checkrd.io
    checkrd policies publish sales-bot ./policy.yaml

Credential precedence

Three slots, checked in order. First non-empty wins:

  1. --api-key flag — per-invocation override. Highest priority. Useful for ad-hoc commands against a specific account without touching env / keychain.
  2. CHECKRD_API_KEY env — for CI / scripts.
  3. OS keychain — what checkrd login writes. Looked up under checkrd:<profile>.

If all three are empty, every command other than login / signup / keygen / --help exits with code 77 and a message pointing at checkrd login.

The flag-then-env-then-keychain order means CI runners that happen to have a developer's interactive credential cached in the keychain can still cleanly use CHECKRD_API_KEY — the env var wins.

Profiles

Profiles let you keep multiple credentials side-by-side. Each profile is a separate keychain entry.

bash
# Set up profiles
checkrd login --profile personal
checkrd login --profile sandbox
checkrd login --profile production

# Use them
checkrd --profile sandbox agents list
checkrd --profile production agents list

# Or set a default for the shell session
export CHECKRD_PROFILE=sandbox
checkrd agents list   # uses sandbox

checkrd whoami always shows which profile + source resolved.

Self-hosted / local development

Override the API endpoint with --base-url or CHECKRD_BASE_URL:

bash
# Hit your local docker-compose stack
checkrd --base-url http://localhost:8080 agents list

# Permanently point a profile at a self-hosted control plane
export CHECKRD_BASE_URL=https://checkrd.internal.example.com
checkrd login --profile internal

The profile remembers its base URL via the keychain entry; subsequent commands honor it without re-passing the flag.

Update

If you installed via Homebrew, npm, or the shell installer, the binary self-detects the install method and routes upgrades through the right channel:

bash
checkrd upgrade
# → Detected install via Homebrew. Running: brew upgrade checkrd

This is powered by axoupdater — a brew-installed binary upgrades via brew, an npm-installed one via npm, etc. No accidental cross-channel installs.

Shell completions

See Install → Shell completions for the per-shell wiring snippets. The completions are generated dynamically by clap, so they always reflect whatever version of the CLI you have installed — no separate update path.

CommandsDev mode