stella CLI — Output & Exit Codes

Audience: CI authors and operators who script against the stella CLI and need a stable, machine-readable output and exit-code contract.

This is the canonical exit-code contract for the StellaOps CLI. Every command honors these formats and codes unless its own guide documents an exception; scripts and pipelines should branch on them rather than parsing human-readable text.

Output formats

--output json (default): deterministic JSON objects per record.
--output ndjson: one JSON object per line for streaming/large results.
--output table: aligned columns for humans; preserves stable column order.
Use --quiet to suppress informational logs; errors still print to stderr.

Exit codes (contract)

0 — Success.
1 — Generic error (unexpected exception).
2 — Validation or user input error, including parser-rejected invocations such as a missing required argument/option or a malformed/unknown argument.
3 — AuthN/AuthZ failure (expired token, missing scope).
4 — Not found / resource missing.
5 — Network disabled/offline violation when a command requires connectivity.
10 — Retryable/transient error (service unavailable, backoff suggested).

Clients and scripts should treat 2–5 as non-retryable unless input changes; only 10 should trigger automated retry with backoff.

The process invocation boundary normalizes System.CommandLine parse failures to 2 after the parser renders its diagnostic and usage text. Help and version requests still exit 0; valid commands retain the exit code returned by their handler.

Determinism & ordering

Lists are sorted (stable) by primary key or timestamp per command documentation.
Timestamps are UTC ISO-8601; hashes use hex lowercase.
Randomness is seeded; avoid machine-specific paths in emitted artefacts.

Examples

stella vuln list --output json | jq '.items[0]'
stella export mirror --offline --output ndjson > mirror.ndjson
stella task-runner simulate --output table

Observability signals

When tracing headers are present (traceparent), CLI propagates them; otherwise it emits new span IDs only in verbose logs.
Metrics are not emitted by the CLI itself; servers capture request telemetry and can be correlated via the returned correlation/trace IDs printed on errors in verbose mode.

Command-specific notes

Proof and replay surfaces

Proof verification surfaces (chain verify, bundle verify, sbom verify, witness verify) emit deterministic error bodies and stable non-zero exit behavior when cryptographic checks fail.
Score explain/replay and scan replay flows avoid synthetic fallback payloads and return explicit contract errors for missing or malformed backend responses.

Attestor transparency

attestor transparency sync run defaults to dry-run. Live connected sync requires --live --confirm-egress-window and is refused in offline/sealed mode.
airgap exchange transparency import validate|apply and connected sync runs return non-zero when Attestor reports validation issues, failed mirror receipts, or a hard stop. Human-readable output keeps Local transparency receipt separate from External mirror receipt, External mirror pending, and External mirror failed.

CLI command reference — the full stella verb tree.
Observability guide — correlation and trace IDs for debugging.
Forensics guide — verification exit codes in practice.