rotate-cli docs

Commands

status & revoke

rotate-cli status (alias ps)

List rotations currently in flight or in grace. Pass a rotation-id for details.

$ rotate-cli status

rotate-cli status

3 rotation(s) in flight

  ● rot_mo9kfx2a  in_grace  clerk-elements
      grace ends 2026-04-22 16:30 UTC
  ● rot_mo9kfy3b  in_grace  resend-railly
      grace ends 2026-04-22 16:30 UTC
  ● rot_mo9kfz4c  failed    supabase-kebo-api

Next:
  → rotate-cli revoke <rotation-id>  when consumers are synced

Inspect one rotation

$ rotate-cli status rot_mo9kfx2a --json

rotate-cli revoke <rotation-id>

Close a rotation: invalidate the old secret. Only works when the rotation is in grace and all consumers have verified sync.

FlagMeaning
--force-revokeRevoke even if some consumers are still unsynced (last resort).
--reason <string>Justification (required in agent mode).
--audit-log <path>Append to existing audit trail.
 
$ rotate-cli revoke rot_mo9kfx2a

rotate-cli revoke

  ✓ rot_mo9kfx2a closed
      old secret invalidated; grace period ended

Audit trail

Every create, propagate, trigger, verify, and revoke step appends a JSON line to the audit log: 

# ./audit.log
{"timestamp":"...","rotation_id":"rot_mo9kfx2a","secret_id":"clerk-elements","adapter":"clerk","status":"in_grace","agent_mode":false,...}
{"timestamp":"...","rotation_id":"rot_mo9kfx2a","status":"revoked",...}