# stella vex - Command Guide

## Commands

- `stella vex consensus --query <filter> [--output json|ndjson|table] [--offline]`
- `stella vex get --id <consensusId> [--offline]`
- `stella vex simulate --input <vexDocs> --policy <policyConfig> [--offline]`
- `stella vex evidence export <target> [--format json|openvex] [--output <path>]`
- `stella vex webhooks list|add|remove [--format json]`
- `stella vex gen --from-drift --image <IMAGE> [--baseline <SEAL_ID>] [--output <PATH>]`

## Flags (common)
- `--offline`: use cached consensus snapshots; fail with exit code 5 if remote would be hit.
- `--policy <path>`: apply trust/weighting config; aggregation-only outputs.
- `--page-size`, `--page-token`: deterministic pagination.

## Inputs/outputs
- Inputs: VEX consensus projection (VexLens); optional cached snapshots when offline.
- Outputs: consensus states with `consensus_state`, `confidence`, `weights`, `issuers`, `rationale`; stable ordering.

## Determinism rules
- Sort by `consensusId`; pagination tokens deterministic.
- No verdict inference beyond upstream consensus projection; CLI stays aggregation-only.

## Offline/air-gap notes
- Cached snapshots are required when `--offline`; otherwise exit code 5 with remediation message.
- Trust roots for signature verification are loaded from `STELLA_TRUST_ROOTS` when verifying cached snapshots.

---

## stella vex evidence export

Export deterministic VEX evidence for a digest or component identifier.

### Usage

```bash
stella vex evidence export <target> [--format json|openvex] [--output <path>]
```

### Examples

```bash
stella vex evidence export sha256:abc --format json
stella vex evidence export pkg:npm/lodash@4.17.21 --format openvex --output vex-evidence.json
```

---

## stella vex webhooks

Manage VEX webhook subscriptions.

### Usage

```bash
stella vex webhooks list --format json
stella vex webhooks add --url <url> --events vex.created vex.updated --format json
stella vex webhooks remove <id> --format json
```

---

## stella vex gen --from-drift

**Sprint:** SPRINT_20260105_002_004_CLI

Generate VEX statements from facet drift analysis. This command analyzes drift between a baseline seal and the current image state, then generates OpenVEX documents for facets that require authorization.

### Usage

```bash
stella vex gen --from-drift --image <IMAGE> [OPTIONS]
```

### Required Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--from-drift` | | Enable drift-based VEX generation |
| `--image <REF>` | `-i` | Image reference or digest to analyze |

### Optional Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--baseline <ID>` | `-b` | Baseline seal ID for comparison | latest seal |
| `--output <PATH>` | `-o` | Output file path | stdout |
| `--format <FMT>` | `-f` | VEX format: `openvex`, `csaf` | `openvex` |
| `--status <STATUS>` | `-s` | VEX status: `under_investigation`, `not_affected`, `affected` | `under_investigation` |
| `--verbose` | `-v` | Enable verbose output | `false` |

### Examples

#### Generate VEX from drift

```bash
stella vex gen --from-drift --image sha256:abc123
```

#### Specify baseline seal

```bash
stella vex gen --from-drift --image myregistry.io/app:v2.0 --baseline seal-xyz789
```

#### Output to file with specific status

```bash
stella vex gen --from-drift --image sha256:abc123 \
  --output vex-authorization.json \
  --status not_affected
```

### Output Format (OpenVEX)

```json
{
  "@context": "https://openvex.dev/ns",
  "@id": "https://stellaops.io/vex/abc123-def456",
  "author": "StellaOps CLI",
  "timestamp": "2026-01-05T10:30:00Z",
  "version": 1,
  "statements": [
    {
      "@id": "vex:statement-1",
      "status": "under_investigation",
      "timestamp": "2026-01-05T10:30:00Z",
      "products": [
        {
          "@id": "sha256:abc123...",
          "identifiers": {
            "facet": "runtime"
          }
        }
      ],
      "justification": "Facet drift authorization for runtime. Churn: 15.50% (3 added, 1 removed, 2 modified)",
      "action_statement": "Review required before deployment"
    }
  ]
}
```

### Exit Codes

| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | Error or no baseline seal found |
| `2` | Image resolution failed |

### Workflow Integration

The `vex gen --from-drift` command is typically used in a deployment pipeline:

1. **Build**: Container image is built
2. **Seal**: `stella seal` creates baseline seal at build time
3. **Deploy**: Deployment triggers admission webhook
4. **Drift Detection**: If drift exceeds quota, deployment is blocked
5. **VEX Generation**: `stella vex gen --from-drift` creates authorization document
6. **Review**: Security team reviews and signs VEX
7. **Retry Deploy**: With VEX in place, deployment proceeds

```bash
# After deployment blocked due to drift
stella vex gen --from-drift --image $IMAGE_DIGEST \
  --output vex-authorization.json

# Review and sign the VEX document
stella vex sign --input vex-authorization.json --key $SIGNING_KEY

# Ingest the signed VEX
stella vex ingest --input vex-authorization.signed.json

# Retry deployment (webhook will now accept)
kubectl apply -f deployment.yaml
```

### Related Documentation

- [Facet Seal Command](./seal.md)
- [Facet Drift Analysis](./facet-drift.md)
- [Admission Webhook Configuration](../admin/admission-webhook.md)