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

---

## 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`.

### 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.

---

## 5 · Findings & Explainability

### 5.1 List Findings

```
stella findings ls --policy P-7 \
  --sbom sbom:S-42 \
  --status affected --severity High,Critical \
  --format table
```

Common flags:

| Flag | Description |
|------|-------------|
| `--page`, `--page-size` | Pagination (default page size 50). |
| `--cursor` | Use cursor token from previous call. |
| `--since` | ISO timestamp filter. |

### 5.2 Fetch Explain

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

Outputs ordered rule hits, inputs, and sealed-mode hints.

---

## 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.
- [ ] **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-26 (Sprint 20).*