Onelake Catalog 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

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.

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

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 waits for the long-running operation itself (a semantic model usually returns 202) — never poll it in separate calls. It waits as long as Fabric's Retry-After asks (often 20–30 s), so give the command up to 3 minutes: if your shell tool has a wait or timeout setting, raise it rather than letting the command move to the background. Only for types with a definition: Warehouse, SQL Database, SQL analytics endpoint, ML model/experiment and Datamart have none — read their schema instead. PowerShell 7 (bash: fabric_lro in COMMON-CLI.md):

  Copy

  $h = @{ Authorization = "Bearer $(az account get-access-token --resource https://api.fabric.microsoft.com --query accessToken -o tsv)"; 'x-ms-fabric-skill' = 'onelake-catalog-cli' }
  $st = @{ n = 0; end = (Get-Date).AddMinutes(3) }
  # Waits the full Retry-After (202 and 429); backs off 2-30 s only when the header is missing or invalid.
  function Wait-RetryAfter($r) { $ra = 0
    if (-not [int]::TryParse("$(@($r.Headers['Retry-After'])[0])", [ref]$ra) -or $ra -lt 1) { $ra = [Math]::Min(30, [Math]::Pow(2, ++$st.n)) }
    if ((Get-Date).AddSeconds($ra) -gt $st.end) { throw "Definition read did not finish within 3 minutes." }
    Start-Sleep -Seconds $ra }
  while (($r = Invoke-WebRequest -Method Post -Uri "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/items/$ITEM_ID/getDefinition" -Headers $h -SkipHttpErrorCheck).StatusCode -eq 429) { Wait-RetryAfter $r }
  if ($r.StatusCode -ge 400) { throw "getDefinition returned $($r.StatusCode): $($r.Content)" }
  $def = if ($r.StatusCode -eq 202) {
    $op = [string]$r.Headers['Location']; $res = $r; $s = ''
    while ($s -notin 'Succeeded', 'Failed') {
      Wait-RetryAfter $res; $res = Invoke-WebRequest $op -Headers $h -SkipHttpErrorCheck
      if ($res.StatusCode -eq 200) { $s = ($res.Content | ConvertFrom-Json).status } elseif ($res.StatusCode -ne 429) { throw "Polling returned $($res.StatusCode): $($res.Content)" } }
    if ($s -ne 'Succeeded') { throw "Definition read failed: $($res.Content)" }
    while (($res = Invoke-WebRequest "$op/result" -Headers $h -SkipHttpErrorCheck).StatusCode -eq 429) { Wait-RetryAfter $res }
    if ($res.StatusCode -ge 400) { throw "Definition result returned $($res.StatusCode): $($res.Content)" }
    $res.Content | ConvertFrom-Json
  } else { $r.Content | ConvertFrom-Json }
  $dir = New-Item -ItemType Directory -Force -Path (Join-Path ([IO.Path]::GetTempPath()) "def-$ITEM_ID")
  foreach ($p in $def.definition.parts) {
    $t = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p.payload)); $f = Join-Path $dir ($p.path -replace '[\\/:]', '_'); Set-Content -LiteralPath $f -Value $t
    "== $($p.path) ($($t.Length) chars)"; if ($t.Length -le 4000) { $t } else { $t.Substring(0, 4000); "[first 4000 of $($t.Length) chars; full text in $f]" } }

  A part cut at 4,000 characters is saved in full: read the rest (one call) if what's shown isn't enough.

• Use the exact Fabric Admin, Core, Power BI, Graph or OneLake API surface the mode documents; a 401 or 403 is never permission to bypass RBAC.

Rules

MUST

• Load exactly one mode reference for the request and follow it end to end; come back to the index below when another procedure is needed. In curate, also read the suggestion guidance before drafting anything, and the table metadata reference before any table or column work.

• (curate) Propose exactly what the owner asked for. A specific request gets only that: "add a description" → the item description; "suggest tags" → tags; "describe the table" → the table description only; "describe the columns" → column descriptions only; "describe the item's objects" or "its tables and columns" → both. A general request ("curate this item", "make it more discoverable", "improve its metadata") gets the item's description, name and tags; an item with a OneLake Tables folder also gets its table and column descriptions. If the owner names several items, cover each one, and report each with only the fields it has.

• (curate) Check the scope before any call. Curate covers one item, an explicit list of items, or one named workspace at a time. For a tenant-wide request ("all my items", "every workspace"), say plainly that it isn't supported and offer one named workspace or an explicit list; for several named workspaces, ask which to start with. Don't list workspaces or items first.

• (govern) State scope, exclusions, pagination completeness, and freshness caveats with every governance statistic.

PREFER

• Least-privileged Core or Power BI APIs for data-owner actions instead of requiring tenant-admin rights.

• Findings as evidence, consequence, recommended action, priority and effort — not an inventory dump.

• Sequencing ownership and access-scope fixes before bulk assignment or labeling.

AVOID

• Mutating a tenant from an audit mode, or reporting an asynchronous 202 as completion.

• Inventing write APIs for endorsement, DLP policy, admin item deletion, or third-party item-identity assignment.

• (curate) Volunteering anything about table or column descriptions for items without a OneLake Tables folder (semantic models, reports, notebooks, pipelines, dataflows, …). For these items, description, name and tags are the complete list — present them without qualifiers in the preview and whenever you say what the skill can do (e.g. while declining a request, or offering what else you could review next). Don't add a note that table or column descriptions are N/A, don't apply or aren't covered, and don't offer them: the owner didn't ask. Only if they ask, answer that they aren't supported for that item type, then stop and let the owner choose — don't load another skill or draft those descriptions yourself.

• (curate) Saying "sub-items" — use the owner's words: "tables" and "columns", or "objects" when speaking generally.

References

Each reference is one hop from this index; after loading one, return here when another is needed.

Curate

• Curate — workflow, permission per change, preview format, examples, errors

• Suggestion guidance — drafting descriptions, names and tags from content

• Tag taxonomy — tenant/domain tag scope and name → ID resolution

• Table metadata — table and column descriptions (OneLake table API, preview)

• Curation API reference — Update Item, Apply/Unapply Tags, List Tags

Govern — shared

• Govern pillars — the three pillars, what "good" looks like, reporting conventions

• Governance data sources — verified API field coverage and blind spots

• Governance roles — permission tiers, domain/workspace roles, insight refresh lag

• Catalog concepts — the entity model and API-backed versus conceptual terms

Govern — modes

• Admin audit — tenant-wide read-only governance assessment

• Admin audit scope — governable denominator (active workspaces of type Workspace), exclusions, and known blind spots

• Admin audit assessment — end-to-end evaluative workflow, prioritization, and deliverable contract

• Admin remediate — tenant-wide guarded writes through Admin APIs

• Data-owner audit — caller-scoped read-only checks through Core APIs, including a workspace's domain assignment

• Data-owner workspace health — empty and inactive workspaces within the caller's scope

• Data-owner remediate — least-privileged Core and Power BI writes: moving one workspace to a domain, capacity, workspace tags, refresh, item identity

Govern — admin audit procedures: domain health · workspace health · capacity health · item inventory · item health · protect coverage · trust curation

Govern — admin remediation procedures: domain lifecycle · bulk workspace assignment (tenant admin) · domain roles · tag definitions · item sensitivity labels · domain default labels · trust remediation · no-write escalation

Examples

I'm curating my items for the OneLake catalog. Propose a better description for the semantic model Sales Model in the Finance workspace.

Make the lakehouse LSEGDemo more discoverable — describe its tables and columns too.

Audit our tenant's OneLake catalog governance posture and prioritize the findings.

Which workspaces I administer are not assigned to a domain?

Show a dry run for assigning these workspaces to the Finance domain, including current assignments.

Find unlabeled items tenant-wide and explain which remediations require a tenant admin versus a data owner.