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.