Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Exit code reference

CodeNameWhen it’s used
0SuccessCommand completed successfully
1General errorUnexpected internal failure (uncaught exception, bug)
4ValidationLocal precondition failed: missing/invalid token, malformed YAML, request body that doesn’t match the schema, missing flag value
10Changes pendingplan / deploy --dry-run --detailed-exitcode detected pending changes
11API errorAPI returned a non-2xx response (4xx or 5xx). Carries status, code, and requestId in stderr
12TransportNetwork failure before getting a response: DNS, connection refused, TLS, timeout
13Partial failuredeploy 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.

​
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 failuresRetry on 12; do not retry on 4 or 11 (likely deterministic)
Surface auth problems to usersLook for 4 (no token / bad config) or 11 with code=AUTH (rejected token)
Continue past partial deploy failureTreat 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 codeCI behavior
0Config is in sync — pass the check
10Config has changes — fail or flag for review
4 / 11 / 12Error — 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"

​
Next steps

Deploy commands

Full deploy, plan, and validate reference.

GitHub Actions

CI/CD integration with the setup-devhelm action.