ota Exit Codes

This document records the current command exit-code contract for the shipped ota surface.

Global registry

• 0: success, ready state, or warning-only diagnosis
• 1: invalid contract, blocking readiness issue, protected write failure, or general command failure
• 2: CLI usage or argument parsing error
• 126: command was found but could not be executed
• 127: command could not be started, usually because the executable was not found on PATH

Command-specific rules

ota validate

• 0 on valid contract
• 1 on load or validation failure

ota tasks

• 0 on valid contract and successful task listing
• 1 on load or validation failure

ota run

• 0 on successful task execution
• child task exit code on task failure
• child task exit code is preserved for native, container, and current remote execution paths
• 126 when the child command was found but could not be executed
• 127 when the task command could not be started because the executable was not found
• 128+n when the child process terminated from signal n
• 1 when backend configuration is invalid or the requested backend/provider is unsupported
• 1 on load/validation failure or runner failure before the child exit code is available

ota doctor

• 0 when findings are empty or warning-only
• 1 when any blocking readiness finding exists
• 1 on load or validation failure

ota check

• 0 when configured checks are empty or warning/info-only
• 1 when any configured check produces an error-severity finding
• 1 on load or validation failure

ota init

• 0 on successful review output or write
• 1 when an existing ota.yaml blocks init
• 1 on detection failure
• 1 on write failure

ota up

ota up has two layers of exit codes:

• Ota-level readiness failures return 1
• child-process failures are preserved when Ota actually runs a service start command or the setup task

That means 0 is reserved for the overall command succeeding and the repo reaching READY. A child command can succeed and Ota can still return 1 later if the repo does not become ready.

• ota up --dry-run: 0 when the preview is actionable and unblocked
• ota up --dry-run: 1 when the preview identifies a blocking condition
• 0 when the repo reaches READY
• service-start child exit code when a required service start command fails
• setup task child exit code when setup fails
• setup task child exit code is preserved when setup runs through native, container, or current remote backend paths
• 126 when a service start command or setup task was found but could not be executed
• 127 when a service start command or setup task could not be started because the executable was not found
• 128+n when a service or setup child process terminated from signal n
• 1 when preconditions fail
• 1 when required-service readiness fails in the services phase
• 1 when post-up diagnosis is still not ready
• 1 on load or validation failure

ota detect

• 0 on successful dry-run output
• 0 on successful write
• 1 when an existing ota.yaml blocks write
• 1 when the high-confidence projection is insufficient to produce a valid contract
• 1 on detection failure
• 1 on write failure

ota workspace validate

• 0 on valid workspace contract
• 1 on load or validation failure

ota workspace tasks

• 0 on successful workspace task listing
• 1 on load or validation failure

ota workspace list

• 0 on successful workspace repo inventory output
• 1 on load or validation failure

ota workspace run

• 0 when all required repos complete the requested task
• 1 when any required repo task fails, acquisition fails, or is blocked by dependency failure
• 1 on load or validation failure

ota workspace check

• 0 when all required repos are check-ready or warning-only
• 1 when any required repo has a blocking check finding
• 1 on load or validation failure

ota clean

• 0 when persistent execution state is removed
• 0 when there is no cleanup action to perform
• 1 on load or validation failure
• 1 when persistent cleanup fails before ota can report success

ota clean --stale

• 0 when exited ota-managed containers are removed
• 0 when ota clean --stale --dry-run previews exited ota-managed containers
• 1 when no local container engine can be queried or stale container removal fails
• 2 when ota clean --stale is combined with PATH, --file, or --member

ota workspace doctor

• 0 when all required repos are ready or warning-only
• 1 when any required repo has a blocking finding
• 1 on load or validation failure

ota workspace up

• 0 when all required repos reach READY
• 1 when any required repo fails acquisition or does not become ready
• 1 on load or validation failure

ota workspace refresh

• 0 when existing repos refresh successfully or are skipped intentionally
• 1 when refresh fails or the workspace cannot be loaded or validated

Notes

• JSON mode does not change exit-code behavior
• ok: true in JSON output is intentionally aligned with exit code 0
• warning-only diagnosis is still success