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

CLI Exceptions Guide

The stella exceptions command group manages exception governance objects (list/show/create/promote/revoke/import/export). Exceptions are tenant-scoped and intended to be time-bound and auditable.

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.

Related Docs

• Exceptions API entry point: docs/api/exceptions.md
• Exception governance migration guide: docs/technical/migration/exception-governance.md