/onelake-catalog-govern-cli

name: onelake-catalog-govern-cli
description: "Governs Microsoft Fabric OneLake catalog health, protection, and trust through Fabric Admin, Core, and Power BI REST APIs. Use for tenant or owner-scoped audits and guarded remediation of domains, workspace assignment, capacity, labels, tags, descriptions, refresh, and item identity. Catalog item discovery belongs to search-consumption-cli."

> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry > `x-ms-fabric-skill: onelake-catalog-govern-cli` (`az rest`: `--headers "x-ms-fabric-skill=onelake-catalog-govern-cli"`), > including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.

> **CRITICAL NOTES** > 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering > 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

OneLake Catalog Govern — CLI (mode dispatcher)

One skill for the whole OneLake Catalog **Govern** family. The governance persona detail lives in four **mode references** loaded on demand. This top-level file exists to do three things and nothing else:

1. **Pick the mode** (the table below). 2. **Surface the safety boundary and the irreversible-write gates** so they are never diluted inside a large reference (see [Irreversible operations](#step-2--irreversible-operations--must-do-gates-read-before-any-write)). 3. **Load exactly one mode reference** and follow it.

Must/Prefer/Avoid

MUST DO

• Start with the audit cell for the caller's permission tier before any remediation.
• Apply the operation-specific confirmation gate in Step 2 before every destructive, irreversible, or broad write.
• Use the exact Fabric Admin, Core, Power BI, or Graph API surface documented for the selected procedure; do not treat a `401` or `403` as permission to bypass RBAC.
• State scope, exclusions, pagination completeness, and freshness caveats with every governance statistic.

PREFER

• Use least-privileged Core or Power BI APIs for data-owner actions instead of requiring tenant-admin rights.
• Report findings as evidence, consequence, recommended action, priority, and effort rather than returning an inventory dump.
• Sequence ownership and access-scope fixes before bulk assignment or labeling.

AVOID

• Do not mutate a tenant from an audit mode.
• Do not invent write APIs for endorsement, DLP policy, admin item deletion, or third-party item-identity assignment.
• Do not report asynchronous `202` responses as successful completion.

Step 1 — Pick the mode

**Two axes → a 2×2 grid.** Tier (which API surface you can reach) × action (audit vs. remediate). Each cell covers all three Govern pillars (health / protect / trust).

| | **Audit** (read-only) | **Remediate** (write) | |---|---|---| | **Fabric Admin** — `/v1/admin/*`, **Fabric tenant admin only** | `admin-audit` | `admin-remediate` | | **Data owner / Operational admin** — Core API + workspace/domain/capacity admins, no tenant admin | `dataowner-audit` | `dataowner-remediate` |

| Mode | Load this reference | Persona / permission tier | Scope | Reads | Writes | |---|---|---|---|---|---| | **admin-audit** | [references/admin-audit.md](references/admin-audit.md) | **Fabric tenant admin** (`/v1/admin/*`) | Whole tenant | ✅ | ❌ | | **admin-remediate** | [references/admin-remediate.md](references/admin-remediate.md) | **Fabric tenant admin only** — every `/v1/admin/*` write requires the Fabric administrator role; **domain & capacity admins do NOT qualify** | Whole tenant | ✅ | ✅ | | **dataowner-audit** | [references/dataowner-audit.md](references/dataowner-audit.md) | **Non-admin** workspace or domain owner (Core API only) | Workspaces the caller administers (widen to accessible on request) | ✅ | ❌ | | **dataowner-remediate** | [references/dataowner-remediate.md](references/dataowner-remediate.md) | **Data owner who is also a domain / workspace / capacity admin** — Core & Power BI API writes, **no tenant admin** | Objects the caller has the role on | ✅ | ✅ (self-service) |

Routing rules

• **Start with an audit mode.** Never remediate before establishing the current state. Audit → remediate within the **same tier** unless the caller's rights change.
• **Choose the tier by the API surface the caller can reach**, not by job title: a **Fabric tenant admin** who needs `/v1/admin/*` → the `admin-*` cell; a data owner acting through workspace/domain/capacity roles → the `dataowner-*` cell.
• **"Fix / assign / apply / create / delete"** → a **remediate** cell. Tenant-wide writes (create/delete domain, bulk domain assignment, domain roles, bulk labels, certification) → `admin-remediate`. Single-workspace `assignToDomain` or `assignToCapacity`, applying tags, setting descriptions, refresh, and item identity → `dataowner-remediate` (these need object-scoped roles, not tenant admin).
• The read/write split is a **safety boundary**: an audit mode must not mutate a tenant even if a prompt asks it to. If you are in an audit mode and the user asks for a write, switch to the matching remediate mode explicitly — do not improvise a write.

> **Tier = API surface, not role title.** The `admin-*` modes call `/v1/admin/*` and require the **Fabric tenant administrator** role (Fabric admin / Power Platform admin / M365 global admin) — **domain, capacity and workspace admins do NOT qualify**, even for their own domain. The `dataowner-*` modes use the Core/Power BI APIs scoped to roles the caller already holds on specific objects. A domain/WS/capacity admin who is *not* a Fabric tenant admin therefore lives entirely in the `dataowner-*` cells; they cross into `admin-*` **only if they are separately granted the Fabric tenant admin role**. Roles are **scope branches inside** a mode; only a different **API surface** justifies a separate mode.

> ⚠️ **Known Fabric g