Getting started

Quickstart

From zero to one rotated secret in 5 minutes.

1 · Install and authenticate

$ git clone https://github.com/crafter-station/rotate-cli
$ cd rotate-cli && bun install && bun link
$ rotate-cli init          # creates ~/.config/rotate-cli/
$ rotate-cli auth login   # interactive picker

Auth is piggybacked from CLIs you already use. rotate-cli reads vercel login's auth file, gh auth token, and your .env.local for anything else.

2 · Scan

Enumerate every env var across every Vercel project your token can see. Produces a cached ~/.config/rotate-cli/last-scan.json.

$ rotate-cli scan

Scanning 1 scope(s)...
  ✓ crafter-station      318 projects · 462 secrets · 5.1s

Total: 318 projects · 462 mapped · 366 unmapped

Mapped by adapter:
    99  clerk
    80  upstash
   148  neon-connection
    29  vercel-ai-gateway
    24  openai
    ...

Next:
  → rotate-cli who --from-scan

3 · Who owns what

Before rotating anything, check which secrets are actually yours vs someone else's (teammates who share the Vercel team).

$ rotate-cli who --from-scan --tag non-sensitive

Preloading ownership indexes...
  ✓ clerk             · 865ms
  ✓ neon-connection   · 3.0s
  ✓ vercel-siblings   · 98/126 projects decrypted · 14.3s

Checking 451 secret(s)...
  ✓ clerk-elements-CLERK_SECRET_KEY    self       [clerk]
  ✗ resend-hack0-RESEND_API_KEY        other      [resend]
  ? openai-semantik-OPENAI_API_KEY     unknown    [openai]
  ...

Summary: 77 self (58 unique), 280 other (145 unique), 69 unknown, 22 no-check

58 unique even though 77 entries show as self. Duplicate values (for example the same CLERK_SECRET_KEY in dev, preview, and prod) get deduped automatically during apply. You rotate once, every copy updates.

4 · Apply (auto phase)

Rotate everything that can be automated, unattended. Manual-assist adapters (providers without a public rotation API like Firecrawl or Trigger.dev) get deferred to the next phase.

$ rotate-cli apply --from-scan --tag non-sensitive \
    --yes --confirm-bulk \
    --reason "vercel-apr-2026 breach"

Applying 58 rotation(s)...
  [1/58] ✓ clerk-elements         rotated · 2.1s
  [2/58] ✓ vercel-ai-gateway-lat…  rotated · 0.8s
  ...
  [58/58] ✓ resend-railly         rotated · 1.4s

✓ 58 rotations in grace (1h)
⚠ 18 rotation(s) deferred to manual phase:
  firecrawl (10), trigger-dev (5), uploadthing (3)
  → rotate-cli apply --from-scan --manual-only

5 · Apply (manual phase, optional)

Dashboard-only providers. rotate-cli opens the URL, you paste the new value, propagation + verify happens automatically. --manual-only requires an interactive TTY because agents can't run this phase.

$ rotate-cli apply --from-scan --manual-only \
    --reason "vercel-apr-2026 breach"

[1/18] firecrawl-visionboard
  → Open: https://firecrawl.dev/app/api-keys
  → Create a key named "rotate-cli 2026-04-22"
  → Paste the new FIRECRAWL_API_KEY here: ▁

6 · Revoke after grace

$ rotate-cli status              # see in-flight rotations
$ rotate-cli revoke <rotation-id> # close, old key invalidated

That's it. See the apply reference for all flags.