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

---

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

---

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

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