Exit Codes
Every omni-cli invocation ends in exactly one of these codes. Branch on the exit code, not on stdout's shape — stdout carries the bare platform payload on success and nothing on failure (the structured error goes to stderr; see Invocation & Envelope). The same table ships in the CLI: omni-cli errors.
| Code | Name | Meaning |
|---|---|---|
| 0 | ok |
success |
| 2 | usage_error |
bad usage (incl. unknown/out-of-build command, --context both on an action) |
| 3 | context_unresolved |
no work/personal context resolved |
| 4 | not_authenticated |
no credential for the platform:context |
| 5 | auth_invalid |
credential rejected by the platform (401) |
| 6 | interactive_required |
an interactive terminal is required |
| 7 | permission_denied |
permission denied (403 / insecure local file perms) |
| 8 | not_found |
resource not found (404) |
| 9 | upstream_error |
upstream platform error (5xx / network) — outcome indeterminate; the CLI does not retry, the agent re-issues only if upstream.idempotent |
| 10 | entitlement_required |
entitlement required (paid stop / window expired) |
| 11 | update_required |
binary below min_binary_version — run omni-cli self-update |
| 12 | rate_limited |
platform rate-limited the request (429) — rejected before applying; the CLI does not retry, the agent may re-issue after upstream.retry_after_seconds |
What to do, per code
0ok — read the payload from stdout.2usage_error — fix the command: re-read the action's discovery entry; don't re-issue as-is.3context_unresolved — pass--context workor--context personalexplicitly.4not_authenticated — a human must run the platform's login command on this machine.5auth_invalid — a human must re-run the platform login; the stored credential was rejected.6interactive_required — a human must run this command; agents never can.7permission_denied — a human widens the credential's scopes (or fixes local file permissions).8not_found — check the identifiers passed; the resource doesn't exist upstream.9upstream_error — re-issue ONLY if the error'supstream.idempotentis true; the outcome is indeterminate.10entitlement_required — a human reviews the plan or subscription; the action is outside the current entitlement.11update_required — a human runsomni-cli self-update.12rate_limited — waitupstream.retry_after_seconds, then re-issue; the request was rejected before applying.
The CLI executes every action exactly once and never retries — not even reads. Retry decisions belong to the caller, informed by the error's upstream object (idempotent, mutating, retry_after_seconds).
Read this page as markdown — the copy your coding agent fetches.