Authentication

The CLI supports two paths into your account:

• checkrd login — interactive browser flow (RFC 8628 device authorization grant). What you'll use on your laptop.
• CHECKRD_API_KEY — an env var pointing at an API key. What you'll use in CI.

Both paths converge on the same credential type — a ck_live_… API key — so anything that works in checkrd login also works in CHECKRD_API_KEY.

Interactive login

checkrd login

This:

1. Opens the Checkrd dashboard at /login/device with a one-time code.
2. You sign in via WorkOS (Google/Microsoft/SAML) on the dashboard.
3. The dashboard shows the code your terminal printed and asks you to confirm.
4. The CLI's polling loop picks up the approval and stores a long-lived API key in your OS keychain.

The whole thing takes about 15 seconds. The terminal prints the same code the dashboard shows so you can verify they match — this is RFC 8628's countermeasure against social-engineering attacks where someone tricks you into approving their CLI session (RFC 8628 §5.4).

Opening your browser. If it doesn't open, visit:
    https://app.checkrd.io/login/device

  Verify the code shown matches:
    → BCDF-GHJK

Waiting for approval...
✓ Logged in. Credential stored in the OS keychain (profile: default).
  Active workspace: 7c4f8a2e-1234-5678-9abc-def012345678
  Run `checkrd whoami` to confirm.

Headless / SSH

If you're SSH'd into a remote box or running inside a container without a browser:

checkrd login --browserless

The CLI prints the URL + code instead of trying to launch a browser. Open the URL on any machine you're signed into, type the code, and the CLI on the remote will pick up the approval.

Confirm

checkrd whoami
# alice@example.com
#   user:    11111111-2222-3333-4444-555555555555
#   org:     7c4f8a2e-1234-5678-9abc-def012345678
#   role:    owner
#   source:  OS keychain (profile: default)

API keys for CI

Browser flows don't work in GitHub Actions or any other unattended environment. Mint a key in the dashboard and pass it via env:

export CHECKRD_API_KEY="ck_live_…"
checkrd agents list

For local pinning (e.g. running ad-hoc commands against a sandbox org), pass --api-key directly:

checkrd --api-key "ck_test_…" agents list

Precedence

When multiple credentials are available, the CLI uses the first one it finds:

1. --api-key flag (per-command override)
2. CHECKRD_API_KEY env var (CI / scripts)
3. OS keychain entry for the active profile (checkrd login)

This precedence prevents shared CI runners from accidentally picking up a developer's interactive credentials.

Profiles (multi-account)

If you keep separate accounts for personal/work or sandbox/production, use profiles:

# One-time setup per profile
checkrd login --profile personal
checkrd login --profile work

# Use a specific profile per invocation
checkrd --profile work agents list
checkrd --profile personal agents list

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

Each profile gets its own keychain entry under the service checkrd:<profile>. Profiles are completely isolated — switching profiles never crosses credentials.

Logging out

checkrd logout
# Removes the keychain entry for the active profile.

To wipe a non-default profile, pass --profile:

checkrd logout --profile work

Troubleshooting

Generate a key locally

If you need an Ed25519 keypair for an agent's identity (separate from the dashboard auth above), use:

checkrd keygen

This is local-only — no network call. See keygen for details.