# stella CLI — Overview

## What it does
- Single entrypoint for scans, exports, policy management, VEX/Vuln queries, air-gapped kit operations, and task-runner interactions.
- Evidence-preserving: the CLI never mutates upstream evidence; it emits signed manifests and deterministic JSON/NDJSON where possible.
- Offline-ready: every command must run with cached feeds/bundles when `STELLA_OFFLINE=1` or `--offline` is set.

## Core verbs (at a glance)
- `stella scan ...` — container/dir scans; emits SBOM + findings bundles.
- `stella policy ...` — push/eval/simulate policy bundles; attach evidence; request rationale.
- `stella vex ...` / `stella vuln ...` — query VEX consensus and vulnerability projections with pagination/budgets.
- `stella export ...` — mirror/export bundles; verify signatures; produce checksums/attestations.
- `stella airgap ...` — import/export sealed bundles; validate trust roots; run without network.
- `stella task-runner ...` — submit/inspect pack runs; stream logs; collect artefacts.

## Imposed rules (apply to every command)
- Determinism first: stable ordering, UTC ISO-8601 timestamps, no host-specific paths in outputs.
- Aggregation-only: if a command shows advisory/VEX data, it must not infer verdicts beyond published evidence.
- Offline/air-gap parity: every feature documents its offline flag(s) and expected cache locations.

## Quick start
```bash
stella --help           # top-level verbs
stella scan image ghcr.io/acme/app:1.2.3 --output json --offline
stella policy eval --input policy.bundle.json --subject sbom.spdx.jsonl --explain
stella export mirror --bundle out/mirror.tgz --verify
```

## Where to read next
- Configuration precedence and file locations: `configuration.md`
- Output formats and exit codes: `output-and-exit-codes.md`
- Command-specific guides: see `cli-reference.md` and verb-specific guides under `guides/`.