Stella CLI — Policy Commands

Audience: Policy authors, reviewers, operators and CI engineers. Lifecycle source verified: 05534daa6eb60609d9b716f7a7c1db38adb74551 (2026-08-31). CLI parser/client existence is not backend availability. The registered Engine lifecycle is documented in the Policy lifecycle guide. Governance requirement: Real review, lint, coverage, shadow/determinism and trusted publication evidence remain required. The current CLI/Engine does not provide the advertised Registry workflow; do not manufacture attachments or successful transitions. Scope correction: Engine pack metadata/bundle operations require policy:edit, reads require policy:read, activation requires policy:activate. Do not remove policy:edit based on the superseded scope guidance. Use the existing configured Authority credential flow for the intended tenant; tenant headers are not an authorization override.

This refresh verifies local authoring and lifecycle parser/client boundaries only. Other command and run-system examples remain reference material requiring their own source/runtime checks.

1 · Global Options & Output Modes

All stella policy * commands honour the common CLI options:

Tip: Set STELLA_PROFILE=policy in CI to load saved defaults from ~/.stella/profiles/policy.toml.

2 · Authoring & Drafting Commands

2.1 stella policy new

Create a local DSL file; this does not register a durable Engine Draft.

stella policy new my-policy --template baseline --output policies/my-policy.stella --fixtures

The parser takes a positional name, --template, --output, optional --description, repeatable --tag, --shadow, --fixtures and optional --git-init. The template’s shadow setting is not a successful live shadow run. Do not initialize a repository or overwrite an existing file unless that local authoring action is intended.

2.2 stella policy edit

Edit a local file:

stella policy edit policies/my-policy.stella

The supported options are --commit, --version <semver>, --message and --no-validate. These concern local validation/Git authoring, not an Engine integer revision, automatic upload or reviewer approval. Committing remains a separate authorized Git operation.

2.3 stella policy lint

Static validation without submitting.

stella policy lint policies/P-7.stella --format json

Outputs diagnostics (line/column, code, message). Exit codes:

2.4 stella policy compile

The parser accepts a local DSL file, not a policy id with an Engine revision:

stella policy compile policies/my-policy.stella

This local compilation is not a durable bundle upload or an approval. Use the canonical Engine procedure for Draft metadata and bundle storage.

3 · Lifecycle Workflow

3.1 Registry commands: parsed, but no registered Engine workflow

The current parser contains the following forms. They are client syntax references, not instructions for a working Engine review/publication sequence:

Reviewer quorum/separation, shadow/coverage and reason/ticket/signature requirements remain governance obligations. Do not infer their enforcement from command names or provide invented evidence to make an unavailable workflow appear complete.

3.2 Activation client mismatch

The parser accepts stella policy activate <id> --version <n> --note <text> and also --run-now, --scheduled-at, --priority, --rollback and --incident. However, BackendOperationsClient.ActivatePolicyRevisionAsync sends POST api/policy/policies/{id}/versions/{n}:activate. The Engine and Gateway map POST /api/policy/packs/{packId}/revisions/{version}:activate, not that client route.

Do not use the current CLI activation command as the Engine acceptance procedure. Use the canonical HTTP lifecycle with its exact scopes, Approved state and persisted actor requirement. The Engine body only consumes comment; it does not implement the client’s scheduling/run/rollback fields as effects.

The CLI maps pending_second_approval to exit 75 and other returned status strings to exit 0. That mapping is not proof of successful activation; verify the actual response and the consumer. There is no policy archive command in this parser or archive transition in the pack API.

3.3 Source re-verification

From the repository root, inspect the enclosing methods after these searches:

rg -n 'new Command\("(new|edit|lint|compile|submit|review|approve|publish|activate|rollback)"' src/Cli/StellaOps.Cli/Commands/CommandFactory.cs
rg -n 'ActivatePolicyRevisionAsync|SubmitPolicyForReviewAsync|ApprovePolicyReviewAsync|PublishPolicyAsync|api/policy/policies/' src/Cli/StellaOps.Cli/Services/BackendOperationsClient.cs
rg -n 'MapPost|RequireStellaOpsScopes|ActivatePolicyRevisionRequest' src/Policy/StellaOps.Policy.Engine/Endpoints/PolicyPackEndpoints.cs

No CLI build, command execution or live mutation is claimed by this documentation verification.

4 · Simulation & Runs

4.1 Simulate — not Registry lifecycle acceptance

The example below is historical run-system reference, not proof of an available Registry simulation/shadow backend. Check GET /policy/capabilities; do not run this sequence expecting a durable review or shadow receipt while that capability is unavailable.

stella policy simulate P-7 \
  --base 3 --candidate 4 \
  --sbom sbom:S-42 --sbom sbom:S-318 \
  --env exposure=internet --env sealed=false \
  --format json --output sims/P-7-v4-vs-v3.json

Output fields (JSON):

{
  "diff": {
    "added": 12,
    "removed": 8,
    "unchanged": 657,
    "bySeverity": {
      "Critical": {"up": 1, "down": 0},
      "High": {"up": 3, "down": 4}
    }
  },
  "explainUri": "blob://policy/P-7/simulations/2025-10-26.json"
}

Schema reminder: CLI commands surface objects defined in src/Scheduler/__Libraries/StellaOps.Scheduler.Models/docs/SCHED-MODELS-20-001-POLICY-RUNS.md; use the samples in docs/samples/api/scheduler/ for contract validation when extending output parsing.

Exit codes:

4.2 Run — historical orchestration reference

These run examples are not part of the registered Engine pack lifecycle and are not executed by activation. Verify a mapped run owner and current parser before operational use; do not treat --run-now as delivered orchestration.

stella policy run P-7 --mode full \
  --sbom sbom:S-42 --env exposure=internal-only \
  --wait --watch

Options:

stella policy run status <runId> retrieves run metadata. stella policy run list --status failed --limit 20 returns recent runs.

4.3 History

stella policy history P-7 --limit 20 --format table

The current parser describes run history, with --tenant, --from, --to, --status, --limit, --cursor and --format. It is not a Registry reviewer/approval history or a --runs lifecycle receipt.

4.4 Replay & Cancel

stella policy run replay run:P-7:2025-10-26:auto --output bundles/replay.tgz
stella policy run cancel run:P-7:2025-10-26:auto

Replay downloads sealed bundle for deterministic verification.

4.5 Schema artefacts for CLI validation

• CI publishes canonical JSON Schema exports for PolicyRunRequest, PolicyRunStatus, PolicyDiffSummary, and PolicyExplainTrace as the policy-schema-exports artifact (see .gitea/workflows/build-test-deploy.yml).
• Each run writes the files to artifacts/policy-schemas/<commit>/ and stores a unified diff (policy-schema-diff.patch) comparing them with the tracked baseline in docs/modules/policy/schemas/.
• Schema changes trigger an alert in Slack #policy-engine via the POLICY_ENGINE_SCHEMA_WEBHOOK secret so CLI maintainers know to refresh fixtures or validation rules.
• Consume these artefacts in CLI tests to keep payload validation aligned without committing generated files into the repo.

5 · Findings & Explainability

5.1 List Findings

stella findings ls --policy P-7 \
  --sbom sbom:S-42 \
  --status affected --severity High,Critical \
  --since 2025-10-01T00:00:00Z \
  --page 2 --page-size 100 \
  --format table

Common flags:

5.2 Fetch Explain

stella findings explain --policy P-7 \
  P-7:S-42:pkg:npm/lodash@4.17.21:CVE-2021-23337 \
  --mode verbose \
  --format json --output explains/lodash.json

Outputs ordered rule hits, inputs, evidence snapshots, and sealed-mode hints. Supported --mode values mirror API contracts (for example summary, verbose); omit to use backend default.

6 · Exit Codes Summary

All non-zero exits emit structured error envelope on stderr when --format json or STELLA_JSON_ERRORS=1.

7 · Offline & Air-Gap Usage

The following bundle/replay examples are historical distribution guidance, not an available Registry approval/export workflow. Verify the current command and real signed artifact before use; offline flags do not supply missing review, shadow or publication evidence.

• Use --sealed to ensure commands avoid outbound calls; required for sealed enclaves.
• stella policy bundle export --policy P-7 --version 4 --output bundles/policy-P-7-v4.bundle pairs with Offline Kit import.
• Replay bundles (run replay) are DSSE-signed; verify with stella offline verify.
• Store credentials in ~/.stella/offline.toml for non-interactive air-gapped pipelines.

8 · Compliance Checklist

• [ ] Help text synced: stella policy --help matches documented flags/examples (update during release pipeline).
• [ ] Exit codes mapped: Table above reflects CLI implementation and CI asserts mapping for ERR_POL_*.
• [ ] JSON schemas verified: Example payloads validated against OpenAPI/SDK contracts before publishing. (CI now exports canonical schemas as policy-schema-exports; wire tests to consume them.)
• [ ] Scope guidance present: Each command lists required Authority scopes.
• [ ] Offline guidance included: Sealed-mode steps and bundle workflows documented.
• [ ] Cross-links tested: Links to DSL, lifecycle, runs, and API docs resolve locally (yarn docs:lint).
• [ ] Examples no-op safe: Command examples either read-only or use placeholders (no destructive defaults).

9 · See Also

• CLI overview and quick start — orientation and installation.
• stella policy command reference — generated flag/field reference.
• Output formats and exit codes — shared exit-code contract.
• Parity matrix — how policy commands map to Policy Engine APIs and offline behaviour.

Last updated: 2025-11-26 (Sprint 307).