fabric-cli

# 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`](./scripts/search_across_workspaces.py); see [workspaces.md](./references/workspaces.md#cross-workspace-search) for the delta. 3. Find the workspace: `fab ls` 4. Find the item: `fab ls "Workspace Name.Workspace"` 4. Check the commands for that item: - `fab desc` to get itemTypes - `fab desc .<ItemType>` for commands i.e. `fab desc .SemanticModel` 5. 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` 6. 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"` 7. 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](./references/querying-data.md#querying-the-sql-endpoint-route-priority) - 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` 8. 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"` 9. Review or manage permissions: - Item ACL: `fab acl ls "ws.Workspace/Model.SemanticModel"` then `fab acl set "ws.Workspace/Model.SemanticModel" -I user@contoso.com -R Read` - Workspace roles: `fab acl ls "ws.Workspace"` then `fab acl set "ws.Workspace" -I user@contoso.com -R Member` 10. Deploy items to Fabric: `fab import "ws.Workspace/New.Notebook" -i ./local-path/Nb.Notebook -f` 11. Download items from Fabric: `fab export "ws.Workspace/Nb.Notebook" -o ./backup -f` (always `mkdir -p ./backup` first) 12. 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` 13. Open item in Fabric via browser: `fab open "spaceparts-dev.SpaceParts/Amazing Report.Report"` 14. 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"` 15. Using [Azure CLI](./references/fab-vs-az-cli.md) (advanced) when Fabric CLI doesn't suffice: - T-SQL over any SQL-capable item ; use [`scripts/query_sql_endpoint.py`](./scripts/query_sql_endpoint.py) (reuses `az login` via `ActiveDirectoryAzCli`; full walkthrough in [querying-data.md](./references/querying-data.md#sqlcmd-over-lakehouse-warehouse-and-sql-database)) - 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](./references/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`: ```bash # 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: ```bash 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: ```bash # 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](./references/admin.md) ### Error Handling & Debugging ```bash # 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`](./scripts/search_across_workspaces.py); see [workspaces.md](./references/workspaces.md#cross-workspace-search) for the delta - Downstream reports for a given model: [`scripts/get-downstream-reports.py`](./scripts/get-downstream-reports.py) - Tenant-wide admin APIs: [admin.md](./references/admin.md) Check references before exploring: - [workspaces.md](./references/workspaces.md) - [folders.md](./references/folders.md) - [admin.md](./references/admin.md) - [reference.md](./references/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/"` |