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

---

## Config Inspection Commands

> **Sprint:** SPRINT_20260112_014_CLI_config_viewer

The CLI provides unified config inspection across all StellaOps modules.

### List All Config Paths

```bash
# List all supported config paths
stella config list

# Output:
# Path                                    Alias                    Module
# ────────────────────────────────────────────────────────────────────────
# policy.determinization                  policy:determinization   Policy
# policy.confidenceweights                policy:weights           Policy
# scanner                                 scanner                  Scanner
# scanner.reachability.prgate            scanner:prgate           Scanner
# attestor.rekor                          attestor:rekor           Attestor
# signals.evidenceweightedscore           signals:ews              Signals
# ...

# Filter by module
stella config list --module policy

# Output as JSON
stella config list --output json
```

### Show Effective Config

```bash
# Show effective config for a path
stella config policy.determinization show

# Output:
# Effective Determinization Config
# ─────────────────────────────────
# Source: Service (api/v1/policy/config/determinization)
#
# Reanalysis Triggers:
#   epssDeltaThreshold: 0.2
#   triggerOnThresholdCrossing: true
#   triggerOnRekorEntry: true
#   triggerOnVexStatusChange: true
#   triggerOnRuntimeTelemetryChange: true
#   triggerOnPatchProofAdded: true
#   triggerOnDsseValidationChange: true
#   triggerOnToolVersionChange: false
#
# Conflict Handling:
#   vexReachabilityContradiction: RequireManualReview
#   ...

# Use path alias
stella config policy:determinization show

# Output as JSON
stella config policy.determinization show --output json

# Show from config file (bypass service)
stella config policy.determinization show --config /etc/stella/config.yaml
```

### Config Path Normalization

Path matching is case-insensitive with flexible separators:

| Input | Normalized | Valid |
|-------|------------|-------|
| `policy.determinization` | `policy.determinization` | ✓ |
| `Policy:Determinization` | `policy.determinization` | ✓ |
| `POLICY.DETERMINIZATION` | `policy.determinization` | ✓ |
| `policy:determinization` | `policy.determinization` | ✓ |

### Secret Redaction

Secrets are automatically redacted in config output:

```bash
stella config database show

# Output:
# database:
#   host: pg.stella.local
#   port: 5432
#   database: stella
#   username: stella_app
#   password: ********  # Redacted
#   connectionString: ********  # Redacted
```

### Popular Config Paths

| Path | Description |
|------|-------------|
| `policy.determinization` | Determinization triggers and thresholds |
| `policy.confidenceweights` | Evidence confidence weight values |
| `scanner` | Core scanner settings |
| `attestor.rekor` | Rekor transparency log settings |
| `signals.evidenceweightedscore` | EWS calculation settings |
| `excititor.mirror` | VEX mirror configuration |
| `airgap.bundlesigning` | Offline kit bundle signing |
| `signer.keyless` | Sigstore keyless signing |

See the full config inventory in `docs/implplan/SPRINT_20260112_014_CLI_config_viewer.md`.