work

docs/modules/cli/guides/output-and-exit-codes.md

@@ -0,0 +1,34 @@
+# 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
+```bash
+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.