# CLI Developer Experience and Command UX

**Version:** 1.0
**Date:** 2025-11-29
**Status:** Canonical

This advisory defines the product rationale, command surface design, and implementation strategy for the Stella Ops CLI, covering developer experience, CI/CD integration, output formatting, and offline operation.

---

## 1. Executive Summary

The Stella Ops CLI is the **primary interface for developers and CI/CD pipelines** interacting with the platform. Key capabilities:

- **Native AOT Binary** - Sub-20ms startup, single binary distribution
- **DPoP-Bound Authentication** - Secure device-code and service principal flows
- **Deterministic Outputs** - JSON/table modes with stable exit codes for CI
- **Buildx Integration** - SBOM generation at build time
- **Offline Kit Management** - Air-gapped deployment support
- **Shell Completions** - Bash/Zsh/Fish/PowerShell auto-complete

---

## 2. Market Drivers

### 2.1 Target Segments

| Segment | CLI Requirements | Use Case |
|---------|-----------------|----------|
| **DevSecOps** | CI integration, exit codes, JSON output | Pipeline gates |
| **Security Engineers** | Verification commands, policy testing | Audit workflows |
| **Platform Operators** | Offline kit, admin commands | Air-gap management |
| **Developers** | Scan commands, buildx integration | Local development |

### 2.2 Competitive Positioning

Most CLI tools in the vulnerability space are slow or lack CI ergonomics. Stella Ops differentiates with:
- **Native AOT** for instant startup (< 20ms vs 500ms+ for JIT)
- **Deterministic exit codes** (12 distinct codes for CI decision trees)
- **DPoP security** (no long-lived tokens on disk)
- **Unified command surface** (50+ commands, consistent patterns)
- **Offline-first design** (works without network in sealed mode)

---

## 3. Command Surface Architecture

### 3.1 Command Categories

| Category | Commands | Purpose |
|----------|----------|---------|
| **Auth** | `login`, `logout`, `status`, `token` | Authentication management |
| **Scan** | `scan image`, `scan fs` | Vulnerability scanning |
| **Export** | `export sbom`, `report final` | Artifact retrieval |
| **Verify** | `verify attestation`, `verify referrers`, `verify image-signature` | Cryptographic verification |
| **Policy** | `policy get`, `policy set`, `policy apply` | Policy management |
| **Buildx** | `buildx install`, `buildx verify`, `buildx build` | Build-time SBOM |
| **Runtime** | `runtime policy test` | Zastava integration |
| **Offline** | `offline kit pull`, `offline kit import`, `offline kit status` | Air-gap operations |
| **Decision** | `decision export`, `decision verify`, `decision compare` | VEX evidence management |
| **AOC** | `sources ingest`, `aoc verify` | Aggregation-only guards |
| **KMS** | `kms export`, `kms import` | Key management |
| **Advise** | `advise run` | AI-powered advisory summaries |

### 3.2 Output Modes

**Human Mode (default):**
```
$ stella scan image nginx:latest --wait
Scanning nginx:latest...
Found 12 vulnerabilities (2 critical, 3 high, 5 medium, 2 low)
Policy verdict: FAIL

Critical:
  - CVE-2025-12345 in openssl (fixed in 3.0.14)
  - CVE-2025-12346 in libcurl (no fix available)

See: https://ui.internal/scans/sha256:abc123...
```

**JSON Mode (`--json`):**
```json
{"event":"scan.complete","status":"fail","critical":2,"high":3,"medium":5,"low":2,"url":"https://..."}
```

### 3.3 Exit Codes

| Code | Meaning | CI Action |
|------|---------|-----------|
| 0 | Success | Continue |
| 2 | Policy fail | Block deployment |
| 3 | Verification failed | Security alert |
| 4 | Auth error | Re-authenticate |
| 5 | Resource not found | Check inputs |
| 6 | Rate limited | Retry with backoff |
| 7 | Backend unavailable | Retry |
| 9 | Invalid arguments | Fix command |
| 11-17 | AOC guard violations | Review ingestion |
| 18 | Verification truncated | Increase limit |
| 70 | Transport failure | Check network |
| 71 | Usage error | Fix command |

---

## 4. Authentication Model

### 4.1 Device Code Flow (Interactive)

```bash
$ stella auth login
Opening browser for authentication...
Device code: ABCD-EFGH
Waiting for authorization...
Logged in as user@example.com (tenant: acme-corp)
```

### 4.2 Service Principal (CI/CD)

```bash
$ stella auth login --client-credentials \
    --client-id $STELLA_CLIENT_ID \
    --private-key $STELLA_PRIVATE_KEY
```

### 4.3 DPoP Key Management

- Ephemeral Ed25519 keypair generated on first login
- Stored in OS keychain (Keychain/DPAPI/KWallet/Gnome Keyring)
- Every request includes DPoP proof header
- Tokens refreshed proactively (30s before expiry)

### 4.4 Token Credential Helper

```bash
# Get one-shot token for curl/scripts
TOKEN=$(stella auth token --aud scanner)
curl -H "Authorization: Bearer $TOKEN" https://scanner.internal/api/...
```

---

## 5. Buildx Integration

### 5.1 Generator Installation

```bash
$ stella buildx install
Installing SBOM generator plugin...
Verifying signature: OK
Generator installed at ~/.docker/cli-plugins/docker-buildx-stellaops

$ stella buildx verify
Docker version: 24.0.7
Buildx version: 0.12.1
Generator: stellaops/sbom-indexer:v1.2.3@sha256:abc123...
Status: Ready
```

### 5.2 Build with SBOM

```bash
$ stella buildx build -t myapp:v1.0.0 --push --attest
Building myapp:v1.0.0...
SBOM generation: enabled (stellaops/sbom-indexer)
Provenance: enabled
Attestation: requested

Build complete!
Image: myapp:v1.0.0@sha256:def456...
SBOM: attached as referrer
Attestation: logged to Rekor (uuid: abc123)
```

---

## 6. Implementation Strategy

### 6.1 Phase 1: Core Commands (Complete)

- [x] Auth commands with DPoP
- [x] Scan/export commands
- [x] JSON output mode
- [x] Exit code standardization
- [x] Shell completions

### 6.2 Phase 2: Buildx & Verification (Complete)

- [x] Buildx plugin management
- [x] Attestation verification
- [x] Referrer verification
- [x] Report commands

### 6.3 Phase 3: Advanced Features (In Progress)

- [x] Decision export/verify commands
- [x] AOC guard helpers
- [x] KMS management
- [ ] Advisory AI integration (CLI-ADVISE-48-001)
- [ ] Filesystem scanning (CLI-SCAN-49-001)

### 6.4 Phase 4: Distribution (Planned)

- [ ] Homebrew formula
- [ ] Scoop/Winget manifests
- [ ] Self-update mechanism
- [ ] Cosign signature verification

---

## 7. CI/CD Integration Patterns

### 7.1 GitHub Actions

```yaml
- name: Install Stella CLI
  run: |
    curl -sSL https://get.stella-ops.io | sh
    echo "$HOME/.stella/bin" >> $GITHUB_PATH

- name: Authenticate
  run: stella auth login --client-credentials
  env:
    STELLAOPS_CLIENT_ID: ${{ secrets.STELLA_CLIENT_ID }}
    STELLAOPS_PRIVATE_KEY: ${{ secrets.STELLA_PRIVATE_KEY }}

- name: Scan Image
  run: |
    stella scan image ${{ env.IMAGE_REF }} --wait --json > scan-results.json
    if [ $? -eq 2 ]; then
      echo "::error::Policy failed - blocking deployment"
      exit 1
    fi

- name: Verify Attestation
  run: stella verify attestation --artifact ${{ env.IMAGE_DIGEST }}
```

### 7.2 GitLab CI

```yaml
scan:
  script:
    - stella auth login --client-credentials
    - stella buildx install
    - docker buildx build --attest=type=sbom,generator=stellaops/sbom-indexer -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - stella scan image $CI_REGISTRY_IMAGE@$IMAGE_DIGEST --wait --json
  artifacts:
    reports:
      container_scanning: scan-results.json
```

---

## 8. Configuration Model

### 8.1 Precedence

CLI flags > Environment variables > Config file > Defaults

### 8.2 Config File

```yaml
# ~/.config/stellaops/config.yaml
cli:
  authority: "https://authority.example.com"
  backend:
    scanner: "https://scanner.example.com"
    attestor: "https://attestor.example.com"
  auth:
    deviceCode: true
    audienceDefault: "scanner"
  output:
    json: false
    color: auto
  tls:
    caBundle: "/etc/ssl/certs/ca-bundle.crt"
  offline:
    kitMirror: "s3://mirror/stellaops-kit"
```

### 8.3 Environment Variables

| Variable | Purpose |
|----------|---------|
| `STELLAOPS_AUTHORITY` | Authority URL |
| `STELLAOPS_SCANNER_URL` | Scanner service URL |
| `STELLAOPS_CLIENT_ID` | Service principal ID |
| `STELLAOPS_PRIVATE_KEY` | Service principal key |
| `STELLAOPS_TENANT` | Default tenant |
| `STELLAOPS_JSON` | Enable JSON output |

---

## 9. Offline Operation

### 9.1 Sealed Mode Detection

```bash
$ stella scan image nginx:latest
Error: Sealed mode active - external network access blocked
Remediation: Import offline kit or disable sealed mode

$ stella offline kit import latest-kit.tar.gz
Importing offline kit...
Advisories: 45,230 records
VEX documents: 12,450 records
Policy packs: 3 bundles
Import complete!

$ stella scan image nginx:latest
Scanning with offline data (2025-11-28)...
```

### 9.2 Air-Gap Guard

All HTTP flows route through `StellaOps.AirGap.Policy`. When sealed mode is active:
- External egress is blocked with `AIRGAP_EGRESS_BLOCKED` error
- CLI provides clear remediation guidance
- Local verification continues to work

---

## 10. Security Considerations

### 10.1 Credential Protection

- DPoP private keys stored in OS keychain only
- No plaintext tokens on disk
- Short-lived OpToks held in memory only
- Authorization headers redacted from verbose logs

### 10.2 Binary Verification

```bash
# Verify CLI binary signature
$ stella version --verify
Version: 1.2.3
Built: 2025-11-29T12:00:00Z
Signature: Valid (cosign)
Signer: release@stella-ops.io
```

### 10.3 Hard Lines

- Refuse to print token values
- Disallow `--insecure` without explicit env var opt-in
- Enforce short token TTL with proactive refresh
- Device-code cache bound to machine + user

---

## 11. Performance Targets

| Metric | Target |
|--------|--------|
| Startup time | < 20ms (AOT) |
| Request overhead | < 5ms |
| Large download (100MB) | > 80 MB/s |
| Buildx wrapper overhead | < 1ms |

---

## 12. Related Documentation

| Resource | Location |
|----------|----------|
| CLI architecture | `docs/modules/cli/architecture.md` |
| Policy CLI guide | `docs/modules/cli/guides/policy.md` |
| API/CLI reference | `docs/09_API_CLI_REFERENCE.md` |
| Offline operation | `docs/24_OFFLINE_KIT.md` |

---

## 13. Sprint Mapping

- **Primary Sprint:** SPRINT_0400_cli_ux.md (NEW)
- **Related Sprints:**
  - SPRINT_210_ui_ii.md (UI integration)
  - SPRINT_0187_0001_0001_evidence_locker_cli_integration.md (Evidence CLI)

**Key Task IDs:**
- `CLI-AUTH-10-001` - DPoP authentication (DONE)
- `CLI-SCAN-20-001` - Scan commands (DONE)
- `CLI-BUILDX-30-001` - Buildx integration (DONE)
- `CLI-ADVISE-48-001` - Advisory AI commands (IN PROGRESS)
- `CLI-SCAN-49-001` - Filesystem scanning (TODO)

---

## 14. Success Metrics

| Metric | Target |
|--------|--------|
| Startup latency | < 20ms p99 |
| CI adoption | 80% of pipelines use CLI |
| Exit code coverage | 100% of failure modes |
| Shell completion coverage | 100% of commands |
| Offline operation success | Works without network |

---

*Last updated: 2025-11-29*