# stella CLI — Observability Guide

## Commands
- `stella obs top` (planned): stream service health (SLO/burn-rate, queue depth, error rates) with table/JSON output.
- `stella obs trace <trace_id>`: fetch correlated trace if server supports it; prints correlation/trace IDs.
- `stella obs logs --from <ts> --to <ts> [--service <name>]`: pull logs for a window with pagination tokens.

## Flags
- `--output json|ndjson|table` (default: json).
- `--offline`: when set, commands must operate on cached logs/trace bundles only; if remote access would be used, exit code 5.
- `--page-size`, `--page-token`: deterministic pagination.

## Output & exit codes
- Exit codes follow `guides/output-and-exit-codes.md` (not found → 4; offline violation → 5).
- Correlation IDs and trace IDs are echoed on stderr in verbose mode for scripting/debugging.

## Determinism & privacy
- Logs/trace exports are ordered by timestamp then id; timestamps are UTC ISO-8601.
- CLI never redacts server-side; it only forwards what the API returns. Avoid printing secrets—use `--output json` with `jq` to filter locally.

## Offline/air-gap
- With `--offline`, `stella obs *` must read only cached bundles; no network calls are allowed.
- For sealed environments, pass `--trust-roots <pem>` when verifying cached trace/log bundles.

## Examples
```bash
# Fetch logs for the last hour in NDJSON
stella obs logs --from "2025-11-25T01:00:00Z" --to "2025-11-25T02:00:00Z" --output ndjson

# Retrieve a trace and pretty print spans
stella obs trace 4f2c8d1c-3b1e-4a7f-9e4a-1f4c56 --output json | jq '.spans[0]'
```