stella CLI — Configuration

This guide explains how the Stella Ops CLI is configured and how to inspect effective configuration across modules with the config commands.

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

Corrected 2026-09-26 (DOC-2). An earlier version of this page described a $XDG_CONFIG_HOME/stella/config.yaml file, STELLA_* environment variables (STELLA_TOKEN, STELLA_OFFLINE, STELLA_LOG_LEVEL, STELLA_TRUST_ROOTS, …) and a planned profile layout. The CLI reads none of these. The verified model is below; the full key table is in CLI architecture, section 3.

Sources and precedence (lowest to highest)

1. appsettings.json, appsettings.local.json, appsettings.yaml, appsettings.local.yaml in the current directory (all optional), bound under the StellaOps section.
2. Command-line configuration arguments.
3. Environment variables (no prefix), for example STELLAOPS_BACKEND_URL, API_KEY, STELLAOPS_AUTHORITY_URL, STELLAOPS_AUTHORITY_USERNAME, STELLAOPS_AUTHORITY_TENANT.

Each setting is resolved from an ordered key list; the first non-empty value wins (for example STELLAOPS_BACKEND_URL, then StellaOps:BackendUrl). Command options such as --tenant apply per invocation.

Common settings

• Backend (gateway) URL: STELLAOPS_BACKEND_URL.
• Credentials: API_KEY (personal access token), or STELLAOPS_AUTHORITY_URL with an operator login (STELLAOPS_AUTHORITY_USERNAME / STELLAOPS_AUTHORITY_PASSWORD) or client credentials (STELLAOPS_AUTHORITY_CLIENT_ID / STELLAOPS_AUTHORITY_CLIENT_SECRET).
• Tenant: one order for the token request and the X-StellaOps-TenantId header of every client: a command-scoped --tenant, then STELLAOPS_AUTHORITY_TENANT (StellaOps:Authority:Tenant), then StellaOps:DefaultTenant, the global --tenant, STELLAOPS_TENANT, and the active profile (stella tenants use). The first non-empty value wins and is lower-cased. Without a command-scoped --tenant the header always names the token’s tenant; a command-scoped --tenant selects another tenant for that request only, which the backend honours for global-admin principals. With nothing configured no header is sent and the token’s tenant claim applies. See CLI architecture, section 4.2.
• Token cache: STELLAOPS_AUTHORITY_TOKEN_CACHE_DIR (default ~/.stellaops/tokens).
• Offline kits: STELLAOPS_OFFLINE_KITS_DIRECTORY.
• Plug-ins: STELLAOPS_CLI_PLUGIN_BASE_DIRECTORY, STELLAOPS_CLI_PLUGIN_DIRECTORY.

Air gap

Every CLI HTTP client passes the air-gap egress policy; in sealed mode a blocked destination fails with AIRGAP_EGRESS_BLOCKED guidance instead of contacting the host.

Logging

--verbose (-v) raises the log level and enables startup diagnostics for human-readable output.

Profiles

Profile metadata lives in ~/.stellaops/profiles.json; profile secrets are protected by the host secret store (see credential storage).

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.