# Smart-Diff CLI Reference

**Sprint:** SPRINT_3500_0001_0001  
**Task:** SDIFF-MASTER-0008 - Update CLI documentation with smart-diff commands

## Overview

Smart-Diff analyzes changes between container image versions to identify material risk changes. It detects reachability shifts, VEX status changes, binary hardening regressions, and intelligence signal updates.

## Commands

### stellaops smart-diff

Compare two artifacts and report material risk changes.

```bash
stellaops smart-diff [OPTIONS]
```

#### Required Options

| Option | Description |
|--------|-------------|
| `--base <ARTIFACT>` | Base artifact (image digest, SBOM path, or purl) |
| `--target <ARTIFACT>` | Target artifact to compare against base |

#### Output Options

| Option | Description | Default |
|--------|-------------|---------|
| `--output <PATH>` | Output file path | stdout |
| `--output-format <FMT>` | Output format: `json`, `yaml`, `table`, `sarif` | `table` |
| `--output-dir <DIR>` | Output directory for bundle format | - |
| `--include-proofs` | Include proof ledger in output | `false` |
| `--include-evidence` | Include raw evidence data | `false` |
| `--pretty` | Pretty-print JSON/YAML output | `false` |

#### Analysis Options

| Option | Description | Default |
|--------|-------------|---------|
| `--rules <PATH>` | Custom detection rules file | built-in |
| `--config <PATH>` | Scoring configuration file | default config |
| `--tier <TIER>` | Filter by evidence tier: `imported`, `executed`, `tainted_sink` | all |
| `--min-priority <N>` | Minimum priority score (0-1) | 0.0 |
| `--include-unchanged` | Include unchanged findings | `false` |

#### Feed Options

| Option | Description | Default |
|--------|-------------|---------|
| `--feed-snapshot <HASH>` | Use specific feed snapshot | latest |
| `--offline` | Run in offline mode | `false` |
| `--feed-dir <PATH>` | Local feed directory | - |

### Examples

#### Basic Comparison

```bash
# Compare two image versions
stellaops smart-diff \
  --base registry.example.com/app:v1.0.0 \
  --target registry.example.com/app:v1.1.0

# Output:
# Smart-Diff Report: app:v1.0.0 → app:v1.1.0
# ═══════════════════════════════════════════
#
# Summary:
#   Total Changes: 5
#   Risk Increased: 2
#   Risk Decreased: 3
#   Hardening Regressions: 1
#
# Material Changes:
# ┌─────────────────┬──────────────────┬──────────┬──────────┐
# │ Vulnerability   │ Component        │ Change   │ Priority │
# ├─────────────────┼──────────────────┼──────────┼──────────┤
# │ CVE-2024-1234   │ lodash@4.17.20   │ +reach   │ 0.85     │
# │ CVE-2024-5678   │ requests@2.28.0  │ +kev     │ 0.95     │
# │ CVE-2024-9999   │ urllib3@1.26.0   │ -reach   │ 0.60     │
# └─────────────────┴──────────────────┴──────────┴──────────┘
```

#### SARIF Output for CI/CD

```bash
# Generate SARIF for GitHub Actions
stellaops smart-diff \
  --base app:v1.0.0 \
  --target app:v1.1.0 \
  --output-format sarif \
  --output results.sarif
```

#### Filtered Analysis

```bash
# Only show high-priority changes
stellaops smart-diff \
  --base app:v1 \
  --target app:v2 \
  --min-priority 0.7 \
  --output-format json

# Only tainted_sink tier findings
stellaops smart-diff \
  --base app:v1 \
  --target app:v2 \
  --tier tainted_sink
```

#### Export with Proofs

```bash
# Full export with proof bundle
stellaops smart-diff \
  --base app:v1 \
  --target app:v2 \
  --output-dir ./smart-diff-export \
  --include-proofs \
  --include-evidence

# Creates:
# ./smart-diff-export/
# ├── manifest.json
# ├── diff-results.json
# ├── proofs/
# └── evidence/
```

#### Offline Mode

```bash
# Use local feeds only
STELLAOPS_OFFLINE=true stellaops smart-diff \
  --base sbom-v1.json \
  --target sbom-v2.json \
  --feed-dir /opt/stellaops/feeds
```

### stellaops smart-diff show

Display results from a saved smart-diff report.

```bash
stellaops smart-diff show [OPTIONS] <INPUT>
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--format <FMT>` | Output format: `table`, `json`, `yaml` | `table` |
| `--filter <EXPR>` | Filter expression (e.g., `priority>=0.8`) | - |
| `--sort <FIELD>` | Sort field: `priority`, `vuln`, `component` | `priority` |
| `--limit <N>` | Maximum results to show | all |

#### Example

```bash
# Show top 5 highest priority changes
stellaops smart-diff show \
  --sort priority \
  --limit 5 \
  smart-diff-report.json
```

### stellaops smart-diff verify

Verify a smart-diff report's proof bundle.

```bash
stellaops smart-diff verify [OPTIONS] <INPUT>
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--proof-bundle <PATH>` | Proof bundle path | inferred |
| `--public-key <PATH>` | Public key for signature verification | - |
| `--strict` | Fail on any warning | `false` |

#### Example

```bash
# Verify report integrity
stellaops smart-diff verify \
  --proof-bundle ./proofs \
  --public-key /path/to/key.pub \
  smart-diff-report.json

# Output:
# ✓ Manifest hash verified: sha256:abc123...
# ✓ Proof ledger valid (45 nodes)
# ✓ Root hash matches
# ✓ Signature valid (key: CN=scanner.stellaops.io)
```

### stellaops smart-diff replay

Re-run smart-diff with different feed or config.

```bash
stellaops smart-diff replay [OPTIONS] <SCAN-ID>
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--feed-snapshot <HASH>` | Use specific feed snapshot | latest |
| `--config <PATH>` | Different scoring config | original |
| `--dry-run` | Preview without saving | `false` |

#### Example

```bash
# Replay with new feed
stellaops smart-diff replay \
  --feed-snapshot sha256:abc123... \
  scan-12345678

# Preview impact of config change
stellaops smart-diff replay \
  --config strict-scoring.json \
  --dry-run \
  scan-12345678
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success, no material changes |
| 1 | Success, material changes found |
| 2 | Success, hardening regressions found |
| 3 | Success, KEV additions found |
| 10 | Invalid arguments |
| 11 | Artifact not found |
| 12 | Feed not available |
| 20 | Verification failed |
| 99 | Internal error |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `STELLAOPS_OFFLINE` | Run in offline mode |
| `STELLAOPS_FEED_DIR` | Local feed directory |
| `STELLAOPS_CONFIG` | Default config file |
| `STELLAOPS_OUTPUT_FORMAT` | Default output format |

## Configuration File

```yaml
# ~/.stellaops/smart-diff.yaml
defaults:
  output_format: json
  include_proofs: true
  min_priority: 0.3

scoring:
  reachability_flip_up_weight: 1.0
  kev_added_weight: 1.5
  hardening_regression_weight: 0.8

rules:
  custom_path: /path/to/custom-rules.json
```

## Related Commands

- `stellaops scan` - Full vulnerability scan
- `stellaops score replay` - Score replay
- `stellaops verify-bundle` - Verify proof bundles

## Related Documentation

- [Smart-Diff Air-Gap Workflows](../airgap/smart-diff-airgap-workflows.md)
- [SARIF Integration](../ci/sarif-integration.md)
- [Scoring Configuration](../ci/scoring-configuration.md)