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

Stella CLI — Policy Commands

Audience: Policy authors, reviewers, operators, and CI engineers using the stella CLI to interact with Policy Engine.
Supported from: stella CLI ≥ 0.20.0 (Policy Engine v2 sprint line).
Prerequisites: Authority-issued bearer token with the scopes noted per command (export STELLA_TOKEN or pass --token). 2025-10-27 scope update: CLI/CI tokens issued prior to Sprint 23 (AUTH-POLICY-23-001) must drop policy:write/policy:submit/policy:edit and instead request policy:read, policy:author, policy:review, and policy:simulate (plus policy:approve/policy:operate/policy:activate for promotion pipelines).

---

1 · Global Options & Output Modes

All stella policy * commands honour the common CLI options:

Flag	Default	Description
--server <url>	https://stella.local	Policy Engine gateway root.
--tenant <id>	token default	Override tenant for multi-tenant installs.
--format <table|json|yaml>	table for TTY, json otherwise	Output format for listings/diffs.
--output <file>	stdout	Write full JSON payload to file.
--sealed	false	Force sealed-mode behaviour (no outbound fetch).
--trace	false	Emit verbose timing/log correlation info.

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 draft policy from a template or scratch.

stella policy new --policy-id P-7 --name "Default Org Policy" \
  --template baseline --output-path policies/P-7.stella

Options:

Flag	Description
--policy-id (required)	Stable identifier (e.g., P-7).
--name	Friendly display name.
--template	baseline, serverless, blank.
--from	Start from existing version (policyId@version).
--open	Launches $EDITOR after creation.

Writes DSL to local file and registers draft version (status=draft). Requires policy:write.

2.2 stella policy edit

Open an existing draft in the local editor.

stella policy edit P-7 --version 4

• Auto-checks out latest draft if --version omitted.
• Saves to temp file, uploads on editor exit (unless --no-upload).
• Use --watch to keep command alive and re-upload on every save.

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:

Code	Meaning
0	No lint errors.
10	Syntax/compile errors (ERR_POL_001).
11	Unsupported syntax version.

2.4 stella policy compile

Emits IR digest and rule summary.

stella policy compile P-7 --version 4

Returns JSON with digest, rules.count, action counts. Exit 0 success, 10 on compile errors.

---

3 · Lifecycle Workflow

3.1 Submit

stella policy submit P-7 --version 4 \
  --reviewer user:kay --reviewer group:sec-reviewers \
  --note "Simulated against golden SBOM set" \
  --attach sims/P-7-v4-vs-v3.json

Requires policy:submit. CLI validates that lint/compile run within 24 h and bundle attachments exist.

3.2 Review

stella policy review P-7 --version 4 --approve \
  --note "Looks good; ensure incident playbook updated."

• --approve, --request-changes, or --comment.
• Provide --blocking to mark comment as blocking.
• Requires policy:review.

3.3 Approve

stella policy approve P-7 --version 4 \
  --note "Determinism CI green; simulation diff attached." \
  --attach sims/P-7-v4-vs-v3.json

Prompts for confirmation; refuses if approver == submitter. Requires policy:approve.

3.4 Activate

stella policy activate P-7 --version 4 --run-now --priority high

• Optional --scheduled-at 2025-10-27T02:00:00Z.
• Requires policy:activate and policy:run.

Options

• --version <number> (required) – target revision to promote.
• --note <text> – record an activation note alongside the approval.
• --run-now – enqueue an immediate full run after activation.
• --scheduled-at <timestamp> – schedule activation for a specific UTC time (ISO-8601 format).
• --priority <label> – optional scheduling priority hint (low, standard, high).
• --rollback – mark the activation as a rollback of a previously active version.
• --incident <id> – associate the activation with an incident identifier.

Exit codes

Code	Meaning
0	Activation completed (or policy already active).
75	Activation recorded but awaiting a second approver.

3.5 Archive / Rollback

stella policy archive P-7 --version 3 --reason "Superseded by v4"
stella policy activate P-7 --version 3 --rollback --incident INC-2025-104

---

4 · Simulation & Runs

4.1 Simulate

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 samples/api/scheduler/ for contract validation when extending output parsing.

Exit codes:

Code	Meaning
0	Simulation succeeded; diffs informational.
20	Blocking delta (--fail-on-diff triggered).
21	Simulation input missing (ERR_POL_003).
22	Determinism guard (ERR_POL_004).
23	API/permission error (ERR_POL_002, ERR_POL_005).

4.2 Run

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

Options:

Flag	Description
--mode	full or incremental (default incremental).
--sbom	Explicit SBOM IDs (optional).
--priority	normal, high, emergency.
--wait	Poll run status until completion.
--watch	Stream progress events (requires TTY).

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

4.3 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.4 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/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:

Flag	Description
--sbom	Repeatable filter for SBOM identifiers.
--status	Repeatable filter (affected, quieted, mitigated, not_affected, etc.).
--severity	Repeatable filter using normalized labels (Critical, High, Medium, Low, Unknown).
--since	Return findings updated on/after the ISO-8601 timestamp.
--cursor	Resume listing using the opaque token from a prior page.
--page, --page-size	Page-based pagination (page >=1, size <=500; falls back to backend defaults).
--output	Persist JSON payload to disk (implied JSON rendering).
--format	table (default for TTY) or json.

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

Exit code	Description	Typical ERR codes
0	Success (command completed, warnings only).	—
10	DSL syntax/compile failure.	ERR_POL_001
11	Unsupported DSL version / schema mismatch.	ERR_POL_001
12	Approval/rbac failure.	ERR_POL_002, ERR_POL_005
20	Simulation diff exceeded thresholds (--fail-on-diff).	—
21	Required inputs missing (SBOM/advisory/VEX).	ERR_POL_003
22	Determinism guard triggered.	ERR_POL_004
23	Run canceled or timed out.	ERR_POL_006
30	Network/transport error (non-HTTP success).	—
64	CLI usage error (invalid flag/argument).	—

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

---

7 · Offline & Air-Gap Usage

• 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).

---

Last updated: 2025-10-27 (Sprint 20).