# 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/migration/exception-governance.md`