---

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).
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 | ✅ 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 | ❌ | | 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 | ✅ self-service | | admin-audit | A Fabric tenant admin wants tenant-wide governance posture (/v1/admin/*) | references/admin-audit.md; any tenant count starts from 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 | ✅ |

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 search-consumption-cli. Looking up a workspace or domain by name, or an item by name inside a known workspace, is not discovery: use the lookups in CRITICAL NOTES and don't load search-consumption-cli for it.

⚠️ Known Fabric gap. A domain or workspace admin who is not a tenant admin has no API for their scoped governance posture: /v1/admin/* rejects them and the Core API can't list a domain's workspaces. dataowner-audit covers only workspaces the caller can access — say so up front rather than routing into an admin-* mode that will 401/403.

Terminal write — the step you must not skip

Reading a reference, drafting suggestions or building a dry run is NOT completing a write. Each writing mode ends with the state-changing call(s) below, issued only after the gate for that write passes. If you did not issue it, nothing changed — say so rather than reporting success.

| Mode | Terminal write | |---|---| | curate | PATCH /v1/workspaces/{ws}/items/{id} (description; display name in a separate call), POST .../items/{id}/applyTags or unapplyTags, and for a table POST https://onelake.table.fabric.microsoft.com/common/v1/{ws}/{item}/schemas/{schema}/tables/{table}/additionalMetadata with the complete set from a fresh read — only for suggestions the owner accepted | | dataowner-remediate | POST /v1/workspaces/{id}/assignToDomain / unassignFromDomain (synchronous 200), assignToCapacity (202 — poll to a terminal state), POST /v1/workspaces/{id}/applyTags / unapplyTags (workspace tags), item identity, semantic model refresh | | admin-remediate | /v1/admin/* writes — domains, bulk workspace assignment, domain roles, labels, tenant tag definitions, tenant settings | | dataowner-audit, admin-audit | none — read-only |

Before reporting a write done, confirm an explicit success (200/201, or a terminal LRO success for a 202) and read the result back.

Write gates — must pass first

| Write | Mode | Gate | |---|---|---| | Any curation write | curate | The owner saw a numbered current → proposed preview of every suggestion and explicitly approved; "apply all" covers only what was shown. Approving an audit or picking a remediation never approves text the owner hasn't seen. | | Table and column descriptions | curate | A write replaces the table's whole additional metadata: re-read, change only the approved descriptions, send the complete set in the same command, read again. The API has no concurrency check — never claim concurrent edits were preserved. A shortcut table is written on its source — name it and get explicit confirmation. | | Delete a domain | admin | Check subdomains (parentDomainId) and assigned-workspace counts for the domain and every subdomain; if workspaces would be orphaned, STOP and get explicit confirmation naming them. The API has no cascade-block. See domain-crud.md. | | Delete a tag definition | admin | Report how many items carry it first — deletion detaches it everywhere with no undo. | | Bulk-assign workspaces to a domain | admin | Check each target's current domainId and warn before silently overriding an assignment. Dry-run the target list first. | | Remove a principal from a domain role | admin | Confirm it will not leave the domain ownerless; name the principal being removed. | | Bulk sensitivity-label change | admin | Dry-run: show the affected items and before/after label, get confirmation. No service principal / managed identity — the call will fail. | | Write a tenant setting | admin | Read and show the current value, then the proposed value — tenant-wide blast radius. | | Assign / unassign one workspace to a domain | dataowner | A move is a reassignment — confirm the current domainId and name the domain it leaves. Needs domain contributor and workspace Admin; say which is missing on failure. | | Reassign item ownership (item identity, preview) | dataowner | Assigns to the caller only; needs Write on the item and its children. Confirm the intended identity. | | Assign a workspace to a capacity | dataowner | Needs workspace Admin plus capacity Contributor/Admin. 202 is not success — poll to a terminal state. | | Apply / remove a workspace tag (preview) | dataowner | Needs workspace Admin. Name the workspace and the tags, and confirm. Removing an applied tag is not deleting its definition. |

Don't promise a write that has no API. Endorsement, DLP policies, an owner changing a sensitivity label, and tenant-admin item deletion have no write route — say so and name who can act (no-write-api-escalation.md). A SQL Database's display name is fixed at creation: never send a rename for it, even when the owner asks for one — say it can't be renamed and offer the description and tags instead.

Shared essentials (all modes)

• Prerequisites: auth & tokens · REST, pagination, LRO, rate limits · CLI auth recipes · az rest (always pass --resource) · OneLake via curl (Storage-audience token) · OneLake shortcuts.
• Resolve workspace and item IDs with the one-call lookups in CRITICAL NOTES 1–2.
• Keep tool calls few. Each call re-sends the whole conversation, so extra calls are slow and costly. Combine related reads in one script, and don't re-open a doc you've already read.
• Read an item's definition in one command that wai