CLI exit codes

This page defines the current exit-code contract for holon commands. It is a script-facing companion to the CLI stability policy and CLI contract inventory.

Holon keeps the contract intentionally small while the runtime is pre-1.0:

Exit code	Meaning	Stream contract
`0`	The CLI command completed successfully.	Machine-readable commands write their JSON or documented raw response to stdout. Human commands may write prose to stdout. Stderr remains diagnostic/log output.
`1`	The command was accepted by the parser, but execution failed before a successful CLI result was produced. This includes unreachable control-plane requests, invalid runtime/config/provider setup, failed file IO, malformed stored config, and HTTP/control-plane errors surfaced by the client.	Stdout is not script-safe and should usually be empty. Diagnostics are written to stderr by the top-level error renderer and may include chained context.
`2`	Clap rejected the invocation before command execution, for example an unknown flag, missing required argument, invalid enum value, or invalid numeric range.	Stdout is empty. Clap writes usage/error text to stderr.

Codes outside this table are not part of Holon's stable CLI contract. In particular, POSIX signal-derived exit statuses are owned by the operating system and should not be interpreted as Holon business results.

Representative cases

Invalid arguments

Parser failures exit with code 2:

holon --definitely-not-a-holon-flag
echo $? # 2

Use this class for invocation-shape problems only. Scripts should treat stderr as human-readable help/error text, not as a machine-readable schema.

Unreachable control plane

Commands that need the local or remote control plane exit with code 1 when transport fails:

HOLON_HTTP_ADDR=127.0.0.1:9 holon agent status
echo $? # 1

The CLI does not synthesize a JSON error envelope on stdout for transport failures. Use stderr for operator diagnostics and retry/backoff decisions in the calling script.

Invalid configuration or provider setup

Configuration that parses as a CLI invocation but is rejected by Holon's config validators exits with code 1:

holon config providers set script-test \
  --transport openai_responses \
  --base-url not-a-url
echo $? # 1

Commands that validate stored config during startup also use code 1 for malformed or unsupported config.

Successful transport with failed business state

When a command successfully talks to the control plane, Holon's CLI exit code reports the command transport/result-rendering outcome, not every business state embedded in the returned JSON. For example, a command that successfully creates, inspects, or returns a task record exits 0 if the HTTP request and response rendering succeeded, even if the returned task or runtime object has a domain state such as failed, cancelled, blocked, or waiting.

Scripts must inspect the documented JSON fields for business state. Holon will only promote a business state to a non-zero process exit when a command's specific reference page documents that behavior.

Stdout and stderr

Treat stdout as machine-readable only for commands whose reference or inventory row says they emit JSON or a documented raw response body.
Treat stderr as human diagnostics. It may contain Clap usage text, anyhow context chains, tracing logs, provider diagnostics, or operating-system errors.
Do not parse exact stderr prose for stable automation. Prefer JSON output or HTTP/API error envelopes when a stable machine contract is required.