CLI Exceptions Guide

Audience: operators and CI authors who manage vulnerability-exception governance from the terminal or a pipeline.

The stella exceptions command group manages exception governance objects — listing, inspecting, creating, promoting, revoking, importing, and exporting them. Exceptions are tenant-scoped and designed to be time-bound and auditable: every state change is recorded, and exports can be signed for downstream verification.

Common Options

--tenant, -t — tenant scope for the operation
--json — output structured JSON (where supported)
--verbose — print additional diagnostic context

Commands

List

stella exceptions list

Filters:

--vuln <id> — CVE or alias
--scope-type <purl|image|component|tenant>
--scope-value <value> — purl string, image ref, component key, etc.
--status, -s <draft|staged|active|expired|revoked> (repeatable)
--owner <string>
--effect <suppress|defer|downgrade|requireControl>
--expiring-within-days <n>
--include-expired
--page-size <n> (default: 50)
--page-token <token>
--csv — output CSV (implies structured output)

Show

stella exceptions show <exception-id>

Create

stella exceptions create --vuln <id> --scope-type <type> --scope-value <value> --effect <effect> --justification <text> --owner <owner>

Options:

--expiration <iso8601|+30d|+90d> — expiration date/time or relative duration
--evidence <type:uri> (repeatable) — evidence references
--policy <policy-id-or-version> — bind exception to a policy profile/version
--stage — create directly as staged (skip draft)

Promote

stella exceptions promote <exception-id>

Options:

--target <staged|active> — target status (default: next stage)
--comment <text> — audit log comment

Revoke

stella exceptions revoke <exception-id>

Options:

--reason <text> — audit log reason

Import

stella exceptions import <file>

Imports exceptions from an NDJSON file.

Options:

--stage (default: true) — import as staged
--source <label> — source label stored with imported records

Export

stella exceptions export --output <path>

Options:

--status, -s <...> (repeatable) — filter by status
--format <ndjson|json> (default: ndjson)
--signed — request a signed export (DSSE) when Attestor is enabled

Offline / Air-Gap Usage

import and export are the primary offline workflows for moving exception sets between environments.
Prefer NDJSON for deterministic diffs and review workflows.
Keep exception data tenant-scoped; cross-tenant bundles should be treated as an explicit, audited workflow.

Exceptions API reference — the HTTP surface behind these commands.
Exception governance migration guide — schema and workflow changes.
Output and exit codes — exit-code contract for scripting these commands.
CLI command reference — the full stella verb tree.