# stella CLI - Complete Command Reference

**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul

## Command Overview

The `stella` CLI provides 50+ commands organized into functional groups:

```mermaid
graph TD
    CLI[stella CLI] --> SCAN[Scanning & Analysis]
    CLI --> CRYPTO[Cryptography]
    CLI --> ADMIN[Administration]
    CLI --> AUTH[Authentication]
    CLI --> POLICY[Policy Management]
    CLI --> EXPLAIN[Explainability]
    CLI --> VEX[VEX & Decisioning]
    CLI --> SBOM[SBOM Operations]
    CLI --> ANALYTICS[Analytics & Insights]
    CLI --> REPORT[Reporting & Export]
    CLI --> OFFLINE[Offline Operations]
    CLI --> SYSTEM[System & Config]
```

---

## Global Options

Available for all commands:

| Option | Alias | Description |
|--------|-------|-------------|
| `--verbose` | `-v` | Enable verbose logging output |
| `--tenant <id>` | `-t` | Tenant context for the operation |
| `--help` | `-h` | Show command help |
| `--version` | | Show version information |

---

## Scanning & Analysis Commands

### stella scan

Scan container images for vulnerabilities and generate SBOMs.

**Usage:**
```bash
stella scan <image> [options]
```

**Arguments:**
- `<image>` - Container image reference (e.g., `docker://nginx:latest`, `tar://image.tar`)

**Options:**
| Option | Description | Default |
|--------|-------------|---------|
| `--output <path>` | Output file path | stdout |
| `--sbom-format <format>` | SBOM format: `spdx`, `cyclonedx` | `spdx` |
| `--sbom-only` | Generate SBOM only (skip vuln scan) | false |
| `--attestation` | Generate in-toto attestation | false |
| `--vex-mode <mode>` | VEX mode: `strict`, `permissive`, `disabled` | `strict` |
| `--policy <path>` | Policy file to apply | None |
| `--fail-on-policy-violations` | Exit with error if policy violations | false |

**Examples:**
```bash
# Basic scan
stella scan docker://nginx:latest --output scan-result.json

# Generate SPDX SBOM only
stella scan docker://nginx:latest --sbom-only --sbom-format spdx --output nginx.spdx.json

# Scan with attestation and policy enforcement
stella scan docker://nginx:latest \
  --attestation \
  --policy company-policy.yaml \
  --fail-on-policy-violations \
  --output results/

# Scan local tar archive
stella scan tar://image.tar --output scan.json
```

**Exit Codes:**
- `0` - Success
- `1` - Scan error
- `2` - Policy violations (with `--fail-on-policy-violations`)

---

### stella aoc

Generate Attestation of Compliance (AoC) documents.

**Usage:**
```bash
stella aoc [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--scan <path>` | Scan result file |
| `--sbom <path>` | SBOM file |
| `--output <path>` | Output attestation file |
| `--sign` | Sign attestation with crypto provider |
| `--provider <name>` | Crypto provider (for signing) |

**Example:**
```bash
stella aoc \
  --scan scan-result.json \
  --sbom sbom.spdx.json \
  --sign \
  --provider gost \
  --output attestation.jsonl
```

---

### stella symbols

Extract and index debug symbols from containers.

**Usage:**
```bash
stella symbols <command> [options]
```

**Subcommands:**
- `extract` - Extract debug symbols
- `index` - Index symbols for lookup
- `query` - Query symbol database

**Example:**
```bash
# Extract symbols
stella symbols extract docker://myapp:v1.2.3 --output symbols/

# Index symbols
stella symbols index symbols/ --output symbols.db

# Query symbols
stella symbols query --db symbols.db --address 0x12345678
```

---

## Cryptography Commands

### stella crypto providers

List available cryptographic providers.

**Usage:**
```bash
stella crypto providers [--json] [--verbose]
```

**Output (International):**
```
Available Crypto Providers:
- default (.NET Crypto, BouncyCastle)
  Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
```

**Output (Russia):**
```
Available Crypto Providers:
- default (.NET Crypto, BouncyCastle)
  Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
- gost (GOST R 34.10-2012, GOST R 34.11-2012)
  Algorithms: GOST12-256, GOST12-512, GOST2001
```

**Distribution Availability:** All

---

### stella crypto sign

Sign files with cryptographic algorithms.

**Usage:**
```bash
stella crypto sign [options]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--provider <name>` | Crypto provider | Yes |
| `--algorithm <alg>` | Algorithm (e.g., `GOST12-256`) | Yes |
| `--key-id <id>` | Key identifier | Yes |
| `--file <path>` | File to sign | Yes |
| `--output <path>` | Signature output file | Yes |
| `--detached` | Create detached signature | No (default: true) |

**Examples:**
```bash
# Sign with default provider (ECDSA)
stella crypto sign \
  --provider default \
  --algorithm ECDSA-P256 \
  --key-id prod-key \
  --file document.pdf \
  --output document.pdf.sig

# Sign with GOST (Russia distribution)
stella crypto sign \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024 \
  --file document.pdf \
  --output document.pdf.sig

# Sign with eIDAS QES (EU distribution)
stella crypto sign \
  --provider eidas \
  --algorithm ECDSA-P256-QES \
  --key-id eidas-qes-key \
  --file contract.pdf \
  --output contract.pdf.sig
```

**Distribution Availability:**
- Default provider: All
- GOST provider: Russia
- eIDAS provider: EU
- SM provider: China

---

### stella crypto verify

Verify cryptographic signatures.

**Usage:**
```bash
stella crypto verify [options]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--provider <name>` | Crypto provider | Yes |
| `--algorithm <alg>` | Algorithm | Yes |
| `--key-id <id>` | Key identifier | Yes |
| `--file <path>` | Original file | Yes |
| `--signature <path>` | Signature file | Yes |

**Example:**
```bash
stella crypto verify \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024 \
  --file document.pdf \
  --signature document.pdf.sig
```

**Output:**
```
✅ Signature valid
Provider: gost
Algorithm: GOST12-256
Signer: CN=Company GOST Key 2024
```

**Exit Codes:**
- `0` - Signature valid
- `1` - Signature invalid or verification error

---

### stella crypto profiles

Manage crypto profiles for easy provider/key switching.

**Usage:**
```bash
stella crypto profiles [command]
```

**Subcommands:**
- `list` - List crypto profiles
- `create` - Create new profile
- `use` - Set active profile
- `delete` - Delete profile

**Examples:**
```bash
# List profiles
stella crypto profiles list

# Create GOST profile
stella crypto profiles create gost-prod \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024

# Use profile
stella crypto profiles use gost-prod

# Sign using active profile
stella crypto sign --file document.pdf --output document.pdf.sig
```

---

## Administration Commands

### stella admin policy

Manage platform policies.

**Usage:**
```bash
stella admin policy <command> [options]
```

**Subcommands:**

#### stella admin policy export

Export active policy snapshot.

```bash
stella admin policy export [--output <path>] [--verbose]
```

**Example:**
```bash
stella admin policy export --output policy-backup-$(date +%F).yaml
```

#### stella admin policy import

Import policy from file.

```bash
stella admin policy import --file <path> [--validate-only] [--verbose]
```

**Example:**
```bash
# Validate before importing
stella admin policy import --file new-policy.yaml --validate-only

# Import after validation
stella admin policy import --file new-policy.yaml
```

#### stella admin policy validate

Validate policy file without importing.

```bash
stella admin policy validate --file <path> [--verbose]
```

#### stella admin policy list

List all policy revisions.

```bash
stella admin policy list [--format table|json] [--verbose]
```

**Required Scope:** `admin.policy`

**See Also:** [Admin Reference](admin-reference.md)

---

### stella admin users

User management commands.

**Usage:**
```bash
stella admin users <command> [options]
```

**Subcommands:**

#### stella admin users list

List platform users.

```bash
stella admin users list [--role <role>] [--format table|json] [--verbose]
```

#### stella admin users add

Add new user.

```bash
stella admin users add <email> --role <role> [--tenant <id>] [--verbose]
```

**Roles:**
- `admin` - Full platform access
- `security-engineer` - Security operations
- `developer` - Development access
- `viewer` - Read-only access

**Example:**
```bash
stella admin users add alice@example.com --role security-engineer --tenant acme-corp
```

#### stella admin users revoke

Revoke user access (destructive - requires confirmation).

```bash
stella admin users revoke <email> --confirm [--verbose]
```

**Example:**
```bash
stella admin users revoke bob@example.com --confirm
```

#### stella admin users update

Update user role.

```bash
stella admin users update <email> --role <role> [--verbose]
```

**Required Scope:** `admin.users`

---

### stella admin feeds

Advisory feed management.

**Usage:**
```bash
stella admin feeds <command> [options]
```

**Subcommands:**

#### stella admin feeds list

List configured advisory feeds.

```bash
stella admin feeds list [--format table|json] [--verbose]
```

#### stella admin feeds status

Show feed synchronization status.

```bash
stella admin feeds status [--source <id>] [--verbose]
```

#### stella admin feeds refresh

Trigger feed refresh.

```bash
stella admin feeds refresh [--source <id>] [--force] [--verbose]
```

**Example:**
```bash
# Refresh all feeds
stella admin feeds refresh

# Force refresh NVD (ignore cache)
stella admin feeds refresh --source nvd --force
```

#### stella admin feeds history

Show feed synchronization history.

```bash
stella admin feeds history --source <id> [--limit <n>] [--verbose]
```

**Required Scope:** `admin.feeds`

---

### stella admin system

System management commands.

**Usage:**
```bash
stella admin system <command> [options]
```

**Subcommands:**

#### stella admin system status

Show system health status.

```bash
stella admin system status [--format table|json] [--verbose]
```

**Output:**
```
System Health Status:
Component        Status    Uptime    Version
─────────────────────────────────────────────
Scanner          ✅ UP     5d 3h     2.1.0
Concelier        ✅ UP     5d 3h     2.1.0
Authority        ✅ UP     5d 3h     2.1.0
PostgreSQL       ✅ UP     10d 2h    16.2
```

#### stella admin system info

Show system version, build, and configuration.

```bash
stella admin system info [--verbose]
```

**Required Scope:** `admin.platform`

---

## Authentication Commands

### stella auth login

Authenticate with platform (interactive).

**Usage:**
```bash
stella auth login [--authority <url>] [--verbose]
```

**Example:**
```bash
# Interactive login (opens browser)
stella auth login

# Specify Authority URL
stella auth login --authority https://auth.stellaops.example.com
```

**Output:**
```
Opening browser for authentication...
✅ Logged in as alice@example.com
Token saved to ~/.stellaops/tokens.json
```

---

### stella auth logout

Log out from platform.

**Usage:**
```bash
stella auth logout [--verbose]
```

---

### stella auth whoami

Show current authentication status.

**Usage:**
```bash
stella auth whoami [--verbose]
```

**Output:**
```
Authenticated as: alice@example.com
Tenant: acme-corp
Scopes: scan.read, scan.write, admin.policy
Token expires: 2025-12-24T10:30:00Z
```

---

## Score Commands

### stella score compute

Compute a unified trust score from signal values.

**Usage:**
```bash
stella score compute [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--finding-id <ID>` | CVE@PURL finding identifier |
| `--cvss <score>` | CVSS base score (0-10) |
| `--epss <score>` | EPSS probability (0-1) |
| `--reachability <value>` | Reachability signal (0-1) |
| `--runtime <value>` | Runtime observation signal (0-1) |
| `--exploit <value>` | Exploit maturity signal (0-1) |
| `--backport <value>` | Backport availability signal (0-1) |
| `--source <value>` | Source confidence signal (0-1) |
| `--mitigation <value>` | Mitigation strength signal (0-1) |
| `--weights-version <ver>` | Pin specific weight manifest version |
| `--show-unknowns` | Include U metric and band in output |
| `--show-deltas` | Include delta-if-present calculations |
| `--format <fmt>` | Output format: `table`, `json`, `markdown` |
| `--offline` | Use bundled weights (no server required) |

**Examples:**
```bash
# Basic score computation
stella score compute --finding-id CVE-2024-1234@pkg:npm/lodash@4.17.0 \
    --cvss 7.5 --epss 0.15 --reachability 0.9

# Full output with deltas
stella score compute --finding-id CVE-2024-1234@pkg:npm/lodash@4.17.0 \
    --cvss 7.5 --reachability 0.9 --runtime 0.7 \
    --show-unknowns --show-deltas --format json
```

---

### stella score explain

Display detailed breakdown of a score computation.

**Usage:**
```bash
stella score explain <FINDING-ID> [OPTIONS]
```

**Examples:**
```bash
stella score explain CVE-2024-1234@pkg:npm/lodash@4.17.0
stella score explain CVE-2024-1234@pkg:npm/lodash@4.17.0 --format markdown
```

---

### stella score replay

Fetch the signed replay proof for a previously computed score.

**Usage:**
```bash
stella score replay <SCORE-ID> [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--format <fmt>` | Output format: `table`, `json`, `markdown` |
| `--verify-rekor` | Also verify Rekor inclusion proof |

**Examples:**
```bash
stella score replay score_a1b2c3d4e5f67890
stella score replay score_a1b2c3d4e5f67890 --format json --verify-rekor
```

---

### stella score verify

Re-execute a score computation and verify it matches the original.

**Usage:**
```bash
stella score verify <SCORE-ID> [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--format <fmt>` | Output format: `table`, `json`, `markdown` |
| `--verify-rekor` | Also verify Rekor inclusion proof |

**Examples:**
```bash
stella score verify score_a1b2c3d4e5f67890
```

---

### stella gate score evaluate

Compute unified score as part of a gate evaluation (enhanced with unknowns support).

**Usage:**
```bash
stella gate score evaluate [OPTIONS]
```

**Additional Options (new):**

| Option | Description |
|--------|-------------|
| `--show-unknowns` | Include U metric and unknowns band |
| `--show-deltas` | Include delta-if-present for missing signals |
| `--weights-version <ver>` | Pin specific weight manifest version |

---

### stella gate score weights

Manage EWS weight manifests.

**Usage:**
```bash
stella gate score weights <SUBCOMMAND>
```

**Subcommands:**

| Subcommand | Description |
|------------|-------------|
| `list` | List available weight manifest versions |
| `show <version>` | Display manifest details |
| `diff <v1> <v2>` | Compare two manifests |

**Examples:**
```bash
stella gate score weights list
stella gate score weights show v2026-01-22
stella gate score weights diff v2026-01-22 v2026-02-01
```

---

## Policy Commands

### stella policy test

Test policy against scan results.

**Usage:**
```bash
stella policy test --policy <path> --scan <path> [--verbose]
```

**Example:**
```bash
stella policy test \
  --policy company-policy.yaml \
  --scan scan-result.json
```

**Output:**
```
Policy Test Results:
✅ PASS: No critical vulnerabilities
✅ PASS: SBOM completeness >= 95%
❌ FAIL: Found 3 GPL-licensed dependencies (policy: copyleft-disallowed)

Policy Status: FAILED (1/3 checks failed)
```

---

### stella policy validate

Validate policy syntax and logic.

**Usage:**
```bash
stella policy validate --file <path> [--verbose]
```

---

## VEX & Decisioning Commands

### stella vex generate

Generate VEX document from scan results.

**Usage:**
```bash
stella vex generate --scan <path> [--output <path>] [--verbose]
```

**Example:**
```bash
stella vex generate \
  --scan scan-result.json \
  --output vex-doc.json
```

---

### stella vex merge

Merge multiple VEX documents.

**Usage:**
```bash
stella vex merge --vex <path1> --vex <path2> [--output <path>] [--verbose]
```

---

### stella decision

Manage vulnerability decisions (VEX workflow).

**Usage:**
```bash
stella decision <command> [options]
```

**Subcommands:**
- `create` - Create new decision
- `list` - List decisions
- `update` - Update decision
- `export` - Export decisions to VEX

**Example:**
```bash
# Mark CVE as not_affected
stella decision create \
  --cve CVE-2024-12345 \
  --status not_affected \
  --justification vulnerable_code_not_in_execute_path \
  --impact-statement "Vulnerable function not called in our application"
```

---

## SBOM Operations

### stella sbom generate

Generate SBOM from source code or container.

**Usage:**
```bash
stella sbom generate <target> [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--format <format>` | SBOM format: `spdx`, `cyclonedx` |
| `--output <path>` | Output file path |
| `--include-dev-dependencies` | Include dev dependencies |

**Example:**
```bash
# Generate SPDX SBOM from source
stella sbom generate . --format spdx --output sbom.spdx.json

# Generate CycloneDX SBOM from container
stella sbom generate docker://myapp:v1 --format cyclonedx --output sbom.cdx.json
```

---

### stella sbom validate

Validate SBOM against schema.

**Usage:**
```bash
stella sbom validate --file <path> [--verbose]
```

---

### stella sbom merge

Merge multiple SBOMs.

**Usage:**
```bash
stella sbom merge --sbom <path1> --sbom <path2> [--output <path>] [--verbose]
```

---

## Analytics Commands

### stella analytics sbom-lake

Query SBOM lake analytics views (suppliers, licenses, vulnerabilities, backlog,
attestation coverage, trends).

**Usage:**
```bash
stella analytics sbom-lake <subcommand> [options]
```

**Subcommands:**
- `suppliers` - Supplier concentration
- `licenses` - License distribution
- `vulnerabilities` - CVE exposure (VEX-adjusted)
- `backlog` - Fixable vulnerability backlog
- `attestation-coverage` - Provenance/SLSA coverage
- `trends` - Time-series trends (vulnerabilities/components)

**Common options:**
| Option | Description |
|--------|-------------|
| `--environment <env>` | Filter to a specific environment |
| `--min-severity <level>` | Minimum severity (`critical`, `high`, `medium`, `low`) |
| `--days <n>` | Lookback window in days (trends only) |
| `--series <name>` | Trend series (`vulnerabilities`, `components`, `all`) |
| `--limit <n>` | Maximum number of rows |
| `--format <fmt>` | Output format: `table`, `json`, `csv` |
| `--output <path>` | Output file path |

**Example:**
```bash
stella analytics sbom-lake vulnerabilities --environment prod --min-severity high --format csv --output vuln.csv
```

---

## Function Map Commands

### stella function-map generate

Generate a function map predicate from an SBOM and optional static analysis.

**Usage:**
```bash
stella function-map generate [OPTIONS]
```

**Options:**

| Option | Alias | Description |
|--------|-------|-------------|
| `--sbom <path>` | `-s` | Path to SBOM file (required) |
| `--service <name>` | | Service name (required) |
| `--subject <purl>` | | Subject artifact PURL (derived from SBOM if omitted) |
| `--static-analysis <path>` | | Path to static analysis results |
| `--hot-functions <glob>` | `-H` | Glob patterns for functions of interest (repeatable) |
| `--min-rate <value>` | | Minimum observation rate 0.0-1.0 (default 0.95) |
| `--window <seconds>` | | Observation window in seconds (default 1800) |
| `--fail-on-unexpected` | | Fail verification on unexpected symbols |
| `--output <path>` | `-o` | Output file path |
| `--format <fmt>` | `-f` | Output format: `json`, `yaml` (default json) |
| `--build-id <id>` | | Build ID for provenance correlation |

**Examples:**
```bash
# Basic generation from SBOM
stella function-map generate --sbom app.cdx.json --service my-backend

# With hot function filtering and custom thresholds
stella function-map generate \
  --sbom app.cdx.json \
  --service my-backend \
  --hot-functions "crypto/*" --hot-functions "auth/*" \
  --min-rate 0.90 --window 3600 \
  --output function-map.json
```

---

### stella function-map verify

Verify runtime observations against a function map predicate.

**Usage:**
```bash
stella function-map verify [OPTIONS]
```

**Options:**

| Option | Alias | Description |
|--------|-------|-------------|
| `--function-map <path>` | `-m` | Path or OCI reference to predicate (required) |
| `--container <id>` | `-c` | Filter to specific container ID |
| `--from <timestamp>` | | ISO 8601 start time (default: 30 min ago) |
| `--to <timestamp>` | | ISO 8601 end time (default: now) |
| `--output <path>` | `-o` | Output verification report path |
| `--format <fmt>` | `-f` | Output format: `json`, `table`, `md` (default table) |
| `--strict` | | Fail on any unexpected symbols |
| `--offline` | | Use bundled observations file |
| `--observations <path>` | | Path to observations file (NDJSON) |

**Examples:**
```bash
# Online verification against live observations
stella function-map verify \
  --function-map function-map.json \
  --from "2026-01-23T00:00:00Z" --to "2026-01-23T01:00:00Z"

# Offline verification with bundled observations
stella function-map verify \
  --function-map function-map.json \
  --offline --observations obs.ndjson \
  --format json --output report.json
```

---

## Observations Commands

### stella observations query

Query runtime observations from the observation store.

**Usage:**
```bash
stella observations query [OPTIONS]
```

**Options:**

| Option | Alias | Description |
|--------|-------|-------------|
| `--symbol <glob>` | `-s` | Glob pattern for symbol name |
| `--node-hash <hash>` | `-n` | Exact node hash filter |
| `--container <id>` | `-c` | Container ID filter |
| `--pod <name>` | `-p` | Pod name filter |
| `--namespace <ns>` | `-N` | Kubernetes namespace filter |
| `--probe-type <type>` | | Probe type filter |
| `--from <timestamp>` | | ISO 8601 start time (default: 1 hour ago) |
| `--to <timestamp>` | | ISO 8601 end time (default: now) |
| `--limit <n>` | `-l` | Maximum results (default 100) |
| `--offset <n>` | | Pagination offset (default 0) |
| `--format <fmt>` | `-f` | Output format: `json`, `table`, `csv` (default table) |
| `--summary` | | Show statistics instead of individual records |
| `--output <path>` | `-o` | Output file path |
| `--offline` | | Use local observations file |
| `--observations-file <path>` | | Path to observations file for offline mode |

**Examples:**
```bash
# Query all crypto-related observations
stella observations query --symbol "crypto_*" --from "2026-01-23T00:00:00Z"

# Summary for a specific container
stella observations query --container abc123 --summary

# Export as CSV for analysis
stella observations query --pod my-service-pod --format csv --output obs.csv
```

---

## Ground-Truth Corpus Commands

### stella groundtruth

Manage ground-truth corpus for patch-paired binary verification. The corpus supports
precision validation of security advisories by maintaining symbol and binary pairs
from upstream sources.

**Sprint:** SPRINT_20260121_035_BinaryIndex_golden_corpus_connectors_cli

**Usage:**
```bash
stella groundtruth <subcommand> [options]
```

**Subcommands:**
- `sources` - Manage symbol source connectors
- `symbols` - Query and search symbols in the corpus
- `pairs` - Manage security pairs (vuln/patch binary pairs)
- `validate` - Run validation and view metrics

---

### stella groundtruth sources

Manage upstream symbol source connectors.

**Usage:**
```bash
stella groundtruth sources <command> [options]
```

**Subcommands:**

#### stella groundtruth sources list

List available symbol source connectors.

```bash
stella groundtruth sources list [--output-format table|json] [--verbose]
```

**Output:**
```
ID                        Display Name              Status       Last Sync
------------------------------------------------------------------------------------------
debuginfod-fedora         Fedora Debuginfod         Enabled      2026-01-22T10:00:00Z
debuginfod-ubuntu         Ubuntu Debuginfod         Enabled      2026-01-22T10:00:00Z
ddeb-ubuntu               Ubuntu ddebs              Enabled      2026-01-22T09:30:00Z
buildinfo-debian          Debian Buildinfo          Enabled      2026-01-22T08:00:00Z
secdb-alpine              Alpine SecDB              Enabled      2026-01-22T06:00:00Z
```

#### stella groundtruth sources enable

Enable a symbol source connector.

```bash
stella groundtruth sources enable <source> [--verbose]
```

**Arguments:**
- `<source>` - Source connector ID (e.g., `debuginfod-fedora`)

**Example:**
```bash
stella groundtruth sources enable debuginfod-fedora
```

#### stella groundtruth sources disable

Disable a symbol source connector.

```bash
stella groundtruth sources disable <source> [--verbose]
```

#### stella groundtruth sources sync

Synchronize symbol sources from upstream.

```bash
stella groundtruth sources sync [--source <id>] [--full] [--verbose]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--source <id>` | Source connector ID (all if not specified) |
| `--full` | Perform a full sync instead of incremental |

**Example:**
```bash
# Incremental sync of all sources
stella groundtruth sources sync

# Full sync of Debian buildinfo
stella groundtruth sources sync --source buildinfo-debian --full
```

---

### stella groundtruth symbols

Query and search symbols in the corpus.

**Usage:**
```bash
stella groundtruth symbols <command> [options]
```

#### stella groundtruth symbols lookup

Lookup symbols by debug ID (build-id).

```bash
stella groundtruth symbols lookup --debug-id <id> [--output-format table|json] [--verbose]
```

**Options:**
| Option | Alias | Description | Required |
|--------|-------|-------------|----------|
| `--debug-id` | `-d` | Debug ID (build-id) to lookup | Yes |
| `--output-format` | `-O` | Output format: `table`, `json` | No |

**Example:**
```bash
stella groundtruth symbols lookup --debug-id 7f8a9b2c4d5e6f1a --output-format json
```

**Output (table):**
```
Binary: libcrypto.so.3
Architecture: x86_64
Distribution: debian-bookworm
Package: openssl@3.0.11-1
Symbol Count: 4523
Sources: debuginfod-fedora, buildinfo-debian
```

#### stella groundtruth symbols search

Search symbols by package or distribution.

```bash
stella groundtruth symbols search [--package <name>] [--distro <distro>] [--limit <n>] [--output-format table|json] [--verbose]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--package` | `-p` | Package name to search for | - |
| `--distro` | | Distribution filter (debian, ubuntu, alpine) | - |
| `--limit` | `-l` | Maximum results | 20 |

**Example:**
```bash
stella groundtruth symbols search --package openssl --distro debian --limit 50
```

---

### stella groundtruth pairs

Manage security pairs (vulnerable/patched binary pairs) in the corpus.

**Usage:**
```bash
stella groundtruth pairs <command> [options]
```

#### stella groundtruth pairs create

Create a new security pair.

```bash
stella groundtruth pairs create --cve <cve-id> --vuln-pkg <pkg=ver> --patch-pkg <pkg=ver> [--distro <distro>] [--verbose]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--cve` | CVE identifier | Yes |
| `--vuln-pkg` | Vulnerable package (name=version) | Yes |
| `--patch-pkg` | Patched package (name=version) | Yes |
| `--distro` | Distribution (e.g., `debian-bookworm`) | No |

**Example:**
```bash
stella groundtruth pairs create \
  --cve CVE-2024-1234 \
  --vuln-pkg openssl=3.0.10-1 \
  --patch-pkg openssl=3.0.11-1 \
  --distro debian-bookworm
```

#### stella groundtruth pairs list

List security pairs in the corpus.

```bash
stella groundtruth pairs list [--cve <pattern>] [--package <name>] [--limit <n>] [--output-format table|json] [--verbose]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--cve` | | Filter by CVE (supports wildcards: `CVE-2024-*`) | - |
| `--package` | `-p` | Filter by package name | - |
| `--limit` | `-l` | Maximum results | 50 |

**Example:**
```bash
stella groundtruth pairs list --cve CVE-2024-* --package openssl --limit 100
```

**Output:**
```
Pair ID      CVE                Package      Vuln Version    Patch Version
-------------------------------------------------------------------------------
pair-001     CVE-2024-1234      openssl      3.0.10-1        3.0.11-1
pair-002     CVE-2024-5678      curl         8.4.0-1         8.5.0-1
```

#### stella groundtruth pairs delete

Delete a security pair from the corpus.

```bash
stella groundtruth pairs delete <pair-id> [--force] [--verbose]
```

**Options:**
| Option | Alias | Description |
|--------|-------|-------------|
| `--force` | `-f` | Skip confirmation prompt |

---

### stella groundtruth validate

Run validation harness against security pairs.

**Usage:**
```bash
stella groundtruth validate <command> [options]
```

#### stella groundtruth validate run

Run validation on security pairs.

```bash
stella groundtruth validate run [--pairs <pattern>] [--matcher <type>] [--output <path>] [--parallel <n>] [--verbose]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--pairs` | `-p` | Pair filter pattern (e.g., `openssl:CVE-2024-*`) | all |
| `--matcher` | `-m` | Matcher type: `semantic-diffing`, `hash-based`, `hybrid` | `semantic-diffing` |
| `--output` | `-o` | Output file for validation report | - |
| `--parallel` | | Maximum parallel validations | 4 |

**Example:**
```bash
stella groundtruth validate run \
  --pairs "openssl:CVE-2024-*" \
  --matcher semantic-diffing \
  --parallel 8 \
  --output validation-report.md
```

**Output:**
```
Validating pairs: 10/10
Validation complete. Run ID: vr-20260122100532
  Function Match Rate: 94.2%
  False-Negative Rate: 2.1%
  SBOM Hash Stability: 3/3
Report written to: validation-report.md
```

#### stella groundtruth validate metrics

View metrics for a validation run.

```bash
stella groundtruth validate metrics --run-id <id> [--output-format table|json] [--verbose]
```

**Options:**
| Option | Alias | Description | Required |
|--------|-------|-------------|----------|
| `--run-id` | `-r` | Validation run ID | Yes |

**Example:**
```bash
stella groundtruth validate metrics --run-id vr-20260122100532 --output-format json
```

**Output (table):**
```
Run ID: vr-20260122100532
Duration: 2026-01-22T10:00:00Z - 2026-01-22T10:15:32Z
Pairs: 48/50 successful
Function Match Rate: 94.2%
False-Negative Rate: 2.1%
SBOM Hash Stability: 3/3
Verify Time (p50/p95): 423ms / 1.2s
```

#### stella groundtruth validate export

Export validation report.

```bash
stella groundtruth validate export --run-id <id> --output <path> [--format <fmt>] [--verbose]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--run-id` | `-r` | Validation run ID | (required) |
| `--output` | `-o` | Output file path | (required) |
| `--format` | `-f` | Export format: `markdown`, `html`, `json` | `markdown` |

**Example:**
```bash
stella groundtruth validate export \
  --run-id vr-20260122100532 \
  --format markdown \
  --output validation-report.md
```

**See Also:** [Ground-Truth CLI Guide](../ground-truth-cli.md)

---

### stella groundtruth bundle

Manage evidence bundles for offline verification of patch provenance.

**Sprint:** SPRINT_20260121_036_BinaryIndex_golden_corpus_bundle_verification

**Usage:**
```bash
stella groundtruth bundle <command> [options]
```

**Subcommands:**
- `export` - Create evidence bundles for air-gapped environments
- `import` - Import and verify evidence bundles

#### stella groundtruth bundle export

Export evidence bundles containing pre/post binaries, SBOMs, delta-sig predicates, and timestamps.

```bash
stella groundtruth bundle export [options]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--packages <list>` | Comma-separated package names (e.g., `openssl,curl`) | Yes |
| `--distros <list>` | Comma-separated distributions (e.g., `debian,ubuntu`) | Yes |
| `--output <path>` | Output bundle path (.tar.gz or .oci.tar) | Yes |
| `--sign-with <signer>` | Signing method: `cosign`, `sigstore`, `none` | No |
| `--include-debug` | Include debug symbols | No |
| `--include-kpis` | Include KPI validation results | No |
| `--include-timestamps` | Include RFC 3161 timestamps | No |

**Example:**
```bash
stella groundtruth bundle export \
  --packages openssl,zlib,glibc \
  --distros debian,fedora \
  --output evidence/security-bundle.tar.gz \
  --sign-with cosign \
  --include-debug \
  --include-kpis \
  --include-timestamps
```

**Exit Codes:**
- `0` - Bundle created successfully
- `1` - Bundle creation failed
- `2` - Invalid input or configuration error

#### stella groundtruth bundle import

Import and verify evidence bundles in air-gapped environments.

```bash
stella groundtruth bundle import [options]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--input <path>` | Input bundle path | Yes |
| `--verify-signature` | Verify bundle signatures | No |
| `--trusted-keys <path>` | Path to trusted public keys | No |
| `--trust-profile <path>` | Trust profile for verification | No |
| `--output <path>` | Output verification report | No |
| `--format <fmt>` | Report format: `markdown`, `json`, `html` | No |

**Example:**
```bash
stella groundtruth bundle import \
  --input symbol-bundle.tar.gz \
  --verify-signature \
  --trusted-keys /etc/stellaops/trusted-keys.pub \
  --trust-profile /etc/stellaops/trust-profiles/global.json \
  --output verification-report.md
```

**Verification Steps:**
1. Validate bundle manifest signature
2. Verify all blob digests match manifest
3. Validate DSSE envelope signatures against trusted keys
4. Verify RFC 3161 timestamps against trusted TSA certificates
5. Run IR matcher to confirm patched functions
6. Verify SBOM canonical hash matches signed predicate
7. Output verification report with KPI line items

**Exit Codes:**
- `0` - All verifications passed
- `1` - One or more verifications failed
- `2` - Invalid input or configuration error

---

### stella groundtruth validate check

Check KPI regression against baseline thresholds.

**Sprint:** SPRINT_20260121_036_BinaryIndex_golden_corpus_bundle_verification

```bash
stella groundtruth validate check [options]
```

**Options:**
| Option | Description | Default |
|--------|-------------|---------|
| `--results <path>` | Path to validation results JSON | (required) |
| `--baseline <path>` | Path to baseline JSON | (required) |
| `--precision-threshold <pp>` | Max precision drop (percentage points) | 0.01 |
| `--recall-threshold <pp>` | Max recall drop (percentage points) | 0.01 |
| `--fn-rate-threshold <pp>` | Max FN rate increase (percentage points) | 0.01 |
| `--determinism-threshold <rate>` | Min determinism rate | 1.0 |
| `--ttfrp-threshold <pct>` | Max TTFRP p95 increase (percentage) | 0.20 |
| `--output <path>` | Output report path | stdout |
| `--format <fmt>` | Report format: `markdown`, `json` | `markdown` |

**Example:**
```bash
stella groundtruth validate check \
  --results bench/results/20260122.json \
  --baseline bench/baselines/current.json \
  --precision-threshold 0.01 \
  --recall-threshold 0.01 \
  --fn-rate-threshold 0.01 \
  --determinism-threshold 1.0 \
  --output regression-report.md
```

**Regression Gates:**
| Metric | Threshold | Action |
|--------|-----------|--------|
| Precision | Drops > threshold | Fail |
| Recall | Drops > threshold | Fail |
| False-negative rate | Increases > threshold | Fail |
| Deterministic replay | Drops below threshold | Fail |
| TTFRP p95 | Increases > threshold | Warn |

**Exit Codes:**
- `0` - All gates passed
- `1` - One or more gates failed
- `2` - Invalid input or configuration error

---

### stella groundtruth baseline

Manage KPI baselines for regression detection.

**Sprint:** SPRINT_20260121_036_BinaryIndex_golden_corpus_bundle_verification

**Usage:**
```bash
stella groundtruth baseline <command> [options]
```

**Subcommands:**
- `update` - Update baseline from validation results
- `show` - Display baseline contents

#### stella groundtruth baseline update

Update baseline from validation results.

```bash
stella groundtruth baseline update [options]
```

**Options:**
| Option | Description | Required |
|--------|-------------|----------|
| `--from-results <path>` | Path to validation results JSON | Yes |
| `--output <path>` | Output baseline path | Yes |
| `--description <text>` | Description for the baseline update | No |
| `--source <commit>` | Source commit SHA for traceability | No |

**Example:**
```bash
stella groundtruth baseline update \
  --from-results bench/results/20260122.json \
  --output bench/baselines/current.json \
  --description "Post algorithm-v2.3 update" \
  --source "$(git rev-parse HEAD)"
```

#### stella groundtruth baseline show

Display baseline contents.

```bash
stella groundtruth baseline show --baseline <path> [--format table|json]
```

**Options:**
| Option | Description | Default |
|--------|-------------|---------|
| `--baseline <path>` | Path to baseline JSON | (required) |
| `--format` | Output format: `table`, `json` | `table` |

**Output (table):**
```
Baseline ID: baseline-20260122120000
Created: 2026-01-22T12:00:00Z
Source: abc123def456
Description: Post-semantic-diffing-v2 baseline

KPIs:
  Precision:              0.9500
  Recall:                 0.9200
  False Negative Rate:    0.0800
  Determinism:            1.0000
  TTFRP p95:              150ms
```

**See Also:** [Ground-Truth CLI Guide](../ground-truth-cli.md)

---

## Attestation Commands

### stella attest attach

Attach an attestation (DSSE envelope) to an OCI image via ORAS referrers.

**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-01)

**Usage:**
```bash
stella attest attach --image <ref> --attestation <path> [options]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--image` | `-i` | OCI image reference (e.g., `registry.example.com/app:v1.2`) | (required) |
| `--attestation` | `-a` | Path to DSSE envelope JSON file | (required) |
| `--media-type` | | Media type for the attestation layer | `application/vnd.dsse.envelope.v1+json` |
| `--registry-url` | | Override registry URL | From image reference |
| `--verbose` | `-v` | Show detailed progress | `false` |

**Example:**
```bash
stella attest attach \
  --image registry.example.com/app:v1.2 \
  --attestation delta-sig.dsse.json \
  --verbose
```

**Exit Codes:**
- `0` - Attestation attached successfully
- `1` - Attachment failed (registry error, invalid envelope)
- `2` - Invalid input or configuration error

---

### stella attest verify

Verify attestations attached to an OCI image. Lists and validates DSSE envelopes, checks signatures, and optionally verifies Rekor annotations.

**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-02)

**Usage:**
```bash
stella attest verify --image <ref> [options]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--image` | `-i` | OCI image reference to verify | (required) |
| `--predicate-type` | | Filter by predicate type URI | (all) |
| `--trusted-keys` | | Path to trusted public keys directory | (none) |
| `--require-rekor` | | Require valid Rekor inclusion annotations | `false` |
| `--output` | `-o` | Output format: `table`, `json` | `table` |
| `--verbose` | `-v` | Show detailed verification steps | `false` |

**Example:**
```bash
stella attest verify \
  --image registry.example.com/app:v1.2 \
  --predicate-type "https://stellaops.dev/delta-sig/v1" \
  --require-rekor \
  --output json
```

**Exit Codes:**
- `0` - All attestations verified successfully
- `1` - One or more attestations failed verification
- `2` - Invalid input or configuration error

---

## Binary Analysis Commands

### stella binary delta-sig attest

Sign a delta-sig predicate with an EC key and optionally submit to a Rekor transparency log. Produces a DSSE envelope suitable for `stella attest attach`.

**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-05)

**Usage:**
```bash
stella binary delta-sig attest --predicate <path> --key <path> [options]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--predicate` | `-p` | Path to delta-sig predicate JSON file | (required) |
| `--key` | `-k` | Path to EC private key (PEM) for DSSE signing | (required) |
| `--output` | `-o` | Path to write the DSSE envelope | stdout |
| `--rekor-url` | | Rekor transparency log URL for submission | (none) |
| `--receipt` | | Path to save Rekor receipt JSON | (none, only with `--rekor-url`) |
| `--dry-run` | | Validate predicate and key without signing | `false` |
| `--verbose` | `-v` | Show detailed signing and submission steps | `false` |

**Example:**
```bash
# Sign predicate and submit to Rekor
stella binary delta-sig attest \
  --predicate delta-sig-predicate.json \
  --key signing-key.pem \
  --output signed-envelope.dsse.json \
  --rekor-url https://rekor.sigstore.dev \
  --receipt rekor-receipt.json \
  --verbose

# Dry run (validate only)
stella binary delta-sig attest \
  --predicate delta-sig-predicate.json \
  --key signing-key.pem \
  --dry-run
```

**Signing Behavior:**
- Key must be an ECDSA private key (PEM format)
- Produces an in-toto v1 statement wrapping the predicate as DSSE payload
- PAE (Pre-Authentication Encoding) used per DSSE specification
- Signature is Base64-encoded in the envelope

**Rekor Submission:**
- When `--rekor-url` is provided, the signed envelope is submitted to the transparency log
- On success, Rekor UUID and log index are displayed
- Receipt JSON includes `uuid`, `logIndex`, `integratedTime`, and `logUrl`

**Exit Codes:**
- `0` - Signing (and optional Rekor submission) succeeded
- `1` - Signing or submission failed
- `2` - Invalid predicate, key format, or configuration error

---

## Bundle Commands

### stella bundle verify

Verify offline evidence bundles with full cryptographic verification. Checks manifest integrity, blob digests, DSSE signatures, Rekor proofs, timestamps, payload types, and optionally replays large blob content verification.

**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-06)

**Usage:**
```bash
stella bundle verify --bundle <path> [options]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--bundle` | `-b` | Path to bundle (tar.gz or directory) | (required) |
| `--trust-root` | | Path to trusted root certificate (PEM) | (none) |
| `--rekor-checkpoint` | | Path to Rekor checkpoint for offline proof verification | (none) |
| `--offline` | | Run in offline mode (no network access) | `false` |
| `--output` | `-o` | Output format: `table`, `json` | `table` |
| `--strict` | | Fail on any warning (missing optional artifacts) | `false` |
| `--signer` | | Path to signing key (PEM) for verification report | (none) |
| `--signer-cert` | | Path to signer certificate PEM (for report metadata) | (none) |
| `--replay` | | Verify binary content by fetching/reading large blobs referenced in attestations | `false` |
| `--blob-source` | | Override blob source (registry URL or local directory path) | (auto-detect) |
| `--verbose` | `-v` | Show detailed verification steps | `false` |

**Verification Steps:**
1. **Manifest checksum** - Validate bundle manifest integrity
2. **Blob digests** - Verify all blob file SHA-256 digests match manifest
3. **DSSE signatures** - Validate envelope signatures against trusted keys
4. **Rekor proofs** - Verify inclusion proofs against checkpoint (when provided)
5. **Timestamps** - Validate RFC 3161 timestamps against TSA certificates
6. **Payload types** - Verify predicate types match expectations
7. **Blob Replay** (when `--replay`) - Fetch and verify large blobs referenced in attestations

**Blob Replay Behavior:**
- For **full bundles** (blobs embedded): verifies content from `blobs/` directory against attestation digests
- For **light bundles** (metadata only): fetches blobs from `--blob-source` (local dir or registry URL)
- Supports `sha256`, `sha384`, `sha512` digest algorithms
- In `--offline` mode, blob fetch from registries is blocked (only local sources work)

**Example:**
```bash
# Basic verification
stella bundle verify --bundle evidence-bundle.tar.gz

# Full verification with replay and trust root
stella bundle verify \
  --bundle /path/to/bundle \
  --trust-root /etc/stellaops/tsa-root.pem \
  --rekor-checkpoint checkpoint.json \
  --replay \
  --verbose

# Light bundle with local blob source
stella bundle verify \
  --bundle light-bundle/ \
  --replay \
  --blob-source /path/to/blobs/

# Strict offline verification with signed report
stella bundle verify \
  --bundle evidence-bundle/ \
  --offline \
  --strict \
  --signer report-key.pem \
  --signer-cert report-cert.pem
```

**Exit Codes:**
- `0` - All verifications passed
- `1` - One or more verifications failed
- `2` - Invalid input or configuration error

---

## Evidence Commands

### stella evidence export-bundle

Export evidence bundles for offline verification. Supports two-tier export modes: **light** (metadata and attestations only) and **full** (includes embedded binary blobs).

**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-04)

**Usage:**
```bash
stella evidence export-bundle --image <ref> --output <path> [options]
```

**Options:**
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--image` | `-i` | OCI image reference to export evidence for | (required) |
| `--output` | `-o` | Output bundle path (.tar.gz or directory) | (required) |
| `--full` | | Export in full mode (embed binary blobs alongside attestations) | `false` (light mode) |
| `--sign-with` | | Signing method for bundle: `cosign`, `sigstore`, `none` | `none` |
| `--verbose` | `-v` | Show detailed export progress | `false` |

**Export Modes:**

| Mode | Flag | Contents | Size | Use Case |
|------|------|----------|------|----------|
| **Light** | (default) | Manifest, attestation envelopes, metadata | Small | Quick transfer, metadata audit |
| **Full** | `--full` | Light + embedded binary blobs in `blobs/` dir | Large | Air-gap verification, replay |

**Example:**
```bash
# Light export (default)
stella evidence export-bundle \
  --image registry.example.com/app:v1.2 \
  --output evidence-light.tar.gz

# Full export with embedded blobs
stella evidence export-bundle \
  --image registry.example.com/app:v1.2 \
  --output evidence-full.tar.gz \
  --full \
  --verbose
```

**Exit Codes:**
- `0` - Bundle exported successfully
- `1` - Export failed
- `2` - Invalid input or configuration error

---
## Reporting & Export Commands

### stella report

Generate compliance reports from scan results.

**Usage:**
```bash
stella report --scan <path> --format <format> [--output <path>] [--verbose]
```

**Formats:**
- `html` - HTML report
- `pdf` - PDF report
- `markdown` - Markdown report
- `csv` - CSV export
- `json` - JSON export

**Example:**
```bash
# Generate HTML report
stella report --scan scan-result.json --format html --output report.html

# Generate PDF report
stella report --scan scan-result.json --format pdf --output report.pdf
```

---

### stella export

Export scan results in various formats.

**Usage:**
```bash
stella export --scan <path> --format <format> [--output <path>] [--verbose]
```

**Formats:**
- `csv` - CSV export for spreadsheets
- `sarif` - SARIF format for CI/CD integration
- `json` - JSON export
- `xml` - XML export

**Example:**
```bash
# Export to CSV for Excel analysis
stella export --scan scan-result.json --format csv --output vulnerabilities.csv

# Export to SARIF for GitHub Code Scanning
stella export --scan scan-result.json --format sarif --output results.sarif
```

---

## Offline Operations

### stella offline sync

Synchronize offline package for air-gapped environments.

**Usage:**
```bash
stella offline sync [--output <path>] [--feeds nvd,osv,github] [--verbose]
```

**Example:**
```bash
# Create offline package
stella offline sync \
  --feeds nvd,osv,github \
  --output stellaops-offline-$(date +%F).tar.gz
```

---

### stella offline load

Load offline package into air-gapped instance.

**Usage:**
```bash
stella offline load --package <path> [--verbose]
```

**Example:**
```bash
stella offline load --package stellaops-offline-2025-12-23.tar.gz
```

---

## System & Configuration

### stella config

Manage CLI configuration.

**Usage:**
```bash
stella config <command> [options]
```

**Subcommands:**
- `show` - Show current configuration
- `set` - Set configuration value
- `get` - Get configuration value
- `list` - List all configuration keys
- `profile` - Manage profiles

**Examples:**
```bash
# Show current config
stella config show

# Set backend URL
stella config set Backend.BaseUrl https://api.stellaops.example.com

# Get backend URL
stella config get Backend.BaseUrl

# Create profile
stella config profile create prod --backend-url https://api.stellaops.example.com

# Switch profile
stella config profile use prod
```

---

### stella system diagnostics

Run system diagnostics.

**Usage:**
```bash
stella system diagnostics [--verbose]
```

**Output:**
```
System Diagnostics:
✅ CLI version: 2.1.0
✅ .NET Runtime: 10.0.0
✅ Backend reachable: https://api.stellaops.example.com
✅ Authentication: Valid (expires 2025-12-24)
✅ Crypto providers: default, gost
⚠️  PostgreSQL: Not configured (offline mode)
```

---

### stella version

Show version information.

**Usage:**
```bash
stella version [--verbose]
```

**Output:**
```
stella CLI version 2.1.0
Build: 2025-12-23T10:00:00Z
Commit: dfaa207
Distribution: stella-russia
Platform: linux-x64
.NET Runtime: 10.0.0
```

---

## Explainability Commands

### stella explain block

Explain why an artifact was blocked by policy gates. Produces deterministic trace with referenced evidence artifacts.

**Sprint:** SPRINT_20260117_026_CLI_why_blocked_command
**Moat Reference:** M2 (Explainability with proof, not narrative)

**Usage:**
```bash
stella explain block <digest> [options]
```

**Arguments:**
- `<digest>` - Artifact digest (`sha256:abc123...`, raw hex, or OCI reference)

**Options:**
| Option | Description | Default |
|--------|-------------|---------|
| `--format <format>` | Output format: `table`, `json`, `markdown` | `table` |
| `--show-evidence` | Include full evidence artifact details | false |
| `--show-trace` | Include policy evaluation trace | false |
| `--replay-token` | Include replay token in output | false |
| `--output <path>` | Write to file instead of stdout | stdout |
| `--offline` | Query local verdict cache only | false |

**Examples:**
```bash
# Basic explanation
stella explain block sha256:abc123def456...

# JSON output for CI/CD
stella explain block sha256:abc123... --format json --output reason.json

# Full explanation with evidence and trace
stella explain block sha256:abc123... --show-evidence --show-trace

# Markdown for PR comment
stella explain block sha256:abc123... --format markdown | gh pr comment 123 --body-file -
```

**Exit Codes:**
- `0` - Artifact is NOT blocked (all gates passed)
- `1` - Artifact IS blocked
- `2` - Error (not found, API error)

**Output (table):**
```
Artifact: sha256:abc123def456789012345678901234567890123456789012345678901234
Status: BLOCKED

Gate: VexTrust
Reason: Trust score below threshold (0.45 < 0.70)
Suggestion: Obtain VEX statement from trusted issuer

Evidence:
  [VEX   ] vex:sha256:de...23  vendor-x  2026-01-15T10:00:00Z
  [REACH ] reach:sha256...56   static    2026-01-15T09:55:00Z

Replay: stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000
```

**See Also:** [Explain Commands Documentation](explain.md)

---

## Additional Commands

### stella vuln query

Query vulnerability database.

**Usage:**
```bash
stella vuln query <cve-id> [--verbose]
```

---

### stella findings

Manage scan findings.

**Usage:**
```bash
stella findings <command> [options]
```

---

### stella advise

Get AI-powered remediation advice for vulnerabilities.

**Usage:**
```bash
stella advise --cve <cve-id> [--verbose]
```

---

### stella reachability

Analyze vulnerability reachability in code.

**Usage:**
```bash
stella reachability analyze --scan <path> --code <path> [--output <path>]
```

---

### stella graph

Call graph evidence and lineage commands.

**Usage:**
```bash
stella graph explain --graph-id <id> [--vuln-id <id>] [--purl <purl>] [--json]
stella graph verify --hash <blake3:...> [--format text|json|markdown]
stella graph lineage show <digest|purl> [--format json|graphson|mermaid] [--output <path>]
```

---

### stella mirror

Manage local package mirrors for offline operation.

**Usage:**
```bash
stella mirror <command> [options]
```

---

### stella notify

Send notifications about scan results.

**Usage:**
```bash
stella notify --scan <path> --channel slack --webhook <url>
```

---

### stella issuer

Manage issuer keys for signing and verification.

**Usage:**
```bash
stella issuer keys list --format json
stella issuer keys create --type ecdsa --name primary --format json
stella issuer keys rotate <id> --format json
stella issuer keys revoke <id> --format json
```

---

## Language-Specific Commands

### stella ruby

Ruby-specific operations.

```bash
stella ruby analyze <path>
```

### stella python

Python-specific operations.

```bash
stella python analyze <path>
```

### stella php

PHP-specific operations.

```bash
stella php analyze <path>
```

---

## Exit Codes

Standard exit codes across all commands:

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Policy violations (with `--fail-on-policy-violations`) |
| `3` | Authentication error |
| `4` | Configuration error |
| `5` | Network error |
| `10` | Invalid arguments |

---

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `STELLAOPS_BACKEND_URL` | Backend API URL | `https://api.stellaops.example.com` |
| `STELLAOPS_API_KEY` | API key for authentication | `sk_live_...` |
| `STELLAOPS_TENANT` | Default tenant | `acme-corp` |
| `STELLAOPS_CRYPTO_PROVIDER` | Default crypto provider | `gost`, `eidas`, `sm` |
| `STELLAOPS_LOG_LEVEL` | Log level | `Debug`, `Info`, `Warning`, `Error` |
| `STELLAOPS_OFFLINE_MODE` | Enable offline mode | `true` |
| `STELLAOPS_CONFIG_PATH` | Custom config file path | `~/.stellaops/custom.yaml` |

---

## See Also

- [CLI Overview](README.md) - Quick start and installation
- [CLI Architecture](architecture.md) - Plugin architecture
- [Admin Reference](admin-reference.md) - Detailed admin command reference
- [Crypto Plugins](crypto-plugins.md) - Crypto plugin development
- [Compliance Guide](compliance-guide.md) - Regional compliance requirements
- [Troubleshooting](troubleshooting.md) - Common issues and solutions