Commands

The CLI follows the noun-verb convention used by gh, stripe, and vault. Every command accepts the same global flags:

Run checkrd <command> --help for details on any subcommand.

Authentication

checkrd login [--browserless] [--signup]

Interactive browser login via RFC 8628 device flow. Stores the credential in the OS keychain. See Authentication.

checkrd login
checkrd login --browserless          # SSH / headless
checkrd login --signup               # open signup instead

checkrd logout

Remove the stored credential for the active profile. Idempotent.

checkrd whoami

Show the currently authenticated identity, the active workspace, and which credential source resolved.

checkrd whoami
checkrd --profile work whoami

checkrd auth set-api-key <KEY>

Manually store an API key without going through the browser flow. Useful when you've already minted a key in the dashboard. The key shape is validated before write.

checkrd auth set-api-key ck_live_…

checkrd auth clear

Remove the stored credential. Equivalent to logout.

checkrd auth switch [--profile NAME]

Switch the persistent active profile. The choice is written to state.toml so subsequent commands honor it without --profile or CHECKRD_PROFILE.

# Pick interactively from authenticated profiles
checkrd auth switch

# Direct switch
checkrd auth switch --profile production

With exactly two known profiles, runs silently without prompting (matches gh auth switch's muscle-memory pattern for dev/prod toggles).

checkrd auth token [--profile NAME]

Print the stored credential to stdout — single line, no decoration. For piping into other tools:

curl -H "Authorization: Bearer $(checkrd auth token)" https://api.checkrd.io/v1/agents

Exits with code 77 (EX_NOPERM) if no credential is stored.

checkrd signup

Open the signup page in your browser. Account creation deliberately doesn't happen from the CLI — billing details and email verification require a browser anyway.

Agents

checkrd agents list [--limit N]

List agents in the active workspace.

checkrd agents list
checkrd agents list --limit 500 --output json | jq '.data[].name'

checkrd agents get <AGENT_ID>

Show one agent.

checkrd agents create --name <NAME> [--description <TEXT>]

Create a new agent. Returns the agent's id + public-key registration prompt.

checkrd agents kill <AGENT_ID>

Trip the kill switch. Every outbound call from the agent's SDK starts denying within ~1 second (SSE control-stream notification).

checkrd agents kill sales-bot
# ✓ Agent sales-bot killed

checkrd agents unkill <AGENT_ID>

Lift the kill switch.

Policies

Per-agent policies. For workspace-wide org policies, see org.

checkrd policies list <AGENT>

List all policy versions for an agent. Active version is flagged.

checkrd policies show <AGENT> [--version N]

Show one policy version. Defaults to the active version.

checkrd policies publish <AGENT> <FILE> [--message TEXT]

Publish a new policy version from a YAML/JSON file on disk.

checkrd policies publish sales-bot ./policy.yaml --message "tighten allowlist"

checkrd policies diff <AGENT> <FILE>

Terraform-plan style diff of a local policy file vs. the deployed version. Shows additions, removals, and modifications before you publish.

checkrd policies test <AGENT> --request <FILE> [--version N]

Replay a sample request against a policy and show the decision (allow / deny + matched rule + reason). Use this to test policy changes before publishing.

checkrd policies test sales-bot --request ./request.json

Keys

checkrd keys list

List API keys for the active workspace. Secrets are never shown — only id + prefix + scope + status.

checkrd keys create --name <NAME> [--scope <SCOPE>]

Mint a new API key. The full secret is printed exactly once — store it immediately.

checkrd keys create --name "ci-bot" --scope write
# key 'ci-bot'
#   id:      00000000-0000-0000-0000-000000000099
#   prefix:  ck_live_abcdef
#   scope:   write
#
#   ⚠  SECRET (shown once — store it now):
#   ck_live_abcdef0123456789…

checkrd keys revoke <KEY_ID>

Revoke a key by id. Existing usage with this key fails immediately. Soft delete — the row stays for audit.

Alerts

checkrd alerts list

List alert rules in the active workspace.

checkrd alerts history <ALERT_ID>

Print the state-transition timeline for an alert.

checkrd alerts toggle <ALERT_ID>

Enable or disable an alert rule.

checkrd alerts mute <ALERT_ID> --until <DURATION>

Snooze for a duration (e.g. 2h, 1d, 30m). The rule keeps evaluating but no notifications fire.

checkrd alerts unmute <ALERT_ID>

Lift any active snooze.

Events

checkrd events list [--agent ID] [--limit N]

Recent events (paginated). --agent filters to one agent.

checkrd events tail --agent <AGENT_ID>

Live-stream events as they happen via SSE. Reconnects with exponential backoff if the stream drops. Honors Ctrl-C cleanly.

# Human mode: timestamped one-liners
checkrd events tail --agent sales-bot

# JSON mode: NDJSON for pipe-into-jq
checkrd events tail --agent sales-bot --output json | jq 'select(.event == "kill_switch")'

Audit

checkrd audit list [--actor X] [--action Y] [--resource Z] [--limit N]

Audit-log entries. Filter by actor (user id or API key prefix), action verb, or resource type.

# Every policy publish in this workspace this week:
checkrd audit list --action policy.publish

# What did api-key ck_live_abc do recently?
checkrd audit list --actor ck_live_abc

Stats

checkrd stats summary

Print the at-a-glance counters from the dashboard home (events / denies / active agents). JSON output.

checkrd stats timeseries <METRIC> [--window DURATION]

Time-series data for one metric (e.g. events, denies, latency_p95). Output is JSON for piping.

checkrd stats timeseries events --window 24h | jq '.points'

Templates

checkrd templates list

List the built-in policy templates with their parameter requirements (required params marked with *).

checkrd templates render <TEMPLATE> --param k=v [--out FILE]

Render a template to YAML (stdout, or --out file). Pass parameters with --param key=value (repeatable).

checkrd templates render api-allowlist \
  --param domain=api.salesforce.com \
  --param method=GET \
  --out ./policy.yaml

Org (workspace administration)

checkrd org list

List workspaces you belong to with your role in each.

checkrd org get <ORG_ID>

Show one workspace.

checkrd org create --name <NAME>

Create a new workspace. Subject to per-user free-tier cap (5 free workspaces; paid don't count).

checkrd org delete <ORG_ID>

Delete a workspace. Owner role only; you cannot delete your last owned workspace.

checkrd org members <ORG_ID>

List members of a workspace.

checkrd org invite <ORG_ID> --email <EMAIL> [--role <ROLE>]

Invite a user. Roles: owner, admin, member, viewer. Defaults to member.

Local helpers

checkrd keygen [--private-only | --public-only]

Generate a local Ed25519 keypair (no network). Use this when you want an agent identity that lives outside the SDK's auto-generated dev key.

checkrd keygen
# # Generated by `checkrd keygen` — store this securely.
# # public_key:  3a4f2c…
# # instance_id: 3a4f2c8b
# export CHECKRD_AGENT_KEY=base64-encoded-private-key

# Pipe just the public key into a registration command:
checkrd keygen --public-only | xargs -I{} checkrd agents register-key sales-bot --public-key {}

checkrd completions <SHELL>

Print shell completions to stdout. See Install for wiring instructions.

checkrd telemetry status

Print the CLI's telemetry posture. Always: off, permanent. The CLI does not collect telemetry; this command exists so security teams can grep for the same answer in vendor questionnaires whether they look for --no-telemetry, CHECKRD_TELEMETRY, DO_NOT_TRACK, or analytics. See Telemetry for the long-form policy.

checkrd debug bundle [--out PATH]

Generate a redacted JSON support bundle to attach to a GitHub issue. Includes CLI version, OS + arch, target triple, active profile name (NEVER the credential), env-var presence (booleans only, never values). Nothing leaves your machine until you decide to share the file.

checkrd debug bundle --out ./bundle.json
# ✓ Wrote support bundle to ./bundle.json.
#   → Review the JSON before sharing — nothing has been sent.

checkrd docs [TOPIC]

Open the docs in your browser. With no topic, opens the CLI docs landing page; with a topic, deep-links.

checkrd docs                # opens https://checkrd.io/docs/cli
checkrd docs install        # opens https://checkrd.io/docs/cli/install
checkrd docs authentication # etc.

checkrd dev [--port 8080] [--policy PATH] [--upstream URL]

Local HTTP proxy that runs the WASM policy engine natively — iterate on checkrd.yaml against real traffic without deploying anything. Same engine that runs in production via the SDK wrappers; no Docker, no setup, single static binary.

# Forward-proxy on :8080, watching ./checkrd.yaml for changes
checkrd dev

# Reverse-proxy a single upstream
checkrd dev --upstream https://api.openai.com --port 9090

# Disable hot-reload for one-shot debugging
checkrd dev --watch=false --policy ./test.yaml

Each request prints a colored allow/deny line with the matched rule. Hot-reloads the policy file on save. See Dev mode for the full guide.

checkrd extension list

List PATH-discovered plugins. Any executable on PATH named checkrd-foo becomes the subcommand checkrd foo automatically — same convention git, kubectl, and gh use.

# Drop a script in PATH
echo '#!/bin/sh
echo hello from plugin' > /usr/local/bin/checkrd-hello
chmod +x /usr/local/bin/checkrd-hello

checkrd hello                  # invokes the plugin
checkrd extension list         # shows it as discovered

Built-in commands always win — a plugin named checkrd-login is silently shadowed (visible in extension list with the shadowed status so you know to rename).

When the parent CLI invokes a plugin, these env vars are set so the plugin doesn't have to re-implement profile / base-URL resolution:

• CHECKRD_PROFILE — active profile name
• CHECKRD_BASE_URL — resolved control-plane URL
• CHECKRD_CONFIG_DIR — config dir path
• CHECKRD_PLUGIN_INVOKED=1 — sentinel so plugins can detect they're being invoked as subcommands rather than directly

Exit codes

The CLI returns BSD sysexits.h-style codes so scripts can branch:

Use them in shell scripts:

checkrd policies publish sales-bot policy.yaml || retry-on 75