CLI Command Reference

Audience: DevEx engineers, operators, and CI authors integrating the stella CLI into vulnerability-scanning and release-control workflows. Scope: Synopsis, options, exit codes, and offline notes for the lock-validation, knowledge-search, policy-lifecycle, and verification command families, plus the withdrawn AOC commands.

The commands in this reference enforce the AOC guardrails described in the Aggregation-Only Contract reference and the CLI architecture overview. They consume Authority-issued tokens with tenant scopes and never mutate ingestion stores.

For per-command deep dives, see the commands/ guides. For the canonical exit-code contract, see Output and exit codes.

1 · Prerequisites

• CLI version: stella ≥ 0.19.0 (AOC feature gate enabled).
• Required scopes (bearer tokens; DPoP is not implemented in the CLI):
  • advisory:read for Concelier sources.
  • vex:read for Excititor sources (optional but required for VEX checks).
  • aoc:verify, which Authority requires alongside advisory:read and vex:read.
  • tenant:select if your deployment uses tenant switching.
• Connectivity: direct access to Concelier/Excititor APIs or an Offline Kit snapshot (see the offline notes in each section).
• Environment: set STELLA_AUTHORITY_URL, STELLA_TENANT, and export a valid OpTok via stella auth login or an existing token cache.

2 · AdvisoryAI knowledge search

The AdvisoryAI Knowledge Search (AKS) commands expose deterministic retrieval from AdvisoryAI (docs|api|doctor) without requiring an LLM.

2.1 stella search

stella search "<query>" \
  [--type docs|api|doctor] \
  [--product <product>] \
  [--version <version>] \
  [--service <service>] \
  [--tag <tag>] \
  [--k <1-100>] \
  [--json]

Notes:

• --type and --tag are repeatable or comma-separated.
• --json emits a stable, machine-readable payload with results[].open.

2.2 stella doctor suggest

stella doctor suggest "<symptom-or-error>" \
  [--product <product>] \
  [--version <version>] \
  [--k <1-100>] \
  [--json]

Uses the same AKS index and prints grouped recommendations for:

• Doctor checks (with run command).
• Related docs anchors.
• Related API operations.

2.3 stella advisoryai index rebuild

stella advisoryai index rebuild [--json]

Rebuilds the deterministic AKS index from local markdown, OpenAPI, and Doctor metadata sources.

2.4 stella advisoryai sources prepare

stella advisoryai sources prepare \
  [--repo-root <path>] \
  [--openapi-output <path>] \
  [--doctor-seed <path>] \
  [--doctor-controls-output <path>] \
  [--overwrite] \
  [--json]

Prepares deterministic AKS source artifacts before an index rebuild:

• aggregated OpenAPI artifact output path
• doctor controls projection JSON, enriched from the configured seed plus discovered Doctor check catalog metadata when available

The reviewed docs manifest is generated by python tools/scripts/validate/check-advisoryai-docs-manifest.py --write; sources prepare leaves it unchanged. Configure STELLAOPS_BACKEND_URL to the Gateway URL and use normal online settings. An empty cache or --overwrite fetches the Gateway’s merged document from /openapi.json. Without --overwrite, preparation reuses a structurally valid existing snapshot and reports fromCache=true; that result establishes local cache reuse. Failed retrieval leaves a good OpenAPI output unchanged and stops before Doctor controls are written. The API command guide describes runtime composition, cache validation and per-service downloads.

3 · sources ingest (withdrawn)

Withdrawn on 2026-10-01 (SPRINT_20260928_008 PCD-153). The command posted documents to api/aoc/ingest/dry-run, a route no Stella Ops service maps, so it failed against every backend. Nothing replaces it. The sources group keeps the read-only generation status command, sources status.

4 · aoc verify (withdrawn)

Withdrawn on 2026-10-01 (SPRINT_20260928_008 PCD-153). The command posted to api/aoc/verify, a route no Stella Ops service maps. Platform’s /api/v1/aoc/* compatibility endpoints, mapped only in Development and testing environments with fixed responses, were not a verification backend and were withdrawn on 2026-10-08 (SPRINT_20261007_002 CCP-004). The CLI no longer registers an aoc command group. See the aoc command guide.

5 · stella node lock-validate

5.1 Synopsis

stella node lock-validate \
  [--path <directory>] \
  [--format table|json] \
  [--verbose]

5.2 Description

Runs the Node analyzer locally against a working directory to compare lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock) with what is actually present in node_modules. The command is read-only and never schedules a scan; it reuses the same deterministic collector that powers Scanner so results match backend evidence. Output highlights two conditions that policy cares about:

• Declared Only – packages present in lockfiles but missing from the filesystem or final image.
• Missing Lock – packages discovered at runtime without corresponding lock metadata (no registry provenance, integrity hash, or repository information).

This helps catch drift before images are built, keeps lockfiles trustworthy, and feeds policy predicates such as node.lock.declaredMissing.

5.3 Options

5.4 Output & exit codes

• table mode prints a summary row and two sections: Declared Only (red) and Missing Lock (yellow). Columns show package, version, lock source/locator, and filesystem path so engineers can reconcile quickly.
• json mode emits { declaredOnly: [], missingLockMetadata: [], totalDeclared, totalInstalled }, mirroring the analyzer telemetry.

Exit codes:

The CLI also records stellaops.cli.node.lock_validate.count{outcome} so operators can monitor adoption in telemetry.

5.5 Offline notes

• Works entirely offline; point --path at a workspace checked out from an Offline Kit or build cache.
• Honors the same Surface.Validation limits configured for Scanner once those knobs (scanner.lockfiles.node.*) are deployed cluster-wide.
• Combine with stella scan by running lock validation in CI before images are built to fail fast on inconsistent manifests.

6 · stella python lock-validate

6.1 Synopsis

stella python lock-validate \
  [--path <directory>] \
  [--format table|json] \
  [--verbose]

6.2 Description

Validates Python lockfiles (currently requirements*.txt, Pipfile.lock, and poetry.lock) against what exists in site-packages. It uses the same analyzer Scanner runs, so declared-only packages, missing locks, and editable installs are detected deterministically and without internet access. This catches drift between lock manifests and baked images before scanners or policy gates fail later.

6.3 Options

6.4 Output & exit codes

Output shape mirrors the Node command: declared-only packages are shown with lock provenance, and runtime packages missing lock metadata are highlighted separately. JSON mode returns the same object schema { declaredOnly, missingLockMetadata, totalDeclared, totalInstalled }.

Exit codes follow the same contract (0 success, 1 violations, 71 for an unreadable path). Telemetry is published via stellaops.cli.python.lock_validate.count{outcome}.

6.5 Offline notes

• Works entirely offline — lockfiles and site-packages must already be present (from a venv snapshot, container rootfs, or Offline Kit).
• Honors upcoming scanner.lockfiles.python.* guardrails once Surface.Validation is wired in, so the CLI and Scanner enforce the same registry/size limits.
• Recommended CI flow: run stella python lock-validate before building containers and fail fast when declared-only packages remain.

7 · stella java lock-validate

7.1 Synopsis

stella java lock-validate \
  [--path <directory>] \
  [--format table|json] \
  [--verbose]

7.2 Description

Executes the Java language analyzer locally so Gradle gradle.lockfile, gradle/dependency-locks/**/*.lockfile, and pom.xml declarations can be compared with the jars that actually ship in a workspace. The command reuses the JavaLockFileCollector plus the JavaLanguageAnalyzer merge logic, so it emits the same DeclaredOnly and Missing Lock evidence that Scanner and Policy consume. Engineers can see which coordinates exist only in lockfiles (no jar on disk) and which installed jars lack lock metadata (no repository/provenance) before a scan ever runs.

7.3 Options

7.4 Output & exit codes

Output mirrors the Node/Python verbs: Declared Only rows include the lock source/locator (e.g., gradle.lockfile, gradle/dependency-locks/app.lockfile) plus configuration/repository hints, while Missing Lock rows highlight jars that Scanner would tag with lockMissing=true. JSON responses return { declaredOnly, missingLockMetadata, totalDeclared, totalInstalled }.

Exit codes align with the other lock validators:

Telemetry is recorded via stellaops.cli.java.lock_validate.count{outcome} so adoption can be monitored alongside the Node/Python verbs.

7.5 Offline notes

• Works with any workspace (Gradle, Maven, or extracted container layers) — no network access or build-tool metadata is required at runtime.
• Honors forthcoming scanner.lockfiles.java.* Surface.Validation limits once they are deployed, so the CLI and Scanner stay in lockstep.
• Recommended CI flow: run stella java lock-validate before packaging containers to surface missing locks / declared-only coordinates early.

8 · stella vuln observations (overlay paging)

stella vuln observations lists raw advisory observations for downstream overlays (Graph Explorer, Policy simulations, Console). Large tenants can page through results deterministically.

Additional notes:

• Table mode prints a hint when hasMore is true: [yellow]More observations available. Continue with --cursor <token>[/].
• JSON mode returns nextCursor and hasMore alongside the observation list so automation can loop until hasMore is false.
• Supplying a non-positive limit falls back to the default (200). Invalid/expired cursors yield 400 Bad Request; restart without --cursor to begin a fresh iteration.

9 · Aggregation-only exit codes (withdrawn)

Exit codes 11–18 mapped ERR_AOC_00x violations for sources ingest --dry-run and aoc verify. Both commands were withdrawn on 2026-10-01 (§ 3, § 4), so no command returns these codes with that meaning. The CLI-wide contract is in Output and exit codes.

10 · Policy lifecycle quick start

• stella policy submit --policy <id> --version <n> --attach <simulation.json> --reviewers group
• stella policy review --policy <id> --version <n> --request-changes|--approve
• stella policy approve --policy <id> --version <n> --note "<justification>"
• stella policy publish --policy <id> --version <n> --reason "<why>" --ticket SEC-2048 --sign
• stella policy promote --policy <id> --version <n> --environment stage --note "<context>"
• stella policy activate --policy <id> --version <n> --note "<deployment reason>"

All publish/promote operations require interactive identities with policy:publish/policy:promote and inject attestation metadata headers (policy_reason, policy_ticket, policy_digest). See Policy Lifecycle & Approvals § 3–4 for the full workflow and compliance checklist.

11 · Authority configuration quick reference

Tokens requesting orch:operate fail with invalid_request unless both operator values are present. orch:quota tokens require quota_reason (≤256 chars) and accept an optional quota_ticket (≤128 chars). orch:backfill tokens require both backfill_reason (≤256 chars) and backfill_ticket (≤128 chars). Avoid embedding secrets in any value.

12 · stella excititor verify

12.1 Synopsis

stella excititor verify \
  [--export-id <id>] \
  [--digest <sha256>] \
  [--attestation <path>] \
  [--verbose]

At least one of --export-id, --digest, or --attestation must be supplied.

12.2 Description

Submits an artifact, digest, or attestation bundle to the Attestor service for verification. The command is available once the non-core plugin pack is installed (default in production CLI builds). It validates DSSE envelopes, Rekor proofs, and export digests without requiring operators to call Attestor APIs directly.

12.3 Options

Behaviour: When --attestation is used, the CLI loads the file into memory, encodes it as base64, and delegates verification to Attestor. Verification fails fast if the file cannot be read.

12.4 Secret rule bundle workflow

To confirm the signed secret-leak rule bundle before enabling the analyzer:

export STELLA_ATTESTOR_URL=https://attestor.internal.example      # or Offline Kit mirror

RULES_PATH=offline/rules/secrets/2025.11/secrets.ruleset.rules.jsonl
ATTESTATION_PATH=offline/rules/secrets/2025.11/secrets.ruleset.dsse.json

stella excititor verify \
  --attestation "${ATTESTATION_PATH}" \
  --digest "$(sha256sum "${RULES_PATH}" | cut -d' ' -f1)"

The Attestor response prints verification status, Rekor UUID (when available), and whether the transparency proof was validated.

12.5 Offline considerations

• Point the CLI to the Offline Kit Attestor mirror via STELLA_ATTESTOR_URL (and STELLA_AUTHORITY_URL if using sealed Authority).
• Offline kits include the mirrored Rekor log bundle required by Attestor; the CLI does not need direct Rekor connectivity.
• Always pass --digest when verifying bundles copied through removable media so mismatched payloads are detected locally before Attestor validation.

13 · stella scan entrytrace --stream-ndjson

13.1 Synopsis

stella scan entrytrace \
  --scan-id <scanId> \
  [--stream-ndjson] \
  [--include-ndjson] \
  [--verbose]

13.2 Description

Streams the EntryTrace NDJSON produced by a completed scan. When --stream-ndjson is set, the CLI sends Accept: application/x-ndjson and writes the raw lines to stdout in order, suitable for piping into AOC/ETL tools. Without the flag, the command returns the JSON envelope (scanId, imageDigest, graph, NDJSON array) and optionally prints NDJSON when --include-ndjson is set.

13.3 Examples

Stream raw NDJSON for further processing:

stella scan entrytrace --scan-id scan-123 --stream-ndjson > entrytrace.ndjson

Retrieve the JSON envelope (default behaviour):

stella scan entrytrace --scan-id scan-123

14 · Related references

• Aggregation-Only Contract reference
• Platform architecture overview
• Console operator guide
• Authority scopes
• Task Pack CLI profiles
• Output and exit codes

Last updated: 2025-11-05 (Sprint 101).