# Score Proofs CLI Reference

**Sprint:** SPRINT_3500_0004_0004  
**Version:** 1.0.0

## Overview

The Score Proofs CLI commands enable score computation, replay, proof verification, and proof bundle management. All commands support air-gapped operation.

---

## Commands

### stella score

Compute or replay vulnerability scores.

```bash
stella score <SUBCOMMAND> [OPTIONS]
```

#### Subcommands

| Subcommand | Description |
|------------|-------------|
| `compute` | Compute scores for a scan |
| `replay` | Replay score computation with different inputs |
| `show` | Display score details for a scan |
| `diff` | Compare scores between runs |
| `manifest` | View/export scan manifest |
| `inputs` | List scoring inputs |

---

### stella score compute

Compute vulnerability scores for a scan.

```bash
stella score compute [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID to compute scores for | Required |
| `--deterministic` | Enable deterministic mode | `true` |
| `--seed <BASE64>` | Random seed for determinism | Auto-generated |
| `--output <PATH>` | Output file path | stdout |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
| `--include-proof` | Include proof ledger in output | `false` |

#### Examples

```bash
# Compute scores
stella score compute --scan-id $SCAN_ID

# Compute with proof output
stella score compute --scan-id $SCAN_ID --include-proof --output-format json

# Compute in deterministic mode with fixed seed
stella score compute --scan-id $SCAN_ID --deterministic --seed "AQIDBA=="
```

---

### stella score replay

Replay score computation with updated feeds or policies.

```bash
stella score replay [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID to replay | Required |
| `--feed-snapshot <HASH>` | Override feed snapshot hash | Current |
| `--vex-snapshot <HASH>` | Override VEX snapshot hash | Current |
| `--policy-snapshot <HASH>` | Override policy hash | Current |
| `--use-original-snapshots` | Use exact original snapshots | `false` |
| `--diff` | Show diff from original | `false` |
| `--skip-unchanged` | Skip if no input changes | `false` |
| `--offline` | Run in offline mode | `false` |
| `--bundle <PATH>` | Use offline bundle for replay | — |
| `--output <PATH>` | Output file path | stdout |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |

#### Examples

```bash
# Replay with current feeds
stella score replay --scan-id $SCAN_ID

# Replay with specific feed snapshot
stella score replay --scan-id $SCAN_ID --feed-snapshot sha256:newfeed...

# Replay and compare with original
stella score replay --scan-id $SCAN_ID --diff

# Replay with original snapshots (exact reproduction)
stella score replay --scan-id $SCAN_ID --use-original-snapshots

# Offline replay
stella score replay --scan-id $SCAN_ID --offline --bundle /path/to/bundle.zip
```

---

### stella score show

Display score details for a scan.

```bash
stella score show [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--verbose` | Show detailed breakdown | `false` |
| `--include-evidence` | Include evidence references | `false` |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |

#### Examples

```bash
# Show score summary
stella score show --scan-id $SCAN_ID

# Show detailed breakdown
stella score show --scan-id $SCAN_ID --verbose

# JSON output
stella score show --scan-id $SCAN_ID --output-format json
```

---

### stella score diff

Compare scores between two runs.

```bash
stella score diff [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID to compare | Required |
| `--original` | Compare with original score | `false` |
| `--replayed` | Compare with most recent replay | `false` |
| `--base <RUN_ID>` | Base run ID for comparison | — |
| `--target <RUN_ID>` | Target run ID for comparison | — |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |

#### Examples

```bash
# Compare original vs replayed
stella score diff --scan-id $SCAN_ID --original --replayed

# Compare two specific runs
stella score diff --scan-id $SCAN_ID --base run-001 --target run-002
```

---

### stella score manifest

View or export scan manifest.

```bash
stella score manifest [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--output <PATH>` | Output file path | stdout |
| `--include-dsse` | Include DSSE envelope | `false` |
| `--verify` | Verify DSSE signature | `false` |

#### Examples

```bash
# View manifest
stella score manifest --scan-id $SCAN_ID

# Export with DSSE
stella score manifest --scan-id $SCAN_ID --include-dsse --output manifest.json

# Verify manifest signature
stella score manifest --scan-id $SCAN_ID --verify
```

---

## Proof Commands

### stella proof

Manage proof bundles.

```bash
stella proof <SUBCOMMAND> [OPTIONS]
```

#### Subcommands

| Subcommand | Description |
|------------|-------------|
| `verify` | Verify a proof bundle |
| `download` | Download proof bundle |
| `export` | Export proof bundle |
| `inspect` | Inspect proof bundle contents |
| `status` | Check proof status |
| `list` | List proofs for a scan |
| `retrieve` | Retrieve from cold storage |

---

### stella proof verify

Verify a proof bundle.

```bash
stella proof verify [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--bundle-id <HASH>` | Proof bundle ID (sha256:...) | — |
| `--bundle <PATH>` | Local proof bundle file | — |
| `--offline` | Skip Rekor verification | `false` |
| `--skip-rekor` | Alias for --offline | `false` |
| `--check-rekor` | Force Rekor verification | `false` |
| `--trust-anchor <PATH>` | Trust anchor file | System default |
| `--public-key <PATH>` | Public key file | — |
| `--self-contained` | Use embedded trust anchors | `false` |
| `--verbose` | Show detailed verification | `false` |
| `--check <CHECK>` | Verify specific check only | All |

#### Verification Checks

| Check | Description |
|-------|-------------|
| `signatureValid` | DSSE signature verification |
| `idRecomputed` | Content-addressed ID match |
| `merklePathValid` | Merkle tree construction |
| `rekorInclusion` | Transparency log entry |

#### Examples

```bash
# Verify online
stella proof verify --bundle-id sha256:proof123...

# Verify offline
stella proof verify --bundle proof.zip --offline

# Verify with specific trust anchor
stella proof verify --bundle proof.zip --offline --trust-anchor anchors.json

# Verify specific check
stella proof verify --bundle-id sha256:proof123... --check signatureValid
```

---

### stella proof download

Download proof bundle.

```bash
stella proof download [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--root-hash <HASH>` | Specific proof root hash | Latest |
| `--output <PATH>` | Output file path | `proof-{scanId}.zip` |
| `--all` | Download all proofs for scan | `false` |
| `--output-dir <PATH>` | Output directory (with --all) | `.` |

#### Examples

```bash
# Download latest proof
stella proof download --scan-id $SCAN_ID --output proof.zip

# Download specific proof
stella proof download --scan-id $SCAN_ID --root-hash sha256:proof123... --output proof.zip

# Download all proofs
stella proof download --scan-id $SCAN_ID --all --output-dir ./proofs/
```

---

### stella proof export

Export proof bundle with additional data.

```bash
stella proof export [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--portable` | Create self-contained portable bundle | `false` |
| `--include-manifest` | Include scan manifest | `true` |
| `--include-chain` | Include full proof chain | `false` |
| `--include-trust-anchors` | Include trust anchor keys | `false` |
| `--output <PATH>` | Output file path | Required |

#### Examples

```bash
# Export standard bundle
stella proof export --scan-id $SCAN_ID --output proof-bundle.zip

# Export portable bundle (for offline verification)
stella proof export --scan-id $SCAN_ID --portable --include-trust-anchors --output portable.zip

# Export with full chain
stella proof export --scan-id $SCAN_ID --include-chain --output full-bundle.zip
```

---

### stella proof inspect

Inspect proof bundle contents.

```bash
stella proof inspect [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--bundle <PATH>` | Proof bundle file | Required |
| `--output-dir <PATH>` | Extract to directory | — |
| `--show-manifest` | Display manifest | `false` |
| `--show-proof` | Display proof nodes | `false` |
| `--show-meta` | Display metadata | `false` |

#### Examples

```bash
# List bundle contents
stella proof inspect --bundle proof.zip

# Extract and inspect
stella proof inspect --bundle proof.zip --output-dir ./inspection/

# Show manifest
stella proof inspect --bundle proof.zip --show-manifest
```

---

## Common Options

### Authentication

| Option | Description |
|--------|-------------|
| `--token <TOKEN>` | OAuth bearer token |
| `--token-file <PATH>` | File containing token |
| `--profile <NAME>` | Use named profile |

### Output

| Option | Description |
|--------|-------------|
| `--quiet` | Suppress non-error output |
| `--verbose` | Enable verbose output |
| `--debug` | Enable debug logging |
| `--no-color` | Disable colored output |

### Connection

| Option | Description |
|--------|-------------|
| `--endpoint <URL>` | Scanner API endpoint |
| `--timeout <DURATION>` | Request timeout (e.g., 30s, 5m) |
| `--insecure` | Skip TLS verification (dev only) |

---

## Environment Variables

| Variable | Description | Equivalent Option |
|----------|-------------|-------------------|
| `STELLA_TOKEN` | OAuth token | `--token` |
| `STELLA_ENDPOINT` | API endpoint | `--endpoint` |
| `STELLA_PROFILE` | Profile name | `--profile` |
| `STELLA_OFFLINE` | Offline mode | `--offline` |
| `STELLA_TRUST_ANCHOR` | Trust anchor path | `--trust-anchor` |

---

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Authentication failed |
| 4 | Resource not found |
| 5 | Verification failed |
| 6 | Network error |
| 10 | Timeout |

---

## Related Documentation

- [Reachability CLI Reference](./reachability-cli-reference.md)
- [Unknowns CLI Reference](./unknowns-cli-reference.md)
- [Score Proofs API Reference](../api/score-proofs-reachability-api-reference.md)
- [Score Proofs Runbook](../operations/score-proofs-runbook.md)

---

**Last Updated**: 2025-12-20  
**Version**: 1.0.0  
**Sprint**: 3500.0004.0004