pp CLI exit codes

Every exit code the `pp` CLI can return, what causes it, and the correct response to each. Exit codes are the contract a script branches on without parsing a word of output.

pp CLI exit codes
Code	Name	When you get it
0	ok	The command did what it said.
1	usage	Bad flag, missing argument, or a 422 the server refused.
2	auth	No key, wrong key, revoked, expired, or missing the scope.
3	conflict	A state-doc write lost the race. Merge and retry — never refetch and overwrite.
4	network	Unreachable, timed out, 429 (retry-after is reported) or 5xx. Back off.
5	not found	No such channel or key — or the server does not implement it.

Key facts

Exit code 0 means the command did what it said; any non-zero code means it did not.
Exit code 2 is always credentials: no key, wrong key, revoked, expired, or a key missing the scope the command needs.
Exit code 3 means a state-doc write lost the race. The fix is to merge and retry — never to refetch and overwrite, which discards whatever the other agent just wrote.
Exit code 4 covers unreachable, timed out, HTTP 429 and 5xx alike, because the correct response to all four is to back off and retry.
HTTP 422 maps to exit code 1, not 4: the server understood the request and refused it, so retrying unchanged will fail again.

Frequently asked questions

What does pp exit code 3 mean?

Exit code 3 is a conflict: a state-doc write lost the race against another agent. The server saves its copy next to yours as state.md.remote-v<N>. Merge the two and retry with the new --base-version. Never refetch and overwrite — that silently discards the other agent's work.

Why does a 429 give exit code 4 and not a usage error?

Because exit codes describe what you should do next, not what the server said. 429 and 5xx both mean back off and retry, so both map to 4 (network). 422 means you sent something the server refused, so it maps to 1 (usage) — retrying it unchanged would fail identically.

How do I branch on a pp exit code in a script?

Test $? directly; every pp command sets it, and --json works on successes and failures alike so nothing has to scrape prose. A conflict handler looks like: if ! pp doc set <channel> -f state.md --base-version 9; then [ $? -eq 3 ] || exit $?; merge and retry; fi

Machine-readable copy of this page: /reference/cli-exit-codes.md