# Drift CLI Reference

**Sprint:** SPRINT_3600_0004_0001  
**Task:** UI-024 - Update CLI documentation for drift commands

## Overview

The Drift CLI provides commands for detecting and analyzing reachability drift between scan results. Reachability drift occurs when the call paths to vulnerable code change between builds, potentially altering the risk profile of an application.

## Commands

### stellaops drift

Parent command for reachability drift operations.

```bash
stellaops drift <SUBCOMMAND> [OPTIONS]
```

---

### stellaops drift compare

Compare reachability between two scans or graph snapshots.

```bash
stellaops drift compare [OPTIONS]
```

#### Required Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--base <ID>` | `-b` | Base scan/graph ID or commit SHA for comparison |

#### Optional Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--head <ID>` | `-h` | Head scan/graph ID or commit SHA | latest |
| `--image <REF>` | `-i` | Container image reference (digest or tag) | - |
| `--repo <REPO>` | `-r` | Repository reference (owner/repo) | - |
| `--output <FMT>` | `-o` | Output format: `table`, `json`, `sarif` | `table` |
| `--min-severity <SEV>` | | Minimum severity: `critical`, `high`, `medium`, `low`, `info` | `medium` |
| `--only-increases` | | Only show sinks with increased reachability | `false` |
| `--verbose` | | Enable verbose output | `false` |

#### Examples

##### Compare by scan IDs

```bash
stellaops drift compare --base abc123 --head def456
```

##### Compare by commit SHAs

```bash
stellaops drift compare --base HEAD~1 --head HEAD --repo myorg/myapp
```

##### Filter to risk increases only

```bash
stellaops drift compare --base abc123 --only-increases --min-severity high
```

##### Output as JSON

```bash
stellaops drift compare --base abc123 --output json > drift.json
```

##### Output as SARIF for CI integration

```bash
stellaops drift compare --base abc123 --output sarif > drift.sarif
```

---

### stellaops drift show

Display details of a previously computed drift result.

```bash
stellaops drift show [OPTIONS]
```

#### Required Options

| Option | Description |
|--------|-------------|
| `--id <ID>` | Drift result ID to display |

#### Optional Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--output <FMT>` | `-o` | Output format: `table`, `json`, `sarif` | `table` |
| `--expand-paths` | | Show full call paths instead of compressed view | `false` |
| `--verbose` | | Enable verbose output | `false` |

#### Examples

##### Show drift result

```bash
stellaops drift show --id drift-abc123
```

##### Show with expanded paths

```bash
stellaops drift show --id drift-abc123 --expand-paths
```

---

## Output Formats

### Table Format (Default)

Human-readable table output using Spectre.Console:

```
┌─────────────────────────────────────────────────────────────┐
│ Reachability Drift (abc123)                                 │
├───────────────────────────────┬─────────────────────────────┤
│ Metric                        │ Value                       │
├───────────────────────────────┼─────────────────────────────┤
│ Trend                         │ ↑ Increasing                │
│ Net Risk Delta                │ +3                          │
│ Increased                     │ 4                           │
│ Decreased                     │ 1                           │
│ New Sinks                     │ 2                           │
│ Removed Sinks                 │ 0                           │
└───────────────────────────────┴─────────────────────────────┘

┌──────────────┬──────────────────────┬───────────────┬─────────────────────────┬───────┐
│ Severity     │ Sink                 │ CVE           │ Bucket Change           │ Delta │
├──────────────┼──────────────────────┼───────────────┼─────────────────────────┼───────┤
│ CRITICAL     │ SqlConnection.Open   │ CVE-2024-1234 │ Runtime → Entrypoint    │ +2    │
│ HIGH         │ XmlParser.Parse      │ CVE-2024-5678 │ Unknown → Direct        │ +1    │
└──────────────┴──────────────────────┴───────────────┴─────────────────────────┴───────┘
```

### JSON Format

Structured JSON for programmatic processing:

```json
{
  "id": "abc123",
  "comparedAt": "2025-12-18T10:30:00Z",
  "baseGraphId": "base-graph-id",
  "headGraphId": "head-graph-id",
  "summary": {
    "totalSinks": 42,
    "increasedReachability": 4,
    "decreasedReachability": 1,
    "unchangedReachability": 35,
    "newSinks": 2,
    "removedSinks": 0,
    "riskTrend": "increasing",
    "netRiskDelta": 3
  },
  "driftedSinks": [
    {
      "sinkSymbol": "SqlConnection.Open",
      "cveId": "CVE-2024-1234",
      "severity": "critical",
      "previousBucket": "runtime",
      "currentBucket": "entrypoint",
      "isRiskIncrease": true,
      "riskDelta": 2
    }
  ]
}
```

### SARIF Format

SARIF 2.1.0 output for CI/CD integration:

```json
{
  "version": "2.1.0",
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "StellaOps Drift",
          "version": "1.0.0",
          "informationUri": "https://stellaops.io/docs/drift"
        }
      },
      "results": [
        {
          "ruleId": "CVE-2024-1234",
          "level": "error",
          "message": {
            "text": "Reachability changed: runtime → entrypoint"
          }
        }
      ]
    }
  ]
}
```

---

## Exit Codes

| Code | Description |
|------|-------------|
| `0` | Success (no risk increases or within threshold) |
| `1` | Error during execution |
| `2` | Risk increases detected |
| `3` | Critical risk increases detected |

---

## CI/CD Integration

### GitHub Actions

```yaml
- name: Check Reachability Drift
  run: |
    stellaops drift compare \
      --base ${{ github.event.pull_request.base.sha }} \
      --head ${{ github.sha }} \
      --repo ${{ github.repository }} \
      --output sarif > drift.sarif
  continue-on-error: true

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: drift.sarif
```

### GitLab CI

```yaml
drift-check:
  script:
    - stellaops drift compare --base $CI_MERGE_REQUEST_DIFF_BASE_SHA --head $CI_COMMIT_SHA --output sarif > drift.sarif
  artifacts:
    reports:
      sast: drift.sarif
```

---

## Related Documentation

- [Reachability Analysis](../reachability/README.md)
- [Smart-Diff CLI](./smart-diff-cli.md)
- [VEX Decisioning](../vex/decisioning.md)