Agent mode

When an AI coding agent runs permdock, the CLI prints the cli-result-v1 envelope instead of text, never prompts, and stops with exit 3 when the run needs something only a person can give: input, a login, or consent.

UsageCopy Anchor Link

permdock doctor                     # JSON envelope when an agent runs it
permdock doctor --format text       # text even in agent mode
permdock doctor --agent no          # turn agent mode off for this run
PERMDOCK_AGENT=1 permdock collect   # turn it on, as in a test harness
permdock codemod 0.5 --confirm 6f3a9c0e41b2   # run again after the person agreed

DetectionCopy Anchor Link

--agent auto|yes|no decides, then PERMDOCK_AGENT (1, yes, true, 0, no, false, auto), then detection. Detection reads the same variables as @vercel/detect-agent 1.2.5, in its order, and a test asserts both agree:

run() from permdock/cli reads only the env its caller passes, so a program that calls it is not switched to JSON by the agent that runs the program.

What changesCopy Anchor Link

• Output. stdout carries the envelope; --format text or --no-json brings text back. Progress and logs go to stderr without spinners.
• Prompts. None. A command that would ask takes the answer its flags give, or stops with missing_input.
• Exit 3. status is action_required and error.code is missing_input, auth_required or consent_required. next lists the commands that continue the run, each with the condition under which to run it.
• Completion. permdock completion and the hidden __complete print text for the shell even in agent mode.

ConsentCopy Anchor Link

An agent may not start three kinds of run without the person's go-ahead:

The first run exits 3 with consent_required, the reasons and a token. The agent shows the person what will happen, and after they agree runs the command in next, which is the same command line with --confirm <token>. A run with --dry-run or --check writes nothing and needs no consent.

The token is the first 12 hex characters of a SHA-256 of the working directory and the command line, --confirm left out. A token for one command line does not confirm another, and --yes does not stand in for it. A secret flag such as --db-url counts by its stdin form (--db-url-stdin), so the token never depends on the secret, and the line in next never prints it.

auth_required follows the same shape: a 401 or 403 from the Cloud exits 3 with permdock login in next.

WhyCopy Anchor Link

• JSON by default for agents. An agent parses text by guessing; one envelope with a stable code per failure lets it branch without matching prose. --format text stays one flag away for an agent that shows the output to a person.
• Exit 3, not 1. 1 means a check found a problem the code must fix. A login or a consent is neither, and a separate code lets a script or an agent tell "fix the code" from "ask the person".
• A token, not --yes. --yes answers prompts, and an agent adds it to every command it runs. The token binds the consent to one command line in one directory, so the agent has to show the person that line first.
• Detection follows @vercel/detect-agent. Agents set their own variables, and one shared list means permdock, the Vercel CLI and better-supabase switch to agent mode for the same agents. The list is copied rather than depended on so the CLI's startup loads no extra package.

RelatedCopy Anchor Link

• CLI
• Completion
• For AI agents
• Wire formats