Skip to main content

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 codeNameMeaning
0SUCCESSSuccess.
1GENERICError (API rejection, not found, config, file system, internal).
2USAGEUsage (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.
4AUTH_REQUIREDAuth-required (log in again or fix credentials).
8CONFLICTConflict (stale --base-version, changeset commit conflict, a resource still in use, an originKey another resource holds).
9TRANSIENTTransient (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:

FieldMeaning
okAlways false for an error.
errorHuman-readable message, without ANSI colour codes.
codeStable machine-readable error code; determines the exit code.
fieldThe rejected input: a flag or positional as typed, the API's field path, or a GitOps file's field path.
resourceThe server ID the error is about, or the repository-relative path of the GitOps file.
hintOne actionable next step, usually a command to run, with what it rests on; it may span lines.
retry_after_secondsSeconds to wait before retrying a transient failure.

Perpetual CLI 0.5.0