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