# Console CLI ↔ UI Parity Matrix

> **Audience:** Docs Guild, Console Guild, CLI Guild, DevOps automation.  
> **Scope:** Track feature-level parity between the StellaOps Console and the `stella` CLI, surface pending work, and describe the parity CI check owned by CONSOLE-DOC-23-502.

Status key:

- **✅ Available** – command exists in `StellaOps.Cli` and is documented.  
- **🟡 In progress** – command implemented but still under active delivery (task status `DOING`).  
- **🟩 Planned** – command spec’d but not yet implemented (task `TODO`).  
- **⚪ UI-only** – no CLI equivalent required.  
- **🔴 Gap** – CLI feature missing with no active task; file a task before sprint exit.

---

## 1 · Navigation & Tenancy

| UI capability | CLI command(s) | Status | Notes / Tasks |
|---------------|----------------|--------|---------------|
| Login / token cache status (`/console/profile`) | `stella auth login`, `stella auth status`, `stella auth whoami` | ✅ Available | Command definitions in `CommandFactory.BuildAuthCommand`. |
| Fresh-auth challenge for sensitive actions | `stella auth fresh-auth` | ✅ Available | Referenced in `/docs/ui/admin.md`. |
| Tenant switcher (UI shell) | `--tenant` flag across CLI commands | ✅ Available | All multi-tenant commands require explicit `--tenant`. |
| Tenant creation / suspension | *(pending CLI)* | 🟩 Planned | No `stella auth tenant *` commands yet – track via `CLI-TEN-47-001` (scopes & tenancy). |

---

## 2 · Policies & Findings

| UI capability | CLI command(s) | Status | Notes / Tasks |
|---------------|----------------|--------|---------------|
| Policy simulation diff, explain | `stella policy simulate` | 🟡 In progress | Implementation present; task `CLI-POLICY-20-002` marked DOING. |
| Promote / activate policy | `stella policy promote`, `stella policy activate` | 🟩 Planned | Spec tracked under `CLI-POLICY-23-005`. |
| History & explain trees | `stella policy history`, `stella policy explain` | 🟩 Planned | `CLI-POLICY-23-006`. |
| Findings explorer export | `stella findings get`, `stella findings export` | 🟩 Planned | Part of `CLI-POLICY-20-003`. |
| Explain drawer JSON | `stella policy simulate --format json` | 🟡 In progress | Same command; JSON output flagged for CLI tests. |

---

## 3 · Runs & Evidence

| UI capability | CLI command(s) | Status | Notes / Tasks |
|---------------|----------------|--------|---------------|
| Run retry / cancel | `stella runs retry`, `stella runs cancel` | 🟩 Planned | Included in export suite task `CLI-EXPORT-35-001`. |
| Manual run submit / preview | `stella runs submit`, `stella runs preview` | 🟩 Planned | `CLI-EXPORT-35-001`. |
| Evidence bundle export | `stella runs export --run <id> --bundle` | 🟩 Planned | `CLI-EXPORT-35-001`. |
| Run status polling | `stella runs status` | 🟩 Planned | Same task. |

---

## 4 · Advisories, VEX, SBOM

| UI capability | CLI command(s) | Status | Notes / Tasks |
|---------------|----------------|--------|---------------|
| Advisory observations search | `stella vuln observations` | ✅ Available | Implemented via `BuildVulnCommand`. |
| Advisory linkset export | `stella advisory linkset show/export` | 🟩 Planned | `CLI-LNM-22-001`. |
| VEX observations / linksets | `stella vex obs get/linkset show` | 🟩 Planned | `CLI-LNM-22-002`. |
| SBOM overlay export | `stella sbom overlay apply/export` | 🟩 Planned | Scoped to upcoming SBOM CLI sprint (`SBOM-CONSOLE-23-001/002` + CLI backlog). |

---

## 5 · Downloads & Offline Kit

| UI capability | CLI command(s) | Status | Notes / Tasks |
|---------------|----------------|--------|---------------|
| Manifest lookup (Console Downloads) | `stella downloads manifest show --artifact <id>` | 🟩 Planned | Delivered with `CONSOLE-DOC-23-502` + CLI parity commands. |
| Mirror digest to OCI archive | `stella downloads mirror --artifact <id> --to <target>` | 🟩 Planned | Same task bundle (`CONSOLE-DOC-23-502`). |
| Console health check | `stella console status --endpoint <url>` | 🟩 Planned | Tracked in `CONSOLE-DOC-23-502`; interim use `curl` as documented. |
| Offline kit import/export | `stella offline kit import`, `stella offline kit export` | ✅ Available | Implemented (see `CommandHandlers.HandleOfflineKitImportAsync/HandleOfflineKitPullAsync`). |

---

## 6 · Admin & Security

| UI capability | CLI command(s) | Status | Notes / Tasks |
|---------------|----------------|--------|---------------|
| Client creation / rotation | `stella auth client create` *(planned)* | 🟩 Planned | Pending tenancy backlog `CLI-TEN-47-001`. |
| Token revoke | `stella auth revoke export/verify` | ✅ Available | Already implemented. |
| Audit export | `stella auth audit export` | 🟩 Planned | Needs CLI work item (Authority guild). |
| Signing key rotation | `stella auth signing rotate` | 🟩 Planned | To be added with AUTH-CONSOLE-23-003 follow-up. |

---

## 7 · Telemetry & Observability

| UI capability | CLI command(s) | Status | Notes / Tasks |
|---------------|----------------|--------|---------------|
| Telemetry dashboard parity | `stella obs top`, `stella obs trace`, `stella obs logs` | 🟩 Planned | CLI observability epic (`CLI-OBS-51-001`, `CLI-OBS-52-001`). |
| Incident mode toggle | `stella obs incident-mode enable|disable|status` | 🟩 Planned | CLI task `CLI-OBS-55-001`. |
| Verify console telemetry health | `stella console status --telemetry` | 🟩 Planned | Part of `CONSOLE-DOC-23-502`. |

---

## 8 · Parity Gaps & Follow-up

- **Tenant and client lifecycle CLI**: create/suspend tenants, manage clients. Coordinate with Authority CLI epic (`CLI-TEN-47-001`, `CLI-TEN-49-001`).  
- **Downloads parity commands**: blocked on `CONSOLE-DOC-23-502` and DevOps pipeline `DOWNLOADS-CONSOLE-23-001`.  
- **Policy promotion/history**: requires completion of CLI policy epic (`CLI-POLICY-23-005`/`23-006`).  
- **Runs/evidence exports**: waiting on `CLI-EXPORT-35-001`.  
- **Observability tooling**: deliver `stella obs` commands before enabling parity CI checks for telemetry.

Document updates should occur whenever a row changes status. When promoting a command from Planned → Available, ensure:

1. CLI command merged with help text.  
2. Relevant UI doc references updated to remove “pending” callouts.  
3. This matrix row status updated to ✅ and task IDs moved to release notes.

---

## 9 · Parity CI Check (CONSOLE-DOC-23-502)

- **Owner:** Docs Guild + DevEx/CLI Guild.  
- **Artefact:** Planned `.gitea/workflows/cli-parity-console.yml`.  
- **What it does:** Runs `scripts/check-console-cli-parity.sh` (to be committed with the workflow) which:
  1. Parses this matrix (YAML view exported from Markdown) to identify rows marked ✅.  
  2. Executes `stella --help` to confirm listed commands exist.  
  3. Optionally triggers smoke commands in sandbox mode (e.g., `stella policy simulate --help`).  
- **Failure action:** Workflow fails when a listed command is missing or when a row marked ✅ still contains “pending” notes. Update the matrix or fix CLI implementation before merging.

Until the workflow lands, run the checker locally:

```bash
# Pending CONSOLE-DOC-23-502 – placeholder command
./scripts/check-console-cli-parity.sh
```

The script should emit a parity report that feeds into the Downloads workspace (`kind = "parity.report"`).

---

## 10 · Compliance checklist

- [ ] Matrix reflects latest command availability (statuses accurate, task IDs linked).  
- [ ] Notes include owning backlog items for every 🟩 / 🟡 row.  
- [ ] CLI commands marked ✅ have corresponding entries in `/docs/cli/*.md` or module-specific docs.  
- [ ] CI parity workflow description kept in sync with CONSOLE-DOC-23-502 implementation.  
- [ ] Downloads workspace links to latest parity report.  
- [ ] Install / observability guides reference this matrix for pending CLI parity.  
- [ ] Offline workflows capture CLI fallbacks when commands are pending.  
- [ ] Docs Guild review recorded in sprint log once parity CI lands.

---

## 11 · References

- `/docs/ui/*.md` – per-surface UI parity callouts.  
- `/docs/install/docker.md` – CLI parity section for deployments.  
- `/docs/observability/ui-telemetry.md` – telemetry metrics referencing CLI checks.  
- `/docs/security/console-security.md` – security metrics & CLI parity expectations.  
- `src/Cli/StellaOps.Cli/TASKS.md` – authoritative status for CLI backlog.  
- `/docs/updates/2025-10-28-docs-guild.md` – coordination note for Authority/Security follow-up.

---

*Last updated: 2025-10-28 (Sprint 23).*