# Unknowns CLI Reference

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

## Overview

The Unknowns CLI commands manage components that cannot be analyzed due to missing data, unrecognized formats, or resolution failures. These commands support triage workflows, escalation, and resolution tracking.

---

## Commands

### stella unknowns

Manage unknowns registry.

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

#### Subcommands

| Subcommand | Description |
|------------|-------------|
| `list` | List unknowns |
| `show` | Show unknown details |
| `summary` | Show unknowns summary |
| `escalate` | Escalate unknown |
| `resolve` | Mark unknown resolved |
| `suppress` | Suppress unknown |
| `bulk-triage` | Bulk triage unknowns |
| `export` | Export unknowns |
| `import` | Import unknown resolutions |

---

### stella unknowns list

List unknowns for a scan or workspace.

```bash
stella unknowns list [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Filter by scan ID | — |
| `--workspace-id <ID>` | Filter by workspace ID | — |
| `--status <STATUS>` | Filter by status | All |
| `--category <CAT>` | Filter by category | All |
| `--priority <PRI>` | Filter by priority (1-10) | All |
| `--min-score <N>` | Minimum 2-factor score | 0 |
| `--max-age <DURATION>` | Maximum age | — |
| `--purl <PATTERN>` | Filter by PURL pattern | — |
| `--output <PATH>` | Output file path | stdout |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table`, `csv` | `table` |
| `--limit <N>` | Maximum results | 100 |
| `--offset <N>` | Pagination offset | 0 |
| `--sort <FIELD>` | Sort field | `priority` |
| `--order <DIR>` | Sort direction: `asc`, `desc` | `desc` |

#### Status Values

| Status | Description |
|--------|-------------|
| `pending` | Awaiting triage |
| `escalated` | Escalated for manual review |
| `suppressed` | Suppressed (accepted risk) |
| `resolved` | Resolved |

#### Category Values

| Category | Description |
|----------|-------------|
| `unmapped_purl` | No CPE/OVAL mapping |
| `checksum_miss` | Binary checksum not in DB |
| `language_gap` | Unsupported language |
| `parsing_failure` | Manifest parsing failed |
| `network_timeout` | Feed unavailable |
| `unrecognized_format` | Unknown format |

#### Examples

```bash
# List all pending unknowns
stella unknowns list --status pending

# List high-priority unknowns
stella unknowns list --min-score 7

# List by category
stella unknowns list --category unmapped_purl

# Export to CSV
stella unknowns list --scan-id $SCAN_ID --output-format csv --output unknowns.csv

# Filter by PURL pattern
stella unknowns list --purl "pkg:npm/*"
```

---

### stella unknowns show

Show details of a specific unknown.

```bash
stella unknowns show [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--id <ID>` | Unknown ID | Required |
| `--verbose` | Show extended details | `false` |
| `--output-format <FMT>` | Format: `json`, `yaml`, `text` | `text` |

#### Examples

```bash
# Show unknown details
stella unknowns show --id unknown-001

# Output:
# ID: unknown-001
# PURL: pkg:npm/left-pad@1.3.0
# Category: unmapped_purl
# Status: pending
# Priority: 6
# Score: 7.2 (vuln: 3, impact: 4.2)
# Created: 2025-12-20T10:00:00Z
# Scans Affected: 5
# Reason: No CVE/advisory mapping exists for this package

# Verbose output
stella unknowns show --id unknown-001 --verbose

# JSON output
stella unknowns show --id unknown-001 --output-format json
```

---

### stella unknowns summary

Show unknowns summary statistics.

```bash
stella unknowns summary [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Filter by scan ID | — |
| `--workspace-id <ID>` | Filter by workspace ID | — |
| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |

#### Examples

```bash
# Summary for workspace
stella unknowns summary --workspace-id $WS_ID

# Output:
# Total unknowns: 127
# 
# By Status:
#   pending: 89
#   escalated: 15
#   suppressed: 12
#   resolved: 11
# 
# By Category:
#   unmapped_purl: 67
#   checksum_miss: 34
#   language_gap: 18
#   parsing_failure: 8
# 
# Priority Distribution:
#   High (8-10): 12
#   Medium (5-7): 45
#   Low (1-4): 70
```

---

### stella unknowns escalate

Escalate an unknown for manual review.

```bash
stella unknowns escalate [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--id <ID>` | Unknown ID | Required |
| `--reason <TEXT>` | Escalation reason | — |
| `--assignee <USER>` | Assign to user/team | — |
| `--severity <LEVEL>` | Severity: `low`, `medium`, `high`, `critical` | `medium` |
| `--due-date <DATE>` | Due date (ISO 8601) | — |

#### Examples

```bash
# Basic escalation
stella unknowns escalate --id unknown-001 --reason "Potential supply chain risk"

# Escalate with assignment
stella unknowns escalate --id unknown-001 \
  --reason "Missing mapping for critical dependency" \
  --assignee security-team \
  --severity high \
  --due-date 2025-12-27
```

---

### stella unknowns resolve

Mark an unknown as resolved.

```bash
stella unknowns resolve [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--id <ID>` | Unknown ID | Required |
| `--resolution <TYPE>` | Resolution type | Required |
| `--comment <TEXT>` | Resolution comment | — |
| `--mapping <JSON>` | Custom mapping data | — |
| `--evidence <PATH>` | Evidence file | — |

#### Resolution Types

| Type | Description |
|------|-------------|
| `mapped` | Package/CVE mapping added |
| `not_applicable` | Not applicable to context |
| `false_positive` | Detection was incorrect |
| `accepted_risk` | Risk accepted |
| `replaced` | Component replaced |
| `removed` | Component removed |

#### Examples

```bash
# Resolve with mapping
stella unknowns resolve --id unknown-001 \
  --resolution mapped \
  --comment "Added CPE mapping to internal DB"

# Resolve as accepted risk
stella unknowns resolve --id unknown-001 \
  --resolution accepted_risk \
  --comment "Internal component, no external exposure"

# Resolve with evidence
stella unknowns resolve --id unknown-001 \
  --resolution not_applicable \
  --evidence ./analysis-report.pdf
```

---

### stella unknowns suppress

Suppress an unknown (accept risk).

```bash
stella unknowns suppress [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--id <ID>` | Unknown ID | Required |
| `--reason <TEXT>` | Suppression reason | Required |
| `--expires <DATE>` | Expiration date | — |
| `--scope <SCOPE>` | Scope: `scan`, `workspace`, `global` | `scan` |
| `--approver <USER>` | Approver name/email | — |

#### Examples

```bash
# Suppress with expiration
stella unknowns suppress --id unknown-001 \
  --reason "Internal tooling, no risk exposure" \
  --expires 2026-01-01

# Workspace-wide suppression
stella unknowns suppress --id unknown-001 \
  --reason "Deprecated component, scheduled for removal" \
  --scope workspace \
  --approver security@example.com
```

---

### stella unknowns bulk-triage

Bulk triage multiple unknowns.

```bash
stella unknowns bulk-triage [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--file <PATH>` | Triage decisions file (JSON/YAML) | Required |
| `--dry-run` | Preview changes | `false` |
| `--continue-on-error` | Continue on individual failures | `false` |

#### Input File Format

```json
{
  "decisions": [
    {
      "id": "unknown-001",
      "action": "resolve",
      "resolution": "mapped",
      "comment": "Added mapping"
    },
    {
      "id": "unknown-002",
      "action": "suppress",
      "reason": "Accepted risk",
      "expires": "2026-01-01"
    },
    {
      "id": "unknown-003",
      "action": "escalate",
      "reason": "Needs security review",
      "assignee": "security-team"
    }
  ]
}
```

#### Examples

```bash
# Bulk triage with preview
stella unknowns bulk-triage --file triage-decisions.json --dry-run

# Apply bulk triage
stella unknowns bulk-triage --file triage-decisions.json
```

---

### stella unknowns export

Export unknowns data.

```bash
stella unknowns export [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Filter by scan ID | — |
| `--workspace-id <ID>` | Filter by workspace ID | — |
| `--status <STATUS>` | Filter by status | All |
| `--output <PATH>` | Output file path | Required |
| `--format <FMT>` | Format: `json`, `yaml`, `csv`, `ndjson` | `json` |
| `--include-history` | Include resolution history | `false` |

#### Examples

```bash
# Export all unknowns
stella unknowns export --workspace-id $WS_ID --output unknowns.json

# Export pending as CSV
stella unknowns export --status pending --output pending.csv --format csv

# Export with history
stella unknowns export --scan-id $SCAN_ID \
  --output unknowns-history.json \
  --include-history
```

---

### stella unknowns import

Import unknown resolutions.

```bash
stella unknowns import [OPTIONS]
```

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--file <PATH>` | Resolutions file | Required |
| `--format <FMT>` | Format: `json`, `yaml`, `csv` | Auto-detect |
| `--dry-run` | Preview import | `false` |
| `--conflict <MODE>` | Conflict handling: `skip`, `update`, `error` | `skip` |

#### Examples

```bash
# Import resolutions
stella unknowns import --file resolutions.json

# Preview import
stella unknowns import --file resolutions.json --dry-run

# Update existing
stella unknowns import --file resolutions.json --conflict update
```

---

## 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_WORKSPACE` | Default workspace ID |

---

## Exit Codes

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

---

## Workflows

### Daily Triage Workflow

```bash
# 1. Check summary
stella unknowns summary --workspace-id $WS_ID

# 2. List high-priority pending
stella unknowns list --status pending --min-score 7

# 3. Review and escalate critical items
stella unknowns escalate --id unknown-001 \
  --reason "Security review needed" \
  --severity high

# 4. Bulk resolve known patterns
stella unknowns bulk-triage --file daily-resolutions.json
```

### Weekly Report Export

```bash
# Export all unknowns with history
stella unknowns export \
  --workspace-id $WS_ID \
  --include-history \
  --output weekly-unknowns-$(date +%Y%m%d).json
```

---

## Related Documentation

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

---

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