Exit codes and errors
The CLI exits with one of these codes. In JSON mode, a failing command also prints an error envelope.
Exit codes
| Exit code | Name | Meaning |
|---|---|---|
| 0 | SUCCESS | Success. |
| 1 | GENERIC | Error (API rejection, not found, config, file system, internal). |
| 2 | USAGE | Usage (unknown command or flag, missing or invalid argument, required flag not given); also changes pending under plan --detailed-exitcode, where usage errors exit 1 instead. |
| 4 | AUTH_REQUIRED | Auth-required (log in again or fix credentials). |
| 8 | CONFLICT | Conflict (stale --base-version, changeset commit conflict, a resource still in use, an originKey another resource holds). |
| 9 | TRANSIENT | Transient (network, timeout, rate limit, server 5xx, a live write whose originKey holder the server could not name); retrying may succeed. |
perpetual capabilities --json lists every error code and the exit code it maps to.
JSON output
With --json, a command that succeeds prints {"ok": true, "data": …} on stdout. The shape of data depends on the command.
Error envelope
In JSON mode, a failing command prints one envelope as the last line of stderr, with these fields:
| Field | Meaning |
|---|---|
ok | Always false for an error. |
error | Human-readable message, without ANSI colour codes. |
code | Stable machine-readable error code; determines the exit code. |
field | The rejected input: a flag or positional as typed, the API's field path, or a GitOps file's field path. |
resource | The server ID the error is about, or the repository-relative path of the GitOps file. |
hint | One actionable next step, usually a command to run, with what it rests on; it may span lines. |
retry_after_seconds | Seconds to wait before retrying a transient failure. |
Related
Perpetual CLI 0.5.0