35 lines
1.6 KiB
Markdown
35 lines
1.6 KiB
Markdown
# 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.
|