git.stella-ops.org/docs/modules/cli/guides/output-and-exit-codes.md

stella CLI — Output & Exit Codes

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.
• 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.

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.