# stella CLI — Configuration

## Precedence (highest → lowest)
1. Command-line flags (e.g., `--output json`, `--offline`)
2. Environment variables
3. Config file (`config.yaml`/`config.json`) loaded from the first existing path:
   - `$STELLA_CONFIG` (explicit override)
   - `$XDG_CONFIG_HOME/stella/config.yaml` (or `%APPDATA%\\Stella\\config.yaml` on Windows)
   - `$HOME/.config/stella/config.yaml`

Tip: keep secrets in env vars, not in the config file; tokens are read from `STELLA_TOKEN`, registry creds from `STELLA_REGISTRY_AUTH`, etc.

## Common settings (YAML example)
```yaml
output: json            # json|ndjson|table
offline: true           # force no-network mode
api:
  baseUrl: https://console.stella.local
  token: ${STELLA_TOKEN} # prefer env substitution
policy:
  tenant: demo-tenant
  rationale: true
airgap:
  bundlesPath: /var/stella/bundles
  trustRoots: /var/stella/trust/roots.pem
observability:
  traceparent: auto      # always inject trace headers when available
```

## Air-gap/offline knobs
- `--offline` or `STELLA_OFFLINE=1` forbids network calls; commands must rely on local bundles/caches.
- `airgap.bundlesPath` controls where imports/exports read/write sealed bundles.
- Mirror/import/export commands respect `STELLA_TRUST_ROOTS` for DSSE/TUF verification.

## Logging & telemetry
- `STELLA_LOG_LEVEL=debug` for verbose logs; `trace` adds wire dumps (still deterministic).
- Tracing headers: CLI injects `traceparent` when provided by the environment (CI runners, gateways); never emits PII.

## Profiles (planned)
- Profiles will live under `profiles/<name>.yaml` and can be selected with `--profile <name>`; until shipped, stick to the single default config file.