# Reachability CLI Reference

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

## Overview

The Reachability CLI commands enable call graph management, reachability computation, and explain queries. All commands support air-gapped operation.

---

## Commands

### stella reachability

Manage reachability analysis.

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

#### Subcommands

| Subcommand | Description |
|------------|-------------|
| `compute` | Trigger reachability computation |
| `findings` | List reachability findings |
| `explain` | Explain reachability verdict |
| `explain-all` | Export all explanations |
| `summary` | Show reachability summary |
| `job-status` | Check computation job status |
| `job-logs` | View job logs |
| `job-cancel` | Cancel running job |

---

### stella reachability compute

Trigger reachability computation for a scan.

```bash
stella reachability compute [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--max-depth <N>` | Maximum path length to explore | 10 |
| `--indirect-resolution <MODE>` | Handle indirect calls: `conservative`, `aggressive`, `skip` | `conservative` |
| `--timeout <DURATION>` | Maximum computation time | 300s |
| `--parallel` | Enable parallel BFS | `true` |
| `--include-runtime` | Merge runtime evidence | `true` |
| `--offline` | Run in offline mode | `false` |
| `--symbol-db <PATH>` | Symbol resolution database | System default |
| `--deterministic` | Enable deterministic mode | `true` |
| `--seed <BASE64>` | Random seed for determinism | Auto |
| `--graph-digest <HASH>` | Use specific call graph version | Latest |
| `--partition-by <KEY>` | Partition analysis: `artifact`, `entrypoint` | — |
| `--force` | Force recomputation | `false` |
| `--wait` | Wait for completion | `false` |

#### Examples

```bash
# Basic computation
stella reachability compute --scan-id $SCAN_ID

# With custom options
stella reachability compute --scan-id $SCAN_ID \
  --max-depth 20 \
  --timeout 600s \
  --indirect-resolution conservative

# Wait for completion
stella reachability compute --scan-id $SCAN_ID --wait

# Offline computation
stella reachability compute --scan-id $SCAN_ID --offline
```

---

### stella reachability findings

List reachability findings for a scan.

```bash
stella reachability findings [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--status <STATUS>` | Filter by status (comma-separated) | All |
| `--cve <ID>` | Filter by CVE ID | — |
| `--purl <PURL>` | Filter by package URL | — |
| `--min-confidence <N>` | Minimum confidence (0-1) | 0 |
| `--output <PATH>` | Output file path | stdout |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table`, `sarif` | `table` |

#### Status Values

| Status | Description |
|--------|-------------|
| `UNREACHABLE` | No path found |
| `POSSIBLY_REACHABLE` | Path with heuristic edges |
| `REACHABLE_STATIC` | Statically proven path |
| `REACHABLE_PROVEN` | Runtime confirmed |
| `UNKNOWN` | Insufficient data |

#### Examples

```bash
# List all findings
stella reachability findings --scan-id $SCAN_ID

# Filter by status
stella reachability findings --scan-id $SCAN_ID \
  --status REACHABLE_STATIC,REACHABLE_PROVEN

# Export as SARIF for CI
stella reachability findings --scan-id $SCAN_ID \
  --status REACHABLE_STATIC,REACHABLE_PROVEN \
  --output-format sarif \
  --output findings.sarif

# JSON output
stella reachability findings --scan-id $SCAN_ID --output-format json
```

---

### stella reachability explain

Explain a reachability verdict.

```bash
stella reachability explain [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--cve <ID>` | CVE ID | Required |
| `--purl <PURL>` | Package URL | Required |
| `--all-paths` | Show all paths, not just shortest | `false` |
| `--max-paths <N>` | Maximum paths to show | 5 |
| `--verbose` | Show detailed explanation | `false` |
| `--offline` | Run in offline mode | `false` |
| `--output <PATH>` | Output file path | stdout |
| `--output-format <FMT>` | Format: `json`, `yaml`, `text` | `text` |

#### Examples

```bash
# Explain single finding
stella reachability explain --scan-id $SCAN_ID \
  --cve CVE-2024-1234 \
  --purl "pkg:npm/lodash@4.17.20"

# Show all paths
stella reachability explain --scan-id $SCAN_ID \
  --cve CVE-2024-1234 \
  --purl "pkg:npm/lodash@4.17.20" \
  --all-paths

# JSON output
stella reachability explain --scan-id $SCAN_ID \
  --cve CVE-2024-1234 \
  --purl "pkg:npm/lodash@4.17.20" \
  --output-format json
```

#### Output Example

```
Status: REACHABLE_STATIC
Confidence: 0.70

Shortest Path (depth=3):
[0] MyApp.Controllers.OrdersController::Get(Guid)
    Entrypoint: HTTP GET /api/orders/{id}
[1] MyApp.Services.OrderService::Process(Order)
    Edge: static (direct_call)
[2] Lodash.merge(Object, Object) [VULNERABLE]
    Edge: static (direct_call)

Why Reachable:
- Static call path exists from HTTP entrypoint /api/orders/{id}
- All edges are statically proven (no heuristics)
- Vulnerable function Lodash.merge() is directly invoked

Confidence Factors:
  staticPathExists: +0.50
  noHeuristicEdges: +0.20
  runtimeConfirmed: +0.00

Alternative Paths: 2
```

---

### stella reachability explain-all

Export all reachability explanations.

```bash
stella reachability explain-all [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--status <STATUS>` | Filter by status | All |
| `--output <PATH>` | Output file path | Required |
| `--offline` | Run in offline mode | `false` |

#### Examples

```bash
# Export all explanations
stella reachability explain-all --scan-id $SCAN_ID --output explanations.json

# Export only reachable findings
stella reachability explain-all --scan-id $SCAN_ID \
  --status REACHABLE_STATIC,REACHABLE_PROVEN \
  --output reachable-explanations.json
```

---

### stella reachability summary

Show reachability summary for a scan.

```bash
stella reachability summary [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |

#### Examples

```bash
# Show summary
stella reachability summary --scan-id $SCAN_ID

# Output:
# Total vulnerabilities: 45
# Unreachable: 38 (84%)
# Possibly reachable: 4 (9%)
# Reachable (static): 2 (4%)
# Reachable (proven): 1 (2%)
# Unknown: 0 (0%)
```

---

### stella reachability job-status

Check computation job status.

```bash
stella reachability job-status [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--job-id <ID>` | Job ID | Required |

#### Examples

```bash
stella reachability job-status --job-id reachability-job-001

# Output:
# Status: running
# Progress: 67% (8,234 / 12,345 nodes visited)
# Started: 2025-12-20T10:00:00Z
# Estimated completion: 2025-12-20T10:02:30Z
```

---

## Call Graph Commands

### stella scan graph

Manage call graphs.

```bash
stella scan graph <SUBCOMMAND> [OPTIONS]
```

#### Subcommands

| Subcommand | Description |
|------------|-------------|
| `upload` | Upload call graph |
| `summary` | Show call graph summary |
| `entrypoints` | List entrypoints |
| `export` | Export call graph |
| `validate` | Validate call graph |
| `visualize` | Generate visualization |
| `convert` | Convert graph format |
| `partition` | Partition large graph |
| `merge` | Merge multiple graphs |

---

### stella scan graph upload

Upload a call graph to a scan.

```bash
stella scan graph upload [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--file <PATH>` | Call graph file | Required |
| `--format <FMT>` | Format: `json`, `ndjson` | Auto-detect |
| `--streaming` | Use streaming upload | `false` |
| `--framework <NAME>` | Framework hint | Auto-detect |

#### Examples

```bash
# Basic upload
stella scan graph upload --scan-id $SCAN_ID --file callgraph.json

# Streaming upload (large graphs)
stella scan graph upload --scan-id $SCAN_ID \
  --file callgraph.ndjson \
  --format ndjson \
  --streaming

# With framework hint
stella scan graph upload --scan-id $SCAN_ID \
  --file callgraph.json \
  --framework aspnetcore
```

---

### stella scan graph summary

Show call graph summary.

```bash
stella scan graph summary [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |

#### Examples

```bash
stella scan graph summary --scan-id $SCAN_ID

# Output:
# Nodes: 12,345
# Edges: 56,789
# Entrypoints: 42
# Languages: [dotnet, java]
# Size: 15.2 MB
```

---

### stella scan graph entrypoints

List detected entrypoints.

```bash
stella scan graph entrypoints [OPTIONS]
```

#### Options

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

#### Examples

```bash
# List entrypoints
stella scan graph entrypoints --scan-id $SCAN_ID

# Output:
# Kind     | Route               | Framework   | Node
# ─────────┼─────────────────────┼─────────────┼────────────────
# http     | GET /api/orders     | aspnetcore  | OrdersController::Get
# http     | POST /api/orders    | aspnetcore  | OrdersController::Create
# grpc     | OrderService.Get    | grpc-dotnet | OrderService::GetOrder
```

---

### stella scan graph validate

Validate call graph structure.

```bash
stella scan graph validate [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Validate uploaded graph | — |
| `--file <PATH>` | Validate local file | — |
| `--strict` | Enable strict validation | `false` |

#### Validation Checks

- All edge targets exist as nodes
- Entrypoints reference valid nodes
- No orphan nodes
- No cycles in entrypoint definitions
- Schema compliance

#### Examples

```bash
# Validate uploaded graph
stella scan graph validate --scan-id $SCAN_ID

# Validate before upload
stella scan graph validate --file callgraph.json --strict
```

---

### stella scan graph visualize

Generate call graph visualization.

```bash
stella scan graph visualize [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan ID | Required |
| `--node <ID>` | Center on specific node | — |
| `--depth <N>` | Visualization depth | 3 |
| `--output <PATH>` | Output file (SVG/PNG/DOT) | Required |
| `--format <FMT>` | Format: `svg`, `png`, `dot` | `svg` |

#### Examples

```bash
# Visualize subgraph
stella scan graph visualize --scan-id $SCAN_ID \
  --node sha256:node123... \
  --depth 3 \
  --output subgraph.svg
```

---

## 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 |
| `--insecure` | Skip TLS verification |

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `STELLA_TOKEN` | OAuth token |
| `STELLA_ENDPOINT` | API endpoint |
| `STELLA_PROFILE` | Profile name |
| `STELLA_OFFLINE` | Offline mode |
| `STELLA_SYMBOL_DB` | Symbol database path |

---

## Exit Codes

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

---

## Related Documentation

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

---

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