git.stella-ops.org/docs/cli/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 and the architecture overview. 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

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`
--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)

{
  "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:

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

Stream from HTTPS and emit JSON for CI:

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

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`
--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)

{
  "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
}

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:

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

CI pipeline focusing on errant sources and exporting evidence:

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):

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
• Architecture overview
• Console AOC dashboard
• Authority scopes

---

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).

---

Last updated: 2025-10-29 (Sprint 24).

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.

Tokens requesting orch:operate will fail with invalid_request unless both values are present. Choose concise strings (≤256 chars for reason, ≤128 chars for ticket) and avoid sensitive data.