Stable, scriptable meanings. The message tells a human what happened; the exit code tells a script what to do.
| Code | Name | Meaning | Typical next step |
|---|---|---|---|
| 0 | Ok | worked | — |
| 1 | Failure | legacy catch-all (being retired in favor of precise codes) | read stderr |
| 2 | Usage | bad arguments | fix the invocation |
| 3 | Ref | reference unresolvable or ambiguous | check agit log, spell the ref fully |
| 4 | Precondition | a precondition wasn’t met | run the command it tells you to run |
| 5 | Auth | not signed in, or token rejected | agit login |
| 6 | Network | hub unreachable / network error | retry in a moment; if it persists, the hub may be down |
| 7 | Policy | a gate refused: secret scan, push gate, baseline mismatch | follow the printed reason |
| 8 | NeedsDecision | needs an interactive answer (e.g. publish from a read-only clone) but stdin isn’t a TTY | run the exact command it prints |
Two examples of the code carrying the story:
- 8 in CI is the designed answer to “promote this clone or not?” — the decision belongs to a person, so automation gets the command to hand them, not a guess.
- 7 from
agit pushmeans the secret scan found something. There is no silent override on the hub side; fix the content.
All codes are regression-pinned by the CLI’s test suite against a table in
src/lib.rs — they don’t drift.