git.stella-ops.org/docs/modules/cli/guides/cli-reference.md

# CLI AOC Commands Reference

> **Audience:** DevEx engineers, operators, and CI authors integrating the `stella` CLI with Aggregation-Only Contract (AOC) workflows.  
> **Scope:** Command synopsis, options, exit codes, and offline considerations for `stella sources ingest --dry-run` and `stella aoc verify` as introduced in Sprint 19.

Both commands are designed to enforce the AOC guardrails documented in the [aggregation-only reference](../../../ingestion/aggregation-only-contract.md) and the [architecture overview](../architecture.md). They consume Authority-issued tokens with tenant scopes and never mutate ingestion stores.

---

## 1 · Prerequisites

- CLI version: `stella` ≥ 0.19.0 (AOC feature gate enabled).
- Required scopes (DPoP-bound):
  - `advisory:read` for Concelier sources.
  - `vex:read` for Excititor sources (optional but required for VEX checks).
  - `aoc:verify` to invoke guard verification endpoints.
  - `tenant:select` if your deployment uses tenant switching.
- Connectivity: direct access to Concelier/Excititor APIs or Offline Kit snapshot (see § 4).
- Environment: set `STELLA_AUTHORITY_URL`, `STELLA_TENANT`, and export a valid OpTok via `stella auth login` or existing token cache.

---

## 2 · `stella sources ingest --dry-run`

### 2.1 Synopsis

```bash
stella sources ingest --dry-run \
  --source <source-key> \
  --input <path-or-uri> \
  [--tenant <tenant-id>] \
  [--format json|table] \
  [--no-color] \
  [--output <file>]
```

### 2.2 Description

Previews an ingestion write without touching MongoDB. The command loads an upstream advisory or VEX document, computes the would-write payload, runs it through the `AOCWriteGuard`, and reports any forbidden fields, provenance gaps, or idempotency issues. Use it during connector development, CI validation, or while triaging incidents.

### 2.3 Options

| Option | Description |
|--------|-------------|
| `--source <source-key>` | Logical source name (`redhat`, `ubuntu`, `osv`, etc.). Mirrors connector configuration. |
| `--input <path-or-uri>` | Path to local CSAF/OSV/VEX file or HTTPS URI. CLI normalises transport (gzip/base64) before guard evaluation. |
| `--tenant <tenant-id>` | Overrides default tenant for multi-tenant deployments. Mandatory when `STELLA_TENANT` is not set. |
| `--format json|table` | Output format. `table` (default) prints summary with highlighted violations; `json` emits machine-readable report (see below). |
| `--no-color` | Disables ANSI colour output for CI logs. |
| `--output <file>` | Writes the JSON report to file while still printing human-readable summary to stdout. |

### 2.4 Output schema (JSON)

```json
{
  "source": "redhat",
  "tenant": "default",
  "guardVersion": "1.0.0",
  "status": "ok",
  "document": {
    "contentHash": "sha256:…",
    "supersedes": null,
    "provenance": {
      "signature": { "format": "pgp", "present": true }
    }
  },
  "violations": []
}
```

When violations exist, `status` becomes `error` and `violations` contains entries with `code` (`ERR_AOC_00x`), a short `message`, and JSON Pointer `path` values indicating offending fields.

### 2.5 Exit codes

| Exit code | Meaning |
|-----------|---------|
| `0` | Guard passed; would-write payload is AOC compliant. |
| `11` | `ERR_AOC_001` – Forbidden field (`severity`, `cvss`, etc.) detected. |
| `12` | `ERR_AOC_002` – Merge attempt (multiple upstream sources fused). |
| `13` | `ERR_AOC_003` – Idempotency violation (duplicate without supersedes). |
| `14` | `ERR_AOC_004` – Missing provenance fields. |
| `15` | `ERR_AOC_005` – Signature/checksum mismatch. |
| `16` | `ERR_AOC_006` – Effective findings present (Policy-only data). |
| `17` | `ERR_AOC_007` – Unknown top-level fields / schema violation. |
| `70` | Transport error (network, auth, malformed input). |

> Exit codes map directly to the `ERR_AOC_00x` table for scripting consistency. Multiple violations yield the highest-priority code (e.g., 11 takes precedence over 14).

### 2.6 Examples

Dry-run a local CSAF file:

```bash
stella sources ingest --dry-run \
  --source redhat \
  --input ./fixtures/redhat/RHSA-2025-1234.json
```

Stream from HTTPS and emit JSON for CI:

```bash
stella sources ingest --dry-run \
  --source osv \
  --input https://osv.dev/vulnerability/GHSA-aaaa-bbbb \
  --format json \
  --output artifacts/osv-dry-run.json

cat artifacts/osv-dry-run.json | jq '.violations'
```

### 2.7 Offline notes

When operating in sealed/offline mode:

- Use `--input` paths pointing to Offline Kit snapshots (`offline-kit/advisories/*.json`).
- Provide `--tenant` explicitly if the offline bundle contains multiple tenants.
- The command does not attempt network access when given a file path.
- Store reports with `--output` to include in transfer packages for policy review.

---

## 3 · `stella aoc verify`

### 3.1 Synopsis

```bash
stella aoc verify \
  [--since <iso8601|duration>] \
  [--limit <count>] \
  [--sources <list>] \
  [--codes <ERR_AOC_00x,...>] \
  [--format table|json] \
  [--export <file>] \
  [--tenant <tenant-id>] \
  [--no-color]
```

### 3.2 Description

Replays the AOC guard against stored raw documents. By default it checks all advisories and VEX statements ingested in the last 24 hours for the active tenant, reporting totals, top violation codes, and sample documents. Use it in CI pipelines, scheduled verifications, or during incident response.

### 3.3 Options

| Option | Description |
|--------|-------------|
| `--since <value>` | Verification window. Accepts ISO 8601 timestamp (`2025-10-25T12:00:00Z`) or duration (`48h`, `7d`). Defaults to `24h`. |
| `--limit <count>` | Maximum number of violations to display (per code). `0` means show all. Defaults to `20`. |
| `--sources <list>` | Comma-separated list of sources (`redhat,ubuntu,osv`). Filters both advisories and VEX entries. |
| `--codes <list>` | Restricts output to specific `ERR_AOC_00x` codes. Useful for regression tracking. |
| `--format table|json` | `table` (default) prints summary plus top violations; `json` outputs machine-readable report identical to the `/aoc/verify` API. |
| `--export <file>` | Writes the JSON report to disk (useful for audits/offline uploads). |
| `--tenant <tenant-id>` | Overrides tenant context. Required for cross-tenant verifications when run by platform operators. |
| `--no-color` | Disables ANSI colours. |

`table` mode prints a summary showing the active tenant, evaluated window, counts of checked advisories/VEX statements, the active limit, total writes/violations, and whether the page was truncated. Status is colour-coded as `ok`, `violations`, or `truncated`. When violations exist the detail table lists the code, total occurrences, first sample document (`source` + `documentId` + `contentHash`), and JSON pointer path.

### 3.4 Report structure (JSON)

```json
{
  "tenant": "default",
  "window": {
    "from": "2025-10-25T12:00:00Z",
    "to": "2025-10-26T12:00:00Z"
  },
  "checked": {
    "advisories": 482,
    "vex": 75
  },
  "violations": [
    {
      "code": "ERR_AOC_001",
      "count": 2,
      "examples": [
        {
          "source": "redhat",
          "documentId": "advisory_raw:redhat:RHSA-2025:1",
          "contentHash": "sha256:…",
          "path": "/content/raw/cvss"
        }
      ]
    }
  ],
  "metrics": {
    "ingestion_write_total": 557,
    "aoc_violation_total": 2
  },
  "truncated": false
}
```

---

## 4 · `stella node lock-validate`

### 4.1 Synopsis

```bash
stella node lock-validate \
  [--path <directory>] \
  [--format table|json] \
  [--verbose]
```

### 4.2 Description

Runs the Node analyzer locally against a working directory to compare lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) with what is actually present in `node_modules`. The command is read-only and never schedules a scan; it reuses the same deterministic collector that powers Scanner so results match backend evidence. Output highlights two conditions that policy cares about:

- **Declared Only** – packages present in lockfiles but missing from the filesystem or final image.
- **Missing Lock** – packages discovered at runtime without corresponding lock metadata (no registry provenance, integrity hash, or repository information).

This helps catch drift before images are built, keeps lockfiles trustworthy, and feeds policy predicates such as `node.lock.declaredMissing`.

### 4.3 Options

| Option | Description |
|--------|-------------|
| `--path`, `-p` | Directory containing `package.json` and lockfiles. Defaults to the current working directory. |
| `--format table|json` | `table` (default) renders a Spectre table with status badges; `json` prints the underlying report for CI automation. |
| `--verbose` | Enables detailed logging (shared root option). |

### 4.4 Output & exit codes

- `table` mode prints a summary row and two sections: `Declared Only` (red) and `Missing Lock` (yellow). Columns show package, version, lock source/locator, and filesystem path so engineers can reconcile quickly.
- `json` mode emits `{ declaredOnly: [], missingLockMetadata: [], totalDeclared, totalInstalled }`, mirroring the analyzer telemetry.

Exit codes:

| Code | Meaning |
|------|---------|
| `0` | No inconsistencies detected. |
| `1` | Declared-only or missing-lock packages were found. |
| `71` | The requested directory could not be read (missing path, permissions, etc.). |

The CLI also records `stellaops.cli.node.lock_validate.count{outcome}` so operators can monitor adoption in telemetry.

### 4.5 Offline notes

- Works entirely offline; point `--path` at a workspace checked out from an Offline Kit or build cache.
- Honors the same `Surface.Validation` limits configured for Scanner once those knobs (`scanner.lockfiles.node.*`) are deployed cluster-wide.
- Combine with `stella scan` by running lock validation in CI before images are built to fail fast on inconsistent manifests.

---

## 5 · `stella python lock-validate`

### 5.1 Synopsis

```bash
stella python lock-validate \
  [--path <directory>] \
  [--format table|json] \
  [--verbose]
```

### 5.2 Description

Validates Python lockfiles (currently `requirements*.txt`, `Pipfile.lock`, and `poetry.lock`) against what exists in `site-packages`. It uses the same analyzer Scanner runs so declared-only packages, missing locks, and editable installs are detected deterministically and without internet access. This catches drift between lock manifests and baked images before scanners or policy gates fail later.

### 5.3 Options

| Option | Description |
|--------|-------------|
| `--path`, `-p` | Directory containing `lib/python*/site-packages` and lockfiles. Defaults to `$PWD`. |
| `--format table|json` | `table` (default) prints a human summary; `json` emits the raw report for CI. |
| `--verbose` | Enables detailed logging. |

### 5.4 Output & exit codes

Output shape mirrors the Node command: declared-only packages are shown with lock provenance, and runtime packages missing lock metadata are highlighted separately. JSON mode returns the same object schema `{ declaredOnly, missingLockMetadata, totalDeclared, totalInstalled }`.

Exit codes follow the same contract (`0` success, `1` violations, `71` for unreadable path). Telemetry is published via `stellaops.cli.python.lock_validate.count{outcome}`.

### 5.5 Offline notes

- Works entirely offline—lockfiles and `site-packages` must already be present (from a venv snapshot, container rootfs, or Offline Kit).
- Honors upcoming `scanner.lockfiles.python.*` guardrails once Surface.Validation is wired in so CLI + Scanner enforce the same registry/size limits.
- Recommended CI flow: run `stella python lock-validate` before building containers and fail fast when declared-only packages remain.

## 6 · `stella java lock-validate`

### 6.1 Synopsis

```bash
stella java lock-validate \\
  [--path <directory>] \\
  [--format table|json] \\
  [--verbose]
```

### 6.2 Description

Executes the Java language analyzer locally so Gradle `gradle.lockfile`, `gradle/dependency-locks/**/*.lockfile`, and `pom.xml` declarations can be compared with the jars that actually ship in a workspace. The command reuses the new `JavaLockFileCollector` plus the `JavaLanguageAnalyzer` merge logic, so it emits the same `DeclaredOnly` and `Missing Lock` evidence that Scanner and Policy consume. Engineers can see which coordinates exist only in lockfiles (no jar on disk) and which installed jars lack lock metadata (no repository/provenance) before a scan ever runs.

### 6.3 Options

| Option | Description |
|--------|-------------|
| `--path`, `-p` | Directory containing jars (e.g., `build/libs`) and lockfiles. Defaults to the current working directory. |
| `--format table|json` | `table` (default) renders the Spectre table; `json` outputs the raw `LockValidationReport`. |
| `--verbose` | Enables detailed logging and surfaces the analyzer paths being inspected. |

### 6.4 Output & exit codes

Output mirrors the Node/Python verbs: `Declared Only` rows include the lock source/locator (e.g., `gradle.lockfile`, `gradle/dependency-locks/app.lockfile`) plus configuration/repository hints, while `Missing Lock` rows highlight jars that Scanner would tag with `lockMissing=true`. JSON responses return `{ declaredOnly, missingLockMetadata, totalDeclared, totalInstalled }`.

Exit codes align with the other lock validators:

| Code | Meaning |
|------|---------|
| `0` | No inconsistencies detected. |
| `1` | Declared-only or missing-lock jars detected. |
| `71` | Directory could not be read. |

Telemetry is recorded via `stellaops.cli.java.lock_validate.count{outcome}` so adoption can be monitored alongside the Node/Python verbs.

### 6.5 Offline notes

- Works with any workspace (Gradle, Maven, or extracted container layers) – no network access or build tool metadata is required at runtime.
- Honors forthcoming `scanner.lockfiles.java.*` Surface.Validation limits once they are deployed so CLI + Scanner stay in lockstep.
- Recommended CI flow: run `stella java lock-validate` before packaging containers to surface missing locks/declared-only coordinates early.

### 3.5 Exit codes

| Exit code | Meaning |
|-----------|---------|
| `0` | Verification succeeded with zero violations. |
| `11…17` | Same mapping as § 2.5 when violations are detected. Highest-priority code returned. |
| `18` | Verification ran but results truncated (limit reached) – treat as warning; rerun with higher `--limit`. |
| `70` | Transport/authentication error. |
| `71` | CLI misconfiguration (missing tenant, invalid `--since`, etc.). |

### 3.6 Examples

Daily verification across all sources:

```bash
stella aoc verify --since 24h --format table
```

CI pipeline focusing on errant sources and exporting evidence:

```bash
stella aoc verify \
  --sources redhat,ubuntu \
  --codes ERR_AOC_001,ERR_AOC_004 \
  --format json \
  --limit 100 \
  --export artifacts/aoc-verify.json

jq '.violations[] | {code, count}' artifacts/aoc-verify.json
```

Air-gapped verification using Offline Kit snapshot (example script):

```bash
stella aoc verify \
  --since 7d \
  --format json \
  --export /mnt/offline/aoc-verify-$(date +%F).json

sha256sum /mnt/offline/aoc-verify-*.json > /mnt/offline/checksums.txt
```

### 3.7 Automation tips

- Schedule with `cron` or platform scheduler and fail the job when exit code ≥ 11.
- Pair with `stella sources ingest --dry-run` for pre-flight validation before re-enabling a paused source.
- Push JSON exports to observability pipelines for historical tracking of violation counts.

### 3.8 Offline notes

- Works against Offline Kit Mongo snapshots when CLI is pointed at the local API gateway included in the bundle.
- When fully disconnected, run against exported `aoc verify` reports generated on production and replay them using `--format json --export` (automation recipe above).
- Include verification output in compliance packages alongside Offline Kit manifests.

---

## 4 · Global exit-code reference

| Code | Summary |
|------|---------|
| `0` | Success / no violations. |
| `11` | `ERR_AOC_001` – Forbidden field present. |
| `12` | `ERR_AOC_002` – Merge attempt detected. |
| `13` | `ERR_AOC_003` – Idempotency violation. |
| `14` | `ERR_AOC_004` – Missing provenance/signature metadata. |
| `15` | `ERR_AOC_005` – Signature/checksum mismatch. |
| `16` | `ERR_AOC_006` – Effective findings in ingestion payload. |
| `17` | `ERR_AOC_007` – Schema violation / unknown fields. |
| `18` | Partial verification (limit reached). |
| `70` | Transport or HTTP failure. |
| `71` | CLI usage error (invalid arguments, missing tenant). |

Use these codes in CI to map outcomes to build statuses or alert severities.

---

## 4 · `stella vuln observations` (Overlay paging)

`stella vuln observations` lists raw advisory observations for downstream overlays (Graph Explorer, Policy simulations, Console). Large tenants can now page through results deterministically.

| Option | Description |
|--------|-------------|
| `--limit <count>` | Caps the number of observations returned in a single call. Defaults to `200`; values above `500` are clamped server-side. |
| `--cursor <token>` | Opaque continuation token produced by the previous page (`nextCursor` in JSON output). Pass it back to resume iteration. |

Additional notes:

- Table mode prints a hint when `hasMore` is `true`:  
  `[yellow]More observations available. Continue with --cursor <token>[/]`.
- JSON mode returns `nextCursor` and `hasMore` alongside the observation list so automation can loop until `hasMore` is `false`.
- Supplying a non-positive limit falls back to the default (`200`). Invalid/expired cursors yield `400 Bad Request`; restart without `--cursor` to begin a fresh iteration.

---

## 5 · Related references

- [Aggregation-Only Contract reference](../../../ingestion/aggregation-only-contract.md)
- [Architecture overview](../../platform/architecture-overview.md)
- [Console AOC dashboard](../../../ui/console.md)
- [Authority scopes](../../authority/architecture.md)
- [Task Pack CLI profiles](./packs-profiles.md)

---

## 6 · Compliance checklist

- [ ] Usage documented for both table and JSON formats.
- [ ] Exit-code mapping matches `ERR_AOC_00x` definitions and automation guidance.
- [ ] Offline/air-gap workflow captured for both commands.
- [ ] References to AOC architecture and console docs included.
- [ ] Examples validated against current CLI syntax (update post-implementation).
- [ ] Docs guild screenshot/narrative placeholder logged for release notes (pending CLI team capture).

---

## 7 · Policy lifecycle CLI quick start

- `stella policy submit --policy <id> --version <n> --attach <simulation.json> --reviewers group`
- `stella policy review --policy <id> --version <n> --request-changes|--approve`
- `stella policy approve --policy <id> --version <n> --note "<justification>"`
- `stella policy publish --policy <id> --version <n> --reason "<why>" --ticket SEC-2048 --sign`
- `stella policy promote --policy <id> --version <n> --environment stage --note "<context>"`
- `stella policy activate --policy <id> --version <n> --note "<deployment reason>"`

All publish/promote operations require interactive identities with `policy:publish`/`policy:promote` and inject attestation metadata headers (`policy_reason`, `policy_ticket`, `policy_digest`). See [Policy Lifecycle & Approvals](../../../policy/lifecycle.md) § 3–4 for the full workflow and compliance checklist.

---

## 13. Authority configuration quick reference

| Setting | Purpose | How to set |
|---------|---------|------------|
| `StellaOps:Authority:OperatorReason` | Incident/change description recorded with `orch:operate` tokens. | CLI flag `--Authority:OperatorReason=...` or env `STELLAOPS_ORCH_REASON`. |
| `StellaOps:Authority:OperatorTicket` | Change/incident ticket reference paired with orchestrator control actions. | CLI flag `--Authority:OperatorTicket=...` or env `STELLAOPS_ORCH_TICKET`. |
| `StellaOps:Authority:QuotaReason` | Required justification recorded with `orch:quota` tokens. | CLI flag `--Authority:QuotaReason=...` or env `STELLAOPS_ORCH_QUOTA_REASON`. |
| `StellaOps:Authority:QuotaTicket` | Optional change ticket/reference accompanying quota adjustments. | CLI flag `--Authority:QuotaTicket=...` or env `STELLAOPS_ORCH_QUOTA_TICKET`. |
| `StellaOps:Authority:BackfillReason` | Required justification recorded with `orch:backfill` tokens. | CLI flag `--Authority:BackfillReason=...` or env `STELLAOPS_ORCH_BACKFILL_REASON`. |
| `StellaOps:Authority:BackfillTicket` | Required ticket/reference accompanying historical backfill runs. | CLI flag `--Authority:BackfillTicket=...` or env `STELLAOPS_ORCH_BACKFILL_TICKET`. |
| `StellaOps:Authority:Scope` | Default scope string requested during `stella auth login`. | CLI flag `--Authority:Scope=\"packs.read packs.run\"` or env `STELLAOPS_AUTHORITY_SCOPE`; see `docs/modules/cli/guides/packs-profiles.md` for common Task Pack profiles. |

> Tokens requesting `orch:operate` fail with `invalid_request` unless both operator values are present. `orch:quota` tokens require `quota_reason` (≤256 chars) and accept an optional `quota_ticket` (≤128 chars). `orch:backfill` tokens require both `backfill_reason` (≤256 chars) and `backfill_ticket` (≤128 chars). Avoid embedding secrets in any value.

---

## 14 · `stella excititor verify`

### 14.1 Synopsis

```bash
stella excititor verify \
  [--export-id <id>] \
  [--digest <sha256>] \
  [--attestation <path>] \
  [--verbose]
```

At least one of `--export-id`, `--digest`, or `--attestation` must be supplied.

### 14.2 Description

Submits an artifact, digest, or attestation bundle to the Attestor service for verification. The command is available once the non-core plugin pack is installed (default in production CLI builds). It validates DSSE envelopes, Rekor proofs, and export digests without requiring operators to call Attestor APIs directly.

### 14.3 Options

| Option | Description |
|--------|-------------|
| `--export-id <id>` | Verify a previously issued Excititor export by identifier. |
| `--digest <sha256>` | Expected SHA-256 digest of the artifact or attestation payload. Added to the verification payload for additional integrity checks. |
| `--attestation <path>` | Path to a DSSE or in-toto bundle. The CLI base64-encodes the file and streams it to Attestor for verification. |
| `--verbose` | Enables debug logging. |

> **Behaviour:** When `--attestation` is used the CLI loads the file into memory, encodes it as base64, and delegates verification to Attestor. Verification fails fast if the file cannot be read.

### 14.4 Secret rule bundle workflow

To confirm the signed secret-leak rule bundle before enabling the analyzer:

```bash
export STELLA_ATTESTOR_URL=https://attestor.internal.example      # or Offline Kit mirror

RULES_PATH=offline/rules/secrets/2025.11/secrets.ruleset.rules.jsonl
ATTESTATION_PATH=offline/rules/secrets/2025.11/secrets.ruleset.dsse.json

stella excititor verify \
  --attestation "${ATTESTATION_PATH}" \
  --digest "$(sha256sum "${RULES_PATH}" | cut -d' ' -f1)"
```

The Attestor response prints verification status, Rekor UUID (when available), and whether the transparency proof was validated.

### 14.5 Offline considerations

- Point the CLI to the Offline Kit Attestor mirror via `STELLA_ATTESTOR_URL` (and `STELLA_AUTHORITY_URL` if using sealed Authority).
- Offline kits include the mirrored Rekor log bundle required by Attestor; the CLI does not need direct Rekor connectivity.
- Always pass `--digest` when verifying bundles copied through removable media so mismatched payloads are detected locally before Attestor validation.

---

*Last updated: 2025-11-05 (Sprint 101).*