stella CLI — Configuration

This guide explains how the Stella Ops CLI is configured: the precedence order between flags, environment variables, and config files; the common settings; the air-gap/offline knobs; and the stella config commands for inspecting effective configuration across modules.

Audience: operators configuring the CLI for interactive or CI/CD use.

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)

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

The CLI provides unified config inspection across all Stella Ops modules.

List All Config Paths

# 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

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

Secret Redaction

Secrets are automatically redacted in config output:

stella config database show

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

Popular Config Paths

Run stella config list to see the full inventory of config paths supported by your build.

See also

• Air-gap guide — sealed bundles, trust roots, and offline operation.
• Output and exit codes — the --output formats referenced above.
• Crypto Commands — crypto profile and provider configuration.