Reference

Agent mode

Hard guardrails for when an AI agent (Claude Code, Codex, Cursor background loops) runs rotate-cli unattended.

How to enable

$ export ROTATE_CLI_AGENT_MODE=1
$ rotate-cli apply ...

Or per-invocation:

$ ROTATE_CLI_AGENT_MODE=1 rotate-cli apply ...

What changes

Behavior	Normal	Agent mode
Output format	Pretty (TTY) or JSON (piped)	Always JSON envelope
Interactive prompts	Allowed via `@clack/prompts`	Refused, `unsupported` error
`--yes`	Optional	Required for any mutating action
`--reason <string>`	Optional	Required for any mutating action
`--max-rotations <n>`	Optional	Required for `apply` and `incident`
`--no-ownership-check`	Allowed	Forbidden
`--force-rotate-other`	Allowed	Forbidden
`--no-verify`	Allowed	Forbidden
`--manual-only`	Allowed	Forbidden, manual-assist adapters can't run in agent mode

The contract

Every command in agent mode emits exactly one JSON line to stdout with this shape:

{
  "version": "1",
  "command": "apply",
  "status": "success" | "partial" | "error",
  "data": { /* command-specific */ },
  "errors": [{ "code": "...", "message": "...", ... }],
  "next_actions": ["..."],
  "meta": { "duration_ms": 12000, "agent_mode": true, ... }
}

Exit codes

Code	Meaning
`0`	All rotations succeeded.
`1`	User error (missing flag, invalid selector, selector matched nothing).
`2`	Provider error (one or more rotations failed at the adapter).
`3`	In-grace warning (partial success; some consumers still need to sync).

Manual-assist adapters

Some providers (Firecrawl, Trigger.dev, Uploadthing) don't expose a public rotation API. Their adapters declare mode: "manual-assist" which requires an interactive terminal to paste the new value.

In agent mode, these adapters return a code: "unsupported" error immediately. The agent should surface the deferred rotations to the human user:

$ ROTATE_CLI_AGENT_MODE=1 rotate-cli apply --from-scan --auto-only --yes \
    --reason "..." --max-rotations 100

{
  "status": "success",
  "data": {
    "rotations": [ /* 58 auto */ ],
    "deferred": [
      { "secret_id": "firecrawl-visionboard", "adapter": "firecrawl" },
      ...
    ]
  },
  "next_actions": ["18 rotation(s) deferred: ..., run `rotate-cli apply --manual-only`"]
}

Audit log (recommended in agent mode)

$ ROTATE_CLI_AGENT_MODE=1 rotate-cli apply \
    --from-scan --yes \
    --reason "incident-response vercel-apr-2026" \
    --max-rotations 50 \
    --audit-log ./rotations.log

Every mutating step appends a structured JSON line. Use it to prove to your security team what happened, when, and why.