/onelake-catalog-cli

name: onelake-catalog-cli
description: "Governs and curates the Microsoft Fabric OneLake catalog through Fabric Admin, Core and Power BI REST APIs. Use for tenant or data-owner governance audits and guarded remediation of domains, workspace assignment, capacity, labels, tag definitions, workspace tags, certification, refresh and item identity, and for owners curating an item's description, name, tags and table and column descriptions. Item discovery belongs to search-consumption-cli."

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

> **CRITICAL NOTES** > 1. To find the workspace ID from its name, one call: `az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces" --query "value[?displayName=='<name>'] | [0].id" -o tsv` (follow `continuationToken` only if it isn't on the first page; details in [COMMON-CLI.md § Finding Workspaces and Items in Fabric](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric)). > 2. To find an item's ID, one call: the same on `.../v1/workspaces/{ws}/items?type=<Type>` with `--query "value[?displayName=='<name>'] | [0].id"`. > 3. **Write-gated skill** — never call a write API before its gate below has passed. For curation that means the owner reviewed **every** proposed change and explicitly confirmed — not even a "test" write to check whether a change is allowed or what is already applied. > 4. The item list and Get Item both return an item's `tags`. **An item with no tags has no `tags` field** — that absence means untagged.

OneLake Catalog — CLI Skill (mode dispatcher)

One skill for the OneLake catalog. **Govern** (catalog health, protection and trust: audits and guarded remediation, by permission tier) and **curate** (an owner improving specific items' discoverability metadata) are modes, each detailed in a reference loaded on demand. This file picks the mode, holds every write gate, and indexes the references.

Mode selection

| Mode | Use when | Load | Writes | |---|---|---|---| | **curate** | An owner wants specific items easier to find: a description, a clearer display name, tags, or table and column descriptions (items with a OneLake Tables folder) — one item, an explicit list, or one named workspace's weakly-described items | [references/curate.md](references/curate.md) | ✅ after the owner approves each suggestion | | **dataowner-audit** | A **non-admin** workspace or domain owner wants governance posture for workspaces they administer (widen to accessible on request; Core API) | [references/dataowner-audit.md](references/dataowner-audit.md) | ❌ | | **dataowner-remediate** | A data owner who is also a domain / workspace / capacity admin fixes a governance finding — single-workspace domain or capacity assignment, workspace tags, refresh, item identity (Core & Power BI APIs, no tenant admin), including dry runs of these | [references/dataowner-remediate.md](references/dataowner-remediate.md) | ✅ self-service | | **admin-audit** | A **Fabric tenant admin** wants tenant-wide governance posture (`/v1/admin/*`) | [references/admin-audit.md](references/admin-audit.md); any tenant count starts from [admin-audit-scope.md](references/admin-audit-scope.md) | ❌ | | **admin-remediate** | A **Fabric tenant admin** makes tenant-wide writes — domains, bulk assignment, domain roles, bulk labels, tenant tag definitions, tenant settings | [references/admin-remediate.md](references/admin-remediate.md) | ✅ |

Govern is a 2×2 grid — tier (which API surface the caller can reach) × action (audit vs remediate) — covering the health, protect and trust pillars. **Choose the tier by API surface, not job title**: the `admin-*` modes need the Fabric tenant administrator role (Fabric admin / Power Platform admin / M365 global admin); domain, capacity and workspace admins who are not tenant admins live entirely in the `dataowner-*` modes.

Mode boundary rules

• **A direct curation request goes straight to curate.** Read the target item's current state —

don't run a governance audit first. Curation needs neither tenant admin nor workspace Admin; each change has its own permission (see curate.md).

• **Governance starts with an audit.** Never remediate before establishing the current state;

audit → remediate within the same tier unless the caller's rights change.

• **Curate is the only writer of item metadata.** Item descriptions and display names, applying

or removing an item's tags, and table and column descriptions are written only in curate. Workspace tags stay in dataowner-remediate; tenant tag *definitions* in admin-remediate.

• **Govern finds, curate fixes.** Govern reports description and tag **coverage** — presence,

with scope, denominator and freshness caveats, not proof the text is accurate; curate judges content and proposes. To fix selected gaps, hand off to curate with: a **bounded target** (an explicit item list with workspace ID, item ID and type, or one named workspace — never the whole tenant: ask the user to pick), the **observed gap** with its source and time (a candidate to recheck, not current truth), **only the fields the user chose** ("fix missing descriptions" = description only), and known access limits and owner contacts. A remediation is done only when curate has verified the write.

• **Audit modes never write.** If a write is asked for in an audit mode, switch explicitly to the

matching remediate mode or to curate — don't improvise a write.

• **A dry run or preflight of a fix** loads that fix's remediate mode and stays read-only there —

it isn't an audit. Moving one workspace to a domain is `dataowner-remediate`; bulk assignment is `admin-remediate`.

• **Finding items** when the workspace isn't known belongs to