Exit Codes

The CLI uses specific exit codes so you can branch on outcome in scripts and CI pipelines without parsing stdout.

Exit code reference

Code	Name	When it’s used
`0`	Success	Command completed successfully
`1`	General error	Unexpected internal failure (uncaught exception, bug)
`2`	Usage error	Command-line parse failure from the CLI framework: unknown command, nonexistent flag, missing required argument or flag, invalid enum value
`4`	Validation	Local precondition failed: missing/invalid token, malformed YAML, request body that doesn’t match the schema
`10`	Changes pending	`plan` / `deploy --dry-run --detailed-exitcode` detected pending changes
`11`	API error	API returned a non-2xx response (4xx or 5xx). Carries `status`, `code`, and `requestId` in stderr
`12`	Transport	Network failure before getting a response: DNS, connection refused, TLS, timeout
`13`	Partial failure	`deploy` finished but at least one resource operation failed; the remainder succeeded

The mapping is implemented in src/lib/errors.ts (EXIT_CODES). Sub-classes (e.g. DevhelmAuthError, DevhelmNotFoundError) inherit their root’s exit code. Exit 2 comes from the oclif framework before the command runs, so it is not part of EXIT_CODES.

Quick decision table

You want to…	Check
Detect any failure	`$? -ne 0`
Distinguish “config drift” from real errors in CI	`$? -eq 10` for drift, `$? -eq 0` for clean, anything else for failure
Retry only on transient failures	Retry on `12`; do not retry on `2`, `4`, or `11` (deterministic)
Surface auth problems to users	Look for `4` (no token / bad config) or `11` with `code=UNAUTHORIZED` / `code=FORBIDDEN` in stderr (rejected token)
Continue past partial deploy failure	Treat `13` as “completed with errors” and inspect the deploy report

Usage in CI

Gate merges on config drift

Use --detailed-exitcode with deploy --dry-run to detect config changes in a PR check:

devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode

Exit code	CI behavior
`0`	Config is in sync — pass the check
`10`	Config has changes — fail or flag for review
`2` / `4` / `11` / `12`	Error — fail the check

Shell scripting

devhelm monitors list -o json > monitors.json
case $? in
  0) echo "OK" ;;
  4) echo "Config error — fix and retry"; exit 1 ;;
  11) echo "API error — see request id in stderr"; exit 1 ;;
  12) echo "Network error — will retry"; sleep 5; exec "$0" "$@" ;;
  *) echo "Failed"; exit 1 ;;
esac

GitHub Actions

- name: Check for drift
  run: devhelm deploy -f devhelm.yml --dry-run --detailed-exitcode
  continue-on-error: true
  id: drift

- name: Comment on PR
  if: steps.drift.outcome == 'failure'
  run: echo "Monitoring config has pending changes"

Getting Started

Commands

Exit code reference

Quick decision table

Usage in CI

Gate merges on config drift

Shell scripting

GitHub Actions

Next steps

Deploy commands

GitHub Actions

​Exit code reference

​Quick decision table

​Usage in CI

​Gate merges on config drift

​Shell scripting

​GitHub Actions

​Next steps

Deploy commands

GitHub Actions

Exit code reference

Quick decision table

Usage in CI

Gate merges on config drift

Shell scripting

GitHub Actions

Next steps