exit codes

Exit codes

The CLI uses exit codes to communicate failure modes to scripts and CI. The dedicated codes are public contract — scripts may branch on them and the CLI will not silently change their meaning.

Code	Meaning
0	Success.
1	Generic failure. Includes "context not found", invalid flag values, file-not-found, parser errors, and any anyhow / clap default.
77	Gateway session expired — the gateway returned 401 to a request that used a cached session token. Refresh with noetl auth login.
(other)	Forwarded from spawned processes (kubectl, cargo, etc.) when the CLI is wrapping them.

Exit code 77 — gateway session expired

Available since noetl v2.15.0 (PR #13).

Any CLI command that talks to the gateway with a cached session token can hit this. When the gateway returns 401, the CLI prints:

Gateway returned 401 (session expired) for context 'gke-prod'.
  Refresh the session token:  noetl auth login --browser-pkce

and exits with code 77. The constant is GATEWAY_AUTH_EXPIRED_EXIT_CODE in src/main.rs, documented as the CLI's stable contract for "session expired".

Why 77

77 was chosen because it doesn't collide with anything we forward from spawned processes (kubectl uses 1, 130, 137; cargo uses 101). The number itself isn't meaningful — what matters is that it's distinct from 1.

Auto-refresh pattern in scripts

set -e
noetl --context gke-prod catalog list Playbook || code=$?
if [[ "${code:-0}" -eq 77 ]]; then
    noetl auth login --browser-pkce --context gke-prod
    noetl --context gke-prod catalog list Playbook
fi

The CI variant adds a sentinel so the script doesn't loop forever on a misconfigured Auth0 application — a second 77 in a row should fail loudly.

Why not 401

Shell exit codes are limited to 0–255, and the 4xx/5xx HTTP shape doesn't map cleanly. We pick a unique, low number.

See also

• noetl auth login — refresh the session token.
• Connecting to a cluster — gateway path troubleshooting.