stella CLI — Parity Matrix
This page maps each stella command surface to the Stella Ops service API behind it, the output contract it must honour, and its offline behaviour. It is the reference for CLI maintainers and reviewers verifying that the CLI stays faithful to the services it fronts. Every row must stay deterministic and aggregation-only: the CLI surfaces published evidence and never infers verdicts of its own.
| Area | Server/API | CLI command(s) | Output contract | Offline support | Notes |
|---|---|---|---|---|---|
| Policy eval/simulate | Policy Engine /policy/eval /policy/simulate | stella policy eval, stella policy simulate | Stable JSON/NDJSON; includes correlationId, policyVersion, rationaleIds | Must run with cached bundles when --offline | No verdict inference beyond engine response. |
| VEX consensus | Vulnerabilities hub GET /api/vulnerabilities/v1/issues/{id}/{productKey}/facts | stella vex explain | One issue per call; every statement, the effective status, winning issuers, contested flag and decision hash | None; the command reads the hub | Global consensus with default issuer tiers; tenant VEX decisions are not applied. |
| Vulnerability list/detail | Vuln Explorer /vuln | stella vuln list, stella vuln get | Sorted by vulnId; includes provenance pointers; no missing fields inferred | Must respect --offline using cached snapshots | |
| Export/mirror bundles | Export Service /export/* | stella export mirror, stella export verify | Emits manifest + checksums; verification errors are deterministic | Yes (air-gap bundles) | All paths must be relative and normalized. |
| Air-gap import/export | AirGap /airgap/* | stella airgap import, stella airgap export | Returns sealed bundle IDs, provenance hashes | Yes; network calls forbidden when --offline or sealed mode | |
| Attestor transparency mirror | Evidence /api/evidence/v1/transparency/* (attest:read for GET, attest:create for POST); receipt list/show use /api/evidence/v1/attestations and /{uuid} with attest:read | stella attestor transparency targets, stella attestor transparency sync, stella attestor transparency receipts, stella airgap exchange transparency | JSON preserves localTransparencyReceipt, externalMirrorReceipts[], proof readError and checkpoint signedNote; package writer preserves signed file bytes plus descriptor | Yes for manual exchange; connected live sync is refused in offline/sealed mode | Dry-run is the default for connected sync; live sync requires --confirm-egress-window. Unavailable Evidence fails without a package. |
| Task Runner | TaskRunner /runs | stella task-runner run, stella task-runner logs | Monotonic log stream; stable ordering by sequence | Local/log-only when offline; remote requires connectivity | |
| Attestations | Attestor /attest/* | stella attest verify, stella attest list | Verification results include DSSE status, signature details; no risk scoring | Yes, using cached trust roots/bundles | |
| SBOM | Scanner /sbom/* | stella sbom generate, stella sbom compose | Emits SPDX/CycloneDX + hashes; preserves ordering | Yes; reads local images/files when offline |
Receipt caller correction verified against commit 6aff2f8ece7ccdfaeee4a237c9f17a24713df050 (2026-10-07): PCD-465 corrects both native Evidence paths and requests attest:read independently of the configured default scope. List filters, paging, UUID escaping, best-effort refresh and local/external receipt fields are preserved. Re-verify with the receipt contract tests named in the CLI architecture. The fourteen external operations remain separately accepted by PCD-428. Deployed gateway routing, proof validity and owner tenant isolation remain outside this caller proof; the Evidence tenant-read residual is assigned to PCD-500. Empty configured scope can grant allowed scopes; the red scope controls used an explicit unrelated configured scope.
Validation checklist
- Commands echo correlation/trace IDs on errors (verbose mode) to match server logs.
- Exit codes follow the contract in output-and-exit-codes.md.
- When a server feature is unavailable offline, the CLI must fail with exit code 5 and an actionable message.