fabric-cli

name	fabric-cli
description	Expert guidance for using the Fabric CLI (`fab`) to fully interact with Fabric workspaces, items, and configuration. Automatically invoke this skill whenever the user mentions "Fabric" or "Power BI Service" or a "Fabric/Power BI workspace".

Fabric CLI

Guidance for using fab to programmatically manage Fabric & Power BI service

• Install via uv tool install ms-fabric-cli (get uv via winget install uv or brew install uv)
• Fabric CLI is for working with the Cloud environment and not local files; it works with Power BI Pro, PPU, or Fabric; you DO NOT need a Fabric SKU to use the Fabric CLI
• Keep fab current: check the installed version against the latest ms-fabric-cli release and upgrade with uv tool upgrade ms-fabric-cli unless the user has pinned a specific version. Discover commands and flags with fab --help and fab <command> --help rather than hard-coding behavior; the CLI surface changes regularly

[!IMPORTANT] Any time you encounter errors, user preferences or learnings when using the Fabric cli, ALWAYS note these down in the user memory rules, i.e. .claude/rules/fabric-cli.md for future improvement. This is ONLY for generic learnings and not for item- or task-specific learnings.

When to use this skill

• Use whenever the user mentions "Fabric" or "Power BI"
• Use when user asks about Power BI workspaces, deployment, tenants, publishing, download, permissions, or data

Critical general rules

• IMPORTANT: The first time you use fab run check that it is up to date to the latest version (upgrade with uv tool upgrade ms-fabric-cli unless the user has pinned a version) and run fab auth status; If user isn't authenticated, ask them to run fab auth login
• Always use fab --help and fab <command> --help the first time you use a command to understand its syntax
• You must search the skill /references/ for relevant reference files that explain certain commands, examples, scripts, or workflows before you start using fab
• Before first use, ask the user if they have Fabric admin access, sensitivity labels or DLP policies, any API restrictions, or preferences for Fabric/Power BI API usage; remind user to add this to memory files
• If workspace or item name is unclear, ask the user first, then verify with fab ls or fab exists before proceeding
• Ensure that you avoid removing or moving items, workspaces, or definitions, or changing properties without explicit user direction
• If a command is blocked in your permissions and you try to use it, stop and ask the user for clarification; never try to circumvent it
• Create output directories before export: fab export does not create intermediate directories; mkdir -p the output path first or the command fails with [InvalidPath]

Use -f (force) for non-interactive use

The fab CLI prompts for confirmation, so you you must always append -f to prevent this UNLESS sensitivity labels are enabled, in which case you must ask the user. Do this for the commands:

• fab get -q "definition" ; sensitivity label confirmation
• fab export ; sensitivity label confirmation
• fab import ; overwrite confirmation
• fab cp / fab cp -r ; overwrite and sensitivity label confirmation
• fab rm ; delete confirmation
• fab assign / fab unassign ; capacity/domain assignment confirmation
• fab mv ; rename/move confirmation

Quickstart guide

You must read and understand the common list of operations with simple examples

0. Check the commands, syntax, and auth status: fab --help and fab auth status
1. Check if the item exists if the user gave the workspace and item name: fab exists "spaceparts-dev.Workspace/spaceparts-otc-full.SemanticModel"
2. Find an item by name across every workspace the user can see: fab find 'sales' -P type=Report -l (substring on name, description, workspace; -P type= to filter, -l for ids; -q '<jmespath>' for client-side filter/projection). For governance workflows that need last visit / last refresh / owner / storage mode / capacity SKU, use scripts/search_across_workspaces.py; see workspaces.md for the delta.
3. Find the workspace: fab ls
4. Find the item: fab ls "Workspace Name.Workspace"
5. Check the commands for that item:
   • fab desc to get itemTypes
   • fab desc .<ItemType> for commands i.e. fab desc .SemanticModel
6. What's in that item; what's it for; what is it?:
   • Full TMDL definition: fab get "spaceparts-dev.Workspace/spaceparts-otc-full.SemanticModel" -q "definition" -f
   • Search a specific measure / table / column: fab get "ws.Workspace/Model.SemanticModel" -q "definition" -f | rga -i "Sales Amount"
   • Retrieve AI instructions / AI schema: python3 scripts/get_semantic_model_ai_metadata.py "ws.Workspace/Model.SemanticModel" --instructions-out instructions.md --schema-out schema.json
7. Get files, tables, or table schemas:
   • List lakehouse files: fab ls "ws.Workspace/LH.Lakehouse/Files"
   • List lakehouse tables: fab ls "ws.Workspace/LH.Lakehouse/Tables"
   • Table schema: fab table schema "ws.Workspace/LH.Lakehouse/Tables/gold/orders"
8. Query data (always prefer the wrapper scripts over raw fab api / duckdb / sqlcmd; they resolve IDs, hosts, and auth for you):
   • Semantic model (DAX): python3 scripts/execute_dax.py "ws.Workspace/Model.SemanticModel" -q "EVALUATE TOPN(10, 'Orders')"
   • Lakehouse SQL endpoint, warehouse, or SQL database (T-SQL): prefer the fabric-sql MCP execute_query(workspaceId, itemId, query) when it is loaded; fall back to python3 scripts/query_sql_endpoint.py "ws.Workspace/LH.Lakehouse" -q "SELECT TOP 10 * FROM dbo.orders". See querying-data.md
   • Lakehouse or warehouse Delta over OneLake (DuckDB): python3 scripts/query_lakehouse_duckdb.py "ws.Workspace/LH.Lakehouse" -q "SELECT * FROM tbl LIMIT 10" -t gold.orders
9. Set properties for an item or workspace: fab set "ws.Workspace/Item.Notebook" -q displayName -i "New Name" or fab set "ws.Workspace" -q description -i "Production environment"
10. Review or manage permissions:
    • Item ACL: fab acl ls "ws.Workspace/Model.SemanticModel" then fab acl set "ws.Workspace/Model.SemanticModel" -I [e-mail] -R Read
    • Workspace roles: fab acl ls "ws.Workspace" then fab acl set "ws.Workspace" -I [e-mail] -R Member
11. Deploy items to Fabric: fab import "ws.Workspace/New.Notebook" -i ./local-path/Nb.Notebook -f
12. Download items from Fabric: fab export "ws.Workspace/Nb.Notebook" -o ./backup -f (always mkdir -p ./backup first)
13. Copy or move items between workspaces: fab cp "dev.Workspace/Item.Notebook" "prod.Workspace" -f or fab mv "ws.Workspace/Old.Notebook" "ws.Workspace/New.Notebook" -f
14. Open item in Fabric via browser: fab open "spaceparts-dev.SpaceParts/Amazing Report.Report"
15. Using Fabric or Power BI APIs: fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}' or fab api "workspaces/<ws-id>/items"
16. Using Azure CLI (advanced) when Fabric CLI doesn't suffice:
    • T-SQL over any SQL-capable item ; use scripts/query_sql_endpoint.py (reuses az login via ActiveDirectoryAzCli; full walkthrough in querying-data.md)
    • Pass a Key Vault secret to a consumer without ever reading, echoing, or persisting it: az login --service-principal -u <appId> -t <tenantId> --password "$(az keyvault secret show --vault-name <vault> --name <secret> --query value -o tsv)" ; command substitution pipes the secret directly into the child process arg list, never stdout, a file, or a named shell variable
    • Full fab-vs-az decision matrix: fab-vs-az-cli.md

Essential Concepts

For information about any concepts related to Power BI or Fabric you must search or fetch via the microsoft-learn MCP server (or the pbi-search CLI as an alternative) and ask the user questions with the AskUserQuestion tool; NEVER guess or make assumptions.

Workspaces

• Workspaces are containers for items like Notebooks (and other ETL items), Lakehouses (and other data items), SemanticModels, Reports (and other consumption items), and OrgApps.
• Workspaces can be assigned to different things:
  • Deployment Pipelines for lifecycle management (Dev, Test, Prod, etc.)
  • Domains for governance and tenant structuring
  • Capacities for licensing and resources (Fabric or Premium capacities only; PPU and Pro work differently)
  • Git repositories for Source Control via Git integration

Key Patterns

Pay special attention to each of the following areas when using the Fabric CLI

Path Format

Fabric uses filesystem-like paths with type extensions:

"WorkspaceName.Workspace/ItemName.ItemType"

You must quote paths with spaces and punctuation:

"Workspace Name.Workspace/Semantic Model Name.SemanticModel"

For lakehouses this is extended into files and tables:

WorkspaceName.Workspace/LakehouseName.Lakehouse/Files/FileName.extension or /WorkspaceName.Workspace/LakehouseName.Lakehouse/Tables/TableName

For Fabric capacities you have to use fab ls .capacities

Examples:

• "Production Workspace.Workspace/Sales Report.Report"
• Data.Workspace/MainLH.Lakehouse/Files/data.csv
• Data.Workspace/MainLH.Lakehouse/Tables/dbo/customers

Common Item Types

• .Workspace - Workspaces
• .SemanticModel - Power BI datasets
• .Report - Power BI reports
• .Notebook - Fabric notebooks
• .DataPipeline - Data pipelines
• .Lakehouse / .Warehouse/ .SQLDatabase - Data artifacts
• .SparkJobDefinition - Spark jobs
• .AISkill - Fabric Data Agents
• .MirroredDatabase / .MirroredWarehouse - Mirrored databases
• .Environment - Spark environments
• .UserDataFunction - User data functions

Full list: You must use fab desc or fab desc .<ItemType> to check syntax and types if the user asks about an item type not listed above.

JMESPath Queries

Filter and transform JSON responses with -q:

# Get single field
-q "id"
-q "displayName"

# Get nested field
-q "properties.sqlEndpointProperties"
-q "definition.parts[0]"

# Filter arrays
-q "value[?type=='Lakehouse']"
-q "value[?contains(name, 'prod')]"

# Get first element
-q "value[0]"
-q "definition.parts[?path=='model.tmdl'] | [0]"

Using fab api

fab has an api escape hatch that lets you use any API even if it doesn't have primary commands.

Variable Extraction Pattern

To use fab api you need item IDs. Extract them like this:

WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')

# Then use in API calls
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'

Admin APIs (Requires Admin Role)

Don't use admin commands or APIs if the user doesn't have Admin access. Here's some examples:

# Find semantic models by name (cross-workspace)
fab api "admin/items" -P "type=SemanticModel" -q "itemEntities[?contains(name, 'Sales')]"

# Find all notebooks
fab api "admin/items" -P "type=Notebook" -q "itemEntities[].{name:name,workspace:workspaceId}"

# Find all lakehouses
fab api "admin/items" -P "type=Lakehouse"

# Common types: SemanticModel, Report, Notebook, Lakehouse, Warehouse, DataPipeline, Ontology

For full admin API reference (cross-workspace discovery, tenant settings read/update, capacity/domain/workspace overrides, activity events): admin.md

Error Handling & Debugging

# Show response headers
fab api workspaces --show_headers

# Verbose output
fab get "Production.Workspace/Item" -v

# Save responses for debugging
fab api workspaces -o /tmp/workspaces.json

Common workflows

These are the most common workflows you'll encounter in Fabric

Finding or exploring workspaces, items, or metadata

Command	Purpose	Example
fab ls	List workspaces / items	fab ls "Sales.Workspace" -l
fab exists	Check if a path exists	fab exists "Sales.Workspace/Model.SemanticModel"
fab get	Get item details	fab get "Sales.Workspace" -q "id"
fab desc	Supported commands per type	fab desc .SemanticModel

Flags:

• -l (long listing)
• -a (show hidden items)
• -q (JMESPath filter)
• -v (verbose output)
• -o (save response to file)

Fabric discovery follows a drill-down pattern:

• Browsing:
  • List workspaces: fab ls
  • List items in a workspace: fab ls "ws.Workspace" -l
  • Confirm a path exists: fab exists "ws.Workspace/Item"
  • Check what commands an item type supports: fab desc .<ItemType>
• Inspection:
  • Get item details: fab get "ws.Workspace/Item"
  • Pull a single field: fab get "ws.Workspace" -q "id"
• Cross-workspace search:
  • Routine search across name, description, workspace: fab find '<text>' -P type=<Type> -l
  • Governance fields not in fab find (last visit, last refresh, owner, storage mode, capacity SKU, Copilot readiness): scripts/search_across_workspaces.py; see workspaces.md for the delta
  • Downstream reports for a given model: scripts/get-downstream-reports.py
  • Tenant-wide admin APIs: admin.md

Check references before exploring:

• workspaces.md
• folders.md
• admin.md
• reference.md

Querying data

Command	Purpose	Example
fab get -q "definition"	Get model schema	fab get "ws.Workspace/Model.SemanticModel" -q "definition" -f
fab api -A powerbi	Execute DAX	fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/executeQueries" -X post -i '{"queries":[{"query":"EVALUATE..."}]}'
fab ls	Browse files / tables	fab ls "ws.Workspace/LH.Lakehouse/Files"
fab table schema	Lakehouse table schema	fab table schema "ws.Workspace/LH.Lakehouse/Tables/sales"
fab cp	Upload / download OneLake file	fab cp ./local.csv "ws.Workspace/LH.Lakehouse/Files/"