git.stella-ops.org/docs/cli/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):

```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/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).*