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"`
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 or warehouse (DuckDB + Delta against OneLake): `python3 scripts/query_lakehouse_duckdb.py "ws.Workspace/LH.Lakehouse" -q "SELECT * FROM tbl LIMIT 10" -t gold.orders`
   - Lakehouse SQL endpoint, warehouse, or SQL database (T-SQL via `sqlcmd` + `az` session): `python3 scripts/query_sql_endpoint.py "ws.Workspace/LH.Lakehouse" -q "SELECT TOP 10 * FROM dbo.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.Note