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
- Check the commands, syntax, and auth status:
fab --help and fab auth status
- Check if the item exists if the user gave the workspace and item name:
fab exists "spaceparts-dev.Workspace/spaceparts-otc-full.SemanticModel"
- 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.
- Find the workspace:
fab ls
- Find the item:
fab ls "Workspace Name.Workspace"
- Check the commands for that item:
fab desc to get itemTypes
fab desc .<ItemType> for commands i.e. fab desc .SemanticModel
- 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
- 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"
- 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
- 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"
- 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
- Setting up a service principal for automation instead of a human identity: service-principals.md - creation via az CLI, the workspace-role-plus-tenant-setting-group double requirement, and how to authenticate
fab as it
- Deploy items to Fabric:
fab import "ws.Workspace/New.Notebook" -i ./local-path/Nb.Notebook -f
- Download items from Fabric:
fab export "ws.Workspace/Nb.Notebook" -o ./backup -f (always mkdir -p ./backup first)
- 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
- Open item in Fabric via browser:
fab open "spaceparts-dev.SpaceParts/Amazing Report.Report"
- 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"
- 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:
Check references before exploring:
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/" |
duckdb + delta_scan |
Query Delta tables (requires DuckDB) |
duckdb -c "... delta_scan('abfss://<ws-id>@onelake.../<lh-id>/Tables/schema/table')" |
duckdb + read_csv/json |
Query raw files (requires DuckDB) |
duckdb -c "... read_csv('abfss://.../Files/data.csv')" |
Flags:
-A fabric|powerbi|storage|azure (API audience)
-X get|post|put|delete|patch (HTTP method)
-i (JSON body or file)
-f (skip sensitivity prompt on definition pulls).
Fabric exposes three query paths depending on the source; always prefer the wrapper scripts -- they resolve IDs, hosts, and auth for you:
- Semantic models (DAX):
- Find model fields first:
fab get "ws.Workspace/Model.SemanticModel" -q "definition"
- Query:
scripts/execute_dax.py
- Lakehouses / Warehouses via Delta over OneLake (DuckDB):
- Lakehouse SQL endpoint, Warehouse, or SQL Database (T-SQL):
- Prefer the
fabric-sql MCP execute_query(workspaceId, itemId, query) when loaded; server-side, no local tooling
- Fall back to
scripts/query_sql_endpoint.py (sqlcmd; auto-detects host per item type, reuses az login via ActiveDirectoryAzCli) when the MCP is unavailable
- Prefer either over DuckDB when you need
INFORMATION_SCHEMA, sys.* metadata, CTEs, or window functions
- Full route priority: querying-data.md
Check references before writing queries:
Changing metadata or access (descriptions, tags, endorsement, properties, bindings, permissions)
| Command |
Purpose |
Example |
fab set |
Update property |
fab set "ws.Workspace/Item" -q displayName -i "New Name" |
fab mv |
Rename / move item |
fab mv "ws/Old.Notebook" "ws/New.Notebook" -f |
fab acl ls |
List permissions |
fab acl ls "ws.Workspace" |
fab acl set |
Grant permission |
fab acl set "ws.Workspace" -I <objectId> -R Member |
fab acl rm |
Revoke permission |
fab acl rm "ws.Workspace" -I <upn> |
fab label set |
Set sensitivity label |
fab label set "ws/Nb.Notebook" --name Confidential |
Flags:
-q <field> + -i <value> (set a single property)
-I (object ID or UPN for fab acl)
-R Admin|Member|Contributor|Viewer (role for fab acl set)
-f (skip confirmation; ask user first if sensitivity labels are in play)
Metadata and access changes fall into a few groups:
- Properties (displayName, description, sensitivity config):
- Native update:
fab set "<path>" -q <field> -i "<value>"
- Capture current state first so you can revert:
fab get -v -o /tmp/before.json
- Endorsement, certification, and tags (no first-class
fab commands):
- Patch via
fab api with item-specific endpoints
- Tag workflow: tags.md
- Endorsement patterns: reference.md
- Folder placement:
- Move items between workspace subfolders: folders.md
- Access control and sensitivity labels:
- Grant / revoke:
fab acl set, fab acl rm
- Set sensitivity label:
fab label set
- Verify the principal first:
az ad user show
- Never change permissions or labels without explicit user confirmation
- Bindings:
Check references before changing metadata:
Working with workspaces
| Command |
Purpose |
Example |
fab mkdir |
Create workspace / item |
fab mkdir "New.Workspace" -P capacityname=MyCapacity |
fab assign |
Attach capacity / domain |
fab assign .capacities/cap.Capacity -W ws.Workspace -f |
fab unassign |
Detach capacity / domain |
fab unassign .capacities/cap.Capacity -W ws.Workspace |
fab start / fab stop |
Resume / pause capacity |
fab start .capacities/cap.Capacity |
fab cp -r |
Fork workspace |
fab cp "dev.Workspace" "prod.Workspace" -r -f |
fab rm |
Soft-delete (see recovery) |
fab rm "ws/Item.Type" -f |
Flags:
-P key=value (creation params for fab mkdir)
-W (target workspace for fab assign / fab unassign)
-r (recursive copy/move)
-bpc (block on path collision for fab cp)
-f (skip confirmation)
Workspace-scope operations fall into a few groups:
- Create and provision:
- Create workspace:
fab mkdir "<Name>.Workspace" -P capacityname=<cap>
- Attach capacity or domain:
fab assign .capacities/<cap>.Capacity -W <ws>.Workspace
- Planning context, create/get/set surface, large storage format, Spark pools, OneLake defaults, Git: workspaces.md
- Copy, fork, download:
- Duplicate a workspace in-tenant:
fab cp -r "dev.Workspace" "prod.Workspace"
- Dry-run the source tree first:
fab ls "dev.Workspace"
- Full local snapshot (items + lakehouse files):
scripts/download_workspace.py
- Permissions:
- Inspect / grant / revoke:
fab acl ls | set | rm
- Tenant-wide governance audit: use the
audit-tenant-settings skill from the fabric-admin plugin
- Connections and gateways (bound to, but outside, the workspace):
- Credential types (WorkspaceIdentity, SPN, Basic), OAuth2 limits: connections.md
- Datasource binding, credential rotation: gateways.md
- Folders inside a workspace:
Check references before modifying workspaces:
Executing or scheduling jobs (notebooks, notebook cells, pipelines, semantic model refresh)
| Command |
Purpose |
Example |
fab job run |
Run synchronously |
fab job run "ws/ETL.Notebook" -P date:string=2025-01-01 |
fab job start |
Run asynchronously |
fab job start "ws/ETL.Notebook" |
fab job run-list |
List executions |
fab job run-list "ws/Nb.Notebook" |
fab job run-status |
Check status |
fab job run-status "ws/Nb.Notebook" --id <job-id> |
fab job run-cancel |
Cancel a job |
fab job run-cancel "ws/Nb.Notebook" --id <job-id> -w |
scripts/run_notebook_checked.py |
Run a notebook + verify its exit value (status Completed ≠ ETL succeeded) |
python3 scripts/run_notebook_checked.py "ws/ETL.Notebook" |
fab api -A powerbi .../refreshes |
Trigger semantic model refresh |
fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}' |
Flags:
-P key:type=value (parameters, type is string|int|bool)
--id (job run ID)
-w (wait on cancel)
--timeout (overall timeout for synchronous runs)
--polling_interval (status poll cadence)
Jobs map to different endpoints depending on item type:
- Notebooks and pipelines:
- Run synchronously:
fab job run "ws/ETL.Notebook" -P date:string=2025-01-01
- Run asynchronously:
fab job start "ws/ETL.Notebook"
- Check status:
fab job run-status "ws/Nb.Notebook" --id <job-id>
- List history:
fab job run-list "ws/Nb.Notebook"
- Verify the REAL outcome: a job
Completed only means the process finished -- a notebook can catch its own exception and exit a failure payload while still showing Completed. Read its exit value, or use scripts/run_notebook_checked.py; details in notebooks.md
- Python / PySpark kernels, Livy sessions, cell-level CRUD: notebooks.md
- Semantic model refresh (not exposed as
fab job):
- Trigger:
fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}'
- Check current run before starting a new one (409 if already running):
fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes?\$top=1"
- Enhanced refresh, incremental policies, partition targeting: semantic-models.md
- Dataflow refresh:
- Scheduling:
Check references before running jobs:
Fabric admin operations (auditing, management)
| Command |
Purpose |
Example |
fab api "admin/items" |
Cross-workspace item search |
fab api "admin/items" -P "type=SemanticModel" -q "itemEntities[?contains(name,'Sales')]" |
fab api "admin/workspaces" |
Workspace inventory |
fab api "admin/workspaces" |
fab api "admin/tenantsettings" |
Tenant settings |
fab api "admin/tenantsettings" |
fab api "admin/capacities" |
Capacity inventory |
fab api "admin/capacities" |
fab api -X post .../update |
Update tenant setting |
fab api -X post "admin/tenantsettings/<name>/update" -i body.json |
Flags:
-P key=value (query params, e.g. type=SemanticModel)
-q (JMESPath filter)
-X post + -i (write ops)
--show_headers (inspect Retry-After on 429)
Admin-scope work is gated behind the Fabric / Power BI admin role. Confirm access first with fab api "admin/capacities" 2>&1 | head -5; if it errors, stop rather than retry.
Two entry points cover most admin tasks:
- Governance audits (tenant settings, delegated overrides, Entra SG scoping):
- Use the
audit-tenant-settings skill from the fabric-admin plugin. It owns the curated metadata baseline, the audit + change-detection script, delegated-override enumeration, and the Entra SG investigation workflow.
- Invoke it whenever the question combines tenant posture with group membership, override scope, or drift against the baseline.
- Raw admin APIs (cross-workspace search, activity events, artifact access, item search):
- Patterns in admin.md
- Rate limit: 25 write requests / minute; honor
Retry-After on 429
- Print the exact command and wait for user confirmation before any destructive admin operation
Check references before admin work:
Definitions and deployment (item definitions, deployment pipelines, git integration, cicd)
| Command |
Purpose |
Example |
fab get -q "definition" |
Read raw definition |
fab get "ws/Model.SemanticModel" -q "definition" -f |
fab export |
Export item to local |
fab export "ws/Nb.Notebook" -o ./backup -f |
fab import |
Import item from local |
fab import "ws/Nb.Notebook" -i ./backup/Nb.Notebook -f |
fab cp |
Copy between workspaces |
fab cp "dev/Item" "prod.Workspace" -f |
fab api "deploymentPipelines" |
Deployment pipelines API |
fab api "deploymentPipelines" -q "value[]" |
Flags:
-o (output path for fab export)
-i (input path or JSON body for fab import)
--format (definition format for export / import)
-f (skip overwrite and sensitivity prompts)
[!IMPORTANT]
The poll interval is by far the biggest performance lever for any definition change.
Creating or updating an item definition is a long-running operation (LRO): the API returns
202 Accepted with a Retry-After: 20 header. fab import, nb create, and nb cell edit
wait roughly that long between status polls, so a notebook that the server finishes in ~1s
takes them 25-60s. Neither fab nor nb exposes a knob to change that interval.
For notebook definition changes, strongly prefer scripts/deploy_notebook.py,
which polls the LRO every ~0.3s (tunable via --poll-interval) and creates in ~1-2s or updates
in place in ~1s. Auto-detects create vs update. When you must roll your own for another item
type, the rule is the same: poll updateDefinition / create at ~0.3s, not the advertised 20s.
python3 scripts/deploy_notebook.py "ws.Workspace/ETL.Notebook" -i ./ETL.Notebook # create or update in place
Every Fabric item has a serializable definition. Move definitions between environments depending on scope:
- Single item:
- Round-trip locally:
fab export then fab import (always mkdir -p the output directory first; fab export does not create intermediate directories and fails with [InvalidPath])
- Same-tenant shortcut, no local hop:
fab cp "dev/Item" "prod.Workspace"
- Semantic model as PBIP (TMDL + blank report):
- Export the model with
fab export, create the report with pbir new report, then combine
them with pbir report merge-to-thick; see import-download-deploy.md
- Full workspace snapshot (items + lakehouse files):
- Promotion between Dev, Test, Prod:
- Fabric deployment pipelines API (covers all item types)
- Power BI pipelines API (Power BI items only, but finer-grained deploy flags like
allowPurgeData, allowTakeOver)
- When to use each, selective deploy, LRO polling: deployment-pipelines.md
- Git integration (connect workspace to repo, branch, commit, update from git):
Check references before deploying:
Related skills
audit-tenant-settings (in the fabric-admin plugin) ; Fabric governance workflow covering tenant settings, delegated overrides (capacity / domain / workspace), and the Entra security groups those settings reference. Read-only; holds the curated metadata baseline and the audit + change-detection script.
Gotchas
- IMPORTANT: DON'T try to use
fab ls on items that aren't data items (.Lakehouse, .Warehouse, etc); use fab ls to find workspaces and items, and use fab get to look at definitions
- ALWAYS Use the
-f flag when using fab get, fab import, fab export, etc. as described above
- ONLY fallback to
fab api when a command doesn't exist
- Definition changes feel slow but aren't:
fab import / nb create / nb cell edit take 25-60s to push a notebook definition only because they poll the LRO at the server's Retry-After: 20. The work is ~1s. Use scripts/deploy_notebook.py (tight-polls at ~0.3s) for definition changes; the poll interval is the single biggest lever
References
Reference map (which references cluster together; follow the links between them, not just this list):
etl / notebooks
notebooks.md ── run jobs, exit value, scheduling
├─ querying-data.md ── nb exec / Livy, DuckDB/sqlcmd, SQL-endpoint sync
└─ lakehouses.md ── attach, table ops, OneLake shortcuts, SQL-endpoint id
(cross-plugin) executing-spark, using-duckdb ── etl plugin: ephemeral Spark, local Delta
data items
lakehouses.md · warehouses.md · sql-databases.md · semantic-models.md
└─ all feed querying-data.md (route priority) and notebooks.md (load then read)
governance / deploy
admin.md · permissions.md · tags.md · folders.md
import-download-deploy.md ─ deployment-pipelines.md ─ workspaces.md (git status)
(cross-plugin) audit-tenant-settings ── fabric-admin plugin
Skill references:
- Import, Download, and Deploy - Export / import / copy / move items, PBIP round-trips, dev-to-prod migration patterns
- Querying Data - Query semantic models in DAX and lakehouses or warehouses in SQL with DuckDB
- Lakehouses - Endpoints, file/table operations, OneLake paths
- Warehouses - Create, browse, query via DuckDB, load data
- SQL Databases - Create, browse, query via DuckDB, auto-mirroring
- Semantic Models - TMDL, DAX, refresh, storage mode
- Reports - Export, import, visuals, fields
- Paginated Reports - RDL upload, export-to-file, datasources, parameters
- Notebooks - Python/PySpark kernels, metadata, cell CRUD, Livy execution, scheduling
- Workspaces - Create, manage, permissions
- Permissions - Sharing and distribution, workspace roles, item permissions, apps, embed, B2B, deployment pipeline permissions, licensing and capacity SKUs
- Deployment Pipelines - CI/CD, deploy stages, selective deploy, LRO polling
- Dataflows - Gen1 and Gen2, refresh, publish, admin
- Dashboards - Tiles, clone (dashboards are not reports)
- Org Apps - Read-only API for distributed content packages
- Scorecards - Goals, check-ins, status rules (Preview API)
- Gateways - Datasources, credentials, dataset binding
- Folders - Organize items into folders via API; includes best practices for structuring workspaces
- Tags - Create, apply, and audit tenant/domain tags on items and workspaces via
fab api (no native fab tag command)
- fab vs az CLI - When to use which; capacity, networking, Key Vault, monitoring, CMK, CI/CD
- Admin APIs - Cross-workspace search, tenant operations, governance
- API Reference - Capacities, domains, misc API patterns
- Connections - Create, update, list connections programmatically; credential types (WorkspaceIdentity, SPN, Basic); OAuth2 limitations
- Service Principals - Create an SP with az CLI, grant it workspace access, clear the tenant-setting gate, authenticate
fab as it (real login vs env-token testing), rotation and teardown
- Full Command Reference - All commands detailed
Scripts (scripts that you can execute):
- search_across_workspaces.py ; cross-workspace governance complement to
fab find (last visit, last refresh, owner, storage mode, capacity SKU, Copilot readiness); see workspaces.md for when to choose which
- get-downstream-reports.py ; find all reports connected to a given semantic model across accessible workspaces (no admin required)
- execute_dax.py ; execute DAX queries against semantic models; output as table, csv, or json
- query_lakehouse_duckdb.py ; query lakehouse or warehouse Delta tables via DuckDB against OneLake (reuses
az login); output as table, csv, or json
- query_sql_endpoint.py ; query lakehouse SQL endpoint, warehouse, or SQL database via
sqlcmd (reuses az login through ActiveDirectoryAzCli); output as table, csv, or json
- create_direct_lake_model.py ; create a Direct Lake semantic model from lakehouse tables
- download_workspace.py ; download a full workspace with all item definitions and lakehouse files
- run_notebook_checked.py ; run a notebook and check its exit value, exiting non-zero when the notebook's own
{ok:false} verdict fails despite a Completed job status (reads the exit value via the notebook job-instance beta endpoint)
- deploy_notebook.py ; create or update a notebook definition fast (~1-2s) by tight-polling the LRO instead of the CLI's ~20s
Retry-After cadence; auto-detects create vs update, --poll-interval is the performance lever. Strongly prefer this over fab import / nb for any notebook definition change
See scripts/README.md for detailed usage, arguments, and examples. Always search the scripts/ folder before writing a new helper; a script may already exist for the task.
External references (request markdown when possible):
Source: data-goblin/power-bi-agentic-development → plugins/fabric-cli/skills/fabric-cli/SKILL.md
1---
2name: fabric-cli
3description: "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\"."
4category: mobile-and-platform
5source_repo: data-goblin/power-bi-agentic-development
6source_path: "plugins/fabric-cli/skills/fabric-cli/SKILL.md"
7source_url: https://github.com/data-goblin/power-bi-agentic-development/blob/HEAD/plugins/fabric-cli/skills/fabric-cli/SKILL.md
8metadata:
9 source: https://skillmd.com/skills/data-goblin/fabric-cli
10---
11
12# Fabric CLI
13
14Guidance for using `fab` to programmatically manage Fabric & Power BI service
15
16- Install via `uv tool install ms-fabric-cli` (get `uv` via `winget install uv` or `brew install uv`)
17- 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
18- 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
19
20> [!IMPORTANT]
21> 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.
22> This is ONLY for generic learnings and not for item- or task-specific learnings.
23
24## When to use this skill
25
26- Use whenever the user mentions "Fabric" or "Power BI"
27- Use when user asks about Power BI workspaces, deployment, tenants, publishing, download, permissions, or data
28
29
30## Critical general rules
31
32- 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`
33- Always use `fab --help` and `fab <command> --help` the first time you use a command to understand its syntax
34- You must search the skill /references/ for relevant reference files that explain certain commands, examples, scripts, or workflows before you start using `fab`
35- 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
36- If workspace or item name is unclear, ask the user first, then verify with `fab ls` or `fab exists` before proceeding
37- Ensure that you avoid removing or moving items, workspaces, or definitions, or changing properties without explicit user direction
38- 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
39- Create output directories before export: `fab export` does not create intermediate directories; `mkdir -p` the output path first or the command fails with `[InvalidPath]`
40
41
42### Use `-f` (force) for non-interactive use
43
44The `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:
45
46- `fab get -q "definition"` ; sensitivity label confirmation
47- `fab export` ; sensitivity label confirmation
48- `fab import` ; overwrite confirmation
49- `fab cp` / `fab cp -r` ; overwrite and sensitivity label confirmation
50- `fab rm` ; delete confirmation
51- `fab assign` / `fab unassign` ; capacity/domain assignment confirmation
52- `fab mv` ; rename/move confirmation
53
54
55## Quickstart guide
56
57You must read and understand the common list of operations with simple examples
58
590. Check the commands, syntax, and auth status: `fab --help` and `fab auth status`
601. Check if the item exists if the user gave the workspace and item name: `fab exists "spaceparts-dev.Workspace/spaceparts-otc-full.SemanticModel"`
612. 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.
623. Find the workspace: `fab ls`
634. Find the item: `fab ls "Workspace Name.Workspace"`
644. Check the commands for that item:
65 - `fab desc` to get itemTypes
66 - `fab desc .<ItemType>` for commands i.e. `fab desc .SemanticModel`
675. What's in that item; what's it for; what is it?:
68 - Full TMDL definition: `fab get "spaceparts-dev.Workspace/spaceparts-otc-full.SemanticModel" -q "definition" -f`
69 - Search a specific measure / table / column: `fab get "ws.Workspace/Model.SemanticModel" -q "definition" -f | rga -i "Sales Amount"`
70 - 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`
716. Get files, tables, or table schemas:
72 - List lakehouse files: `fab ls "ws.Workspace/LH.Lakehouse/Files"`
73 - List lakehouse tables: `fab ls "ws.Workspace/LH.Lakehouse/Tables"`
74 - Table schema: `fab table schema "ws.Workspace/LH.Lakehouse/Tables/gold/orders"`
757. Query data (always prefer the wrapper scripts over raw `fab api` / `duckdb` / `sqlcmd`; they resolve IDs, hosts, and auth for you):
76 - Semantic model (DAX): `python3 scripts/execute_dax.py "ws.Workspace/Model.SemanticModel" -q "EVALUATE TOPN(10, 'Orders')"`
77 - 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)
78 - 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`
798. 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"`
809. Review or manage permissions:
81 - Item ACL: `fab acl ls "ws.Workspace/Model.SemanticModel"` then `fab acl set "ws.Workspace/Model.SemanticModel" -I user@contoso.com -R Read`
82 - Workspace roles: `fab acl ls "ws.Workspace"` then `fab acl set "ws.Workspace" -I user@contoso.com -R Member`
83 - Setting up a service principal for automation instead of a human identity: [service-principals.md](./references/service-principals.md) - creation via az CLI, the workspace-role-plus-tenant-setting-group double requirement, and how to authenticate `fab` as it
8410. Deploy items to Fabric: `fab import "ws.Workspace/New.Notebook" -i ./local-path/Nb.Notebook -f`
8511. Download items from Fabric: `fab export "ws.Workspace/Nb.Notebook" -o ./backup -f` (always `mkdir -p ./backup` first)
8612. 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`
8713. Open item in Fabric via browser: `fab open "spaceparts-dev.SpaceParts/Amazing Report.Report"`
8814. 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"`
8915. Using [Azure CLI](./references/fab-vs-az-cli.md) (advanced) when Fabric CLI doesn't suffice:
90 - 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))
91 - 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
92 - Full fab-vs-az decision matrix: [fab-vs-az-cli.md](./references/fab-vs-az-cli.md)
93
94
95## Essential Concepts
96
97For 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.
98
99### Workspaces
100
101- **Workspaces** are containers for **items** like Notebooks (and other ETL items), Lakehouses (and other data items), SemanticModels, Reports (and other consumption items), and OrgApps.
102- Workspaces can be assigned to different things:
103 - Deployment Pipelines for lifecycle management (Dev, Test, Prod, etc.)
104 - Domains for governance and tenant structuring
105 - Capacities for licensing and resources (Fabric or Premium capacities only; PPU and Pro work differently)
106 - Git repositories for Source Control via Git integration
107
108
109## Key Patterns
110
111Pay special attention to each of the following areas when using the Fabric CLI
112
113
114### Path Format
115
116Fabric uses filesystem-like paths with type extensions:
117
118`"WorkspaceName.Workspace/ItemName.ItemType"`
119
120You must quote paths with spaces and punctuation:
121
122`"Workspace Name.Workspace/Semantic Model Name.SemanticModel"`
123
124For lakehouses this is extended into files and tables:
125
126`WorkspaceName.Workspace/LakehouseName.Lakehouse/Files/FileName.extension` or `/WorkspaceName.Workspace/LakehouseName.Lakehouse/Tables/TableName`
127
128For Fabric capacities you have to use `fab ls .capacities`
129
130Examples:
131
132- `"Production Workspace.Workspace/Sales Report.Report"`
133- `Data.Workspace/MainLH.Lakehouse/Files/data.csv`
134- `Data.Workspace/MainLH.Lakehouse/Tables/dbo/customers`
135
136
137### Common Item Types
138
139- `.Workspace` - Workspaces
140- `.SemanticModel` - Power BI datasets
141- `.Report` - Power BI reports
142- `.Notebook` - Fabric notebooks
143- `.DataPipeline` - Data pipelines
144- `.Lakehouse` / `.Warehouse`/ `.SQLDatabase` - Data artifacts
145- `.SparkJobDefinition` - Spark jobs
146- `.AISkill` - Fabric Data Agents
147- `.MirroredDatabase` / `.MirroredWarehouse` - Mirrored databases
148- `.Environment` - Spark environments
149- `.UserDataFunction` - User data functions
150
151Full 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.
152
153
154### JMESPath Queries
155
156Filter and transform JSON responses with `-q`:
157
158```bash
159# Get single field
160-q "id"
161-q "displayName"
162
163# Get nested field
164-q "properties.sqlEndpointProperties"
165-q "definition.parts[0]"
166
167# Filter arrays
168-q "value[?type=='Lakehouse']"
169-q "value[?contains(name, 'prod')]"
170
171# Get first element
172-q "value[0]"
173-q "definition.parts[?path=='model.tmdl'] | [0]"
174```
175
176### Using `fab api`
177
178`fab` has an api escape hatch that lets you use any API even if it doesn't have primary commands.
179
180
181#### Variable Extraction Pattern
182
183To use `fab api` you need item IDs. Extract them like this:
184
185```bash
186WS_ID=$(fab get "ws.Workspace" -q "id" | tr -d '"')
187MODEL_ID=$(fab get "ws.Workspace/Model.SemanticModel" -q "id" | tr -d '"')
188
189# Then use in API calls
190fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'
191```
192
193
194#### Admin APIs (Requires Admin Role)
195
196Don't use admin commands or APIs if the user doesn't have Admin access. Here's some examples:
197
198```bash
199# Find semantic models by name (cross-workspace)
200fab api "admin/items" -P "type=SemanticModel" -q "itemEntities[?contains(name, 'Sales')]"
201
202# Find all notebooks
203fab api "admin/items" -P "type=Notebook" -q "itemEntities[].{name:name,workspace:workspaceId}"
204
205# Find all lakehouses
206fab api "admin/items" -P "type=Lakehouse"
207
208# Common types: SemanticModel, Report, Notebook, Lakehouse, Warehouse, DataPipeline, Ontology
209```
210
211For full admin API reference (cross-workspace discovery, tenant settings read/update, capacity/domain/workspace overrides, activity events): [admin.md](./references/admin.md)
212
213
214### Error Handling & Debugging
215
216```bash
217# Show response headers
218fab api workspaces --show_headers
219
220# Verbose output
221fab get "Production.Workspace/Item" -v
222
223# Save responses for debugging
224fab api workspaces -o /tmp/workspaces.json
225```
226
227
228## Common workflows
229
230These are the most common workflows you'll encounter in Fabric
231
232### Finding or exploring workspaces, items, or metadata
233
234| Command | Purpose | Example |
235|---|---|---|
236| `fab ls` | List workspaces / items | `fab ls "Sales.Workspace" -l` |
237| `fab exists` | Check if a path exists | `fab exists "Sales.Workspace/Model.SemanticModel"` |
238| `fab get` | Get item details | `fab get "Sales.Workspace" -q "id"` |
239| `fab desc` | Supported commands per type | `fab desc .SemanticModel` |
240
241Flags:
242- `-l` (long listing)
243- `-a` (show hidden items)
244- `-q` (JMESPath filter)
245- `-v` (verbose output)
246- `-o` (save response to file)
247
248Fabric discovery follows a drill-down pattern:
249
250- Browsing:
251 - List workspaces: `fab ls`
252 - List items in a workspace: `fab ls "ws.Workspace" -l`
253 - Confirm a path exists: `fab exists "ws.Workspace/Item"`
254 - Check what commands an item type supports: `fab desc .<ItemType>`
255- Inspection:
256 - Get item details: `fab get "ws.Workspace/Item"`
257 - Pull a single field: `fab get "ws.Workspace" -q "id"`
258- Cross-workspace search:
259 - Routine search across name, description, workspace: `fab find '<text>' -P type=<Type> -l`
260 - 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
261 - Downstream reports for a given model: [`scripts/get-downstream-reports.py`](./scripts/get-downstream-reports.py)
262 - Tenant-wide admin APIs: [admin.md](./references/admin.md)
263
264Check references before exploring:
265
266- [workspaces.md](./references/workspaces.md)
267- [folders.md](./references/folders.md)
268- [admin.md](./references/admin.md)
269- [reference.md](./references/reference.md)
270
271
272### Querying data
273
274| Command | Purpose | Example |
275|---|---|---|
276| `fab get -q "definition"` | Get model schema | `fab get "ws.Workspace/Model.SemanticModel" -q "definition" -f` |
277| `fab api -A powerbi` | Execute DAX | `fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/executeQueries" -X post -i '{"queries":[{"query":"EVALUATE..."}]}'` |
278| `fab ls` | Browse files / tables | `fab ls "ws.Workspace/LH.Lakehouse/Files"` |
279| `fab table schema` | Lakehouse table schema | `fab table schema "ws.Workspace/LH.Lakehouse/Tables/sales"` |
280| `fab cp` | Upload / download OneLake file | `fab cp ./local.csv "ws.Workspace/LH.Lakehouse/Files/"` |
281| `duckdb` + `delta_scan` | Query Delta tables (requires DuckDB) | `duckdb -c "... delta_scan('abfss://<ws-id>@onelake.../<lh-id>/Tables/schema/table')"` |
282| `duckdb` + `read_csv/json` | Query raw files (requires DuckDB) | `duckdb -c "... read_csv('abfss://.../Files/data.csv')"` |
283
284Flags:
285- `-A fabric|powerbi|storage|azure` (API audience)
286- `-X get|post|put|delete|patch` (HTTP method)
287- `-i` (JSON body or file)
288- `-f` (skip sensitivity prompt on definition pulls).
289
290Fabric exposes three query paths depending on the source; always prefer the wrapper scripts -- they resolve IDs, hosts, and auth for you:
291
292- Semantic models (DAX):
293 - Find model fields first: `fab get "ws.Workspace/Model.SemanticModel" -q "definition"`
294 - Query: [`scripts/execute_dax.py`](./scripts/execute_dax.py)
295- Lakehouses / Warehouses via Delta over OneLake (DuckDB):
296 - Query a single table: [`scripts/query_lakehouse_duckdb.py`](./scripts/query_lakehouse_duckdb.py) (use `tbl` as a placeholder and pass `-t schema.table`)
297 - Multi-table joins or raw files in `Files/`: pass `--sql` with your own `delta_scan()` / `read_csv` / `read_json_auto` calls
298 - Optionally scaffold a Direct Lake model instead: [`scripts/create_direct_lake_model.py`](./scripts/create_direct_lake_model.py)
299- Lakehouse SQL endpoint, Warehouse, or SQL Database (T-SQL):
300 - Prefer the `fabric-sql` MCP `execute_query(workspaceId, itemId, query)` when loaded; server-side, no local tooling
301 - Fall back to [`scripts/query_sql_endpoint.py`](./scripts/query_sql_endpoint.py) (`sqlcmd`; auto-detects host per item type, reuses `az login` via `ActiveDirectoryAzCli`) when the MCP is unavailable
302 - Prefer either over DuckDB when you need `INFORMATION_SCHEMA`, `sys.*` metadata, CTEs, or window functions
303 - Full route priority: [querying-data.md](./references/querying-data.md#querying-the-sql-endpoint-route-priority)
304
305Check references before writing queries:
306
307- [querying-data.md](./references/querying-data.md)
308- [semantic-models.md](./references/semantic-models.md)
309- [lakehouses.md](./references/lakehouses.md)
310- [warehouses.md](./references/warehouses.md)
311- [sql-databases.md](./references/sql-databases.md)
312
313
314### Changing metadata or access (descriptions, tags, endorsement, properties, bindings, permissions)
315
316| Command | Purpose | Example |
317|---|---|---|
318| `fab set` | Update property | `fab set "ws.Workspace/Item" -q displayName -i "New Name"` |
319| `fab mv` | Rename / move item | `fab mv "ws/Old.Notebook" "ws/New.Notebook" -f` |
320| `fab acl ls` | List permissions | `fab acl ls "ws.Workspace"` |
321| `fab acl set` | Grant permission | `fab acl set "ws.Workspace" -I <objectId> -R Member` |
322| `fab acl rm` | Revoke permission | `fab acl rm "ws.Workspace" -I <upn>` |
323| `fab label set` | Set sensitivity label | `fab label set "ws/Nb.Notebook" --name Confidential` |
324
325Flags:
326- `-q <field>` + `-i <value>` (set a single property)
327- `-I` (object ID or UPN for `fab acl`)
328- `-R Admin|Member|Contributor|Viewer` (role for `fab acl set`)
329- `-f` (skip confirmation; ask user first if sensitivity labels are in play)
330
331Metadata and access changes fall into a few groups:
332
333- Properties (displayName, description, sensitivity config):
334 - Native update: `fab set "<path>" -q <field> -i "<value>"`
335 - Capture current state first so you can revert: `fab get -v -o /tmp/before.json`
336- Endorsement, certification, and tags (no first-class `fab` commands):
337 - Patch via `fab api` with item-specific endpoints
338 - Tag workflow: [tags.md](./references/tags.md)
339 - Endorsement patterns: [reference.md](./references/reference.md)
340- Folder placement:
341 - Move items between workspace subfolders: [folders.md](./references/folders.md)
342- Access control and sensitivity labels:
343 - Grant / revoke: `fab acl set`, `fab acl rm`
344 - Set sensitivity label: `fab label set`
345 - Verify the principal first: `az ad user show`
346 - Never change permissions or labels without explicit user confirmation
347- Bindings:
348 - Rebind a thin `.Report` to a different `.SemanticModel`: [reports.md](./references/reports.md)
349 - Semantic model source rebinds (e.g. swap a lakehouse): [semantic-models.md](./references/semantic-models.md)
350
351Check references before changing metadata:
352
353- [reference.md](./references/reference.md)
354- [tags.md](./references/tags.md)
355- [folders.md](./references/folders.md)
356- [reports.md](./references/reports.md)
357- [semantic-models.md](./references/semantic-models.md)
358
359### Working with workspaces
360
361| Command | Purpose | Example |
362|---|---|---|
363| `fab mkdir` | Create workspace / item | `fab mkdir "New.Workspace" -P capacityname=MyCapacity` |
364| `fab assign` | Attach capacity / domain | `fab assign .capacities/cap.Capacity -W ws.Workspace -f` |
365| `fab unassign` | Detach capacity / domain | `fab unassign .capacities/cap.Capacity -W ws.Workspace` |
366| `fab start` / `fab stop` | Resume / pause capacity | `fab start .capacities/cap.Capacity` |
367| `fab cp -r` | Fork workspace | `fab cp "dev.Workspace" "prod.Workspace" -r -f` |
368| `fab rm` | Soft-delete (see [recovery](./references/reference.md#recovering-deleted-items)) | `fab rm "ws/Item.Type" -f` |
369
370Flags:
371- `-P key=value` (creation params for `fab mkdir`)
372- `-W` (target workspace for `fab assign` / `fab unassign`)
373- `-r` (recursive copy/move)
374- `-bpc` (block on path collision for `fab cp`)
375- `-f` (skip confirmation)
376
377Workspace-scope operations fall into a few groups:
378
379- Create and provision:
380 - Create workspace: `fab mkdir "<Name>.Workspace" -P capacityname=<cap>`
381 - Attach capacity or domain: `fab assign .capacities/<cap>.Capacity -W <ws>.Workspace`
382 - Planning context, create/get/set surface, large storage format, Spark pools, OneLake defaults, Git: [workspaces.md](./references/workspaces.md)
383- Copy, fork, download:
384 - Duplicate a workspace in-tenant: `fab cp -r "dev.Workspace" "prod.Workspace"`
385 - Dry-run the source tree first: `fab ls "dev.Workspace"`
386 - Full local snapshot (items + lakehouse files): [`scripts/download_workspace.py`](./scripts/download_workspace.py)
387- Permissions:
388 - Inspect / grant / revoke: `fab acl ls | set | rm`
389 - Tenant-wide governance audit: use the `audit-tenant-settings` skill from the `fabric-admin` plugin
390- Connections and gateways (bound to, but outside, the workspace):
391 - Credential types (WorkspaceIdentity, SPN, Basic), OAuth2 limits: [connections.md](./references/connections.md)
392 - Datasource binding, credential rotation: [gateways.md](./references/gateways.md)
393- Folders inside a workspace:
394 - Layout, nesting, conventions: [folders.md](./references/folders.md)
395
396Check references before modifying workspaces:
397
398- [workspaces.md](./references/workspaces.md)
399- [folders.md](./references/folders.md)
400- [connections.md](./references/connections.md)
401- [gateways.md](./references/gateways.md)
402
403
404### Executing or scheduling jobs (notebooks, notebook cells, pipelines, semantic model refresh)
405
406| Command | Purpose | Example |
407|---|---|---|
408| `fab job run` | Run synchronously | `fab job run "ws/ETL.Notebook" -P date:string=2025-01-01` |
409| `fab job start` | Run asynchronously | `fab job start "ws/ETL.Notebook"` |
410| `fab job run-list` | List executions | `fab job run-list "ws/Nb.Notebook"` |
411| `fab job run-status` | Check status | `fab job run-status "ws/Nb.Notebook" --id <job-id>` |
412| `fab job run-cancel` | Cancel a job | `fab job run-cancel "ws/Nb.Notebook" --id <job-id> -w` |
413| `scripts/run_notebook_checked.py` | Run a notebook + verify its exit value (status `Completed` ≠ ETL succeeded) | `python3 scripts/run_notebook_checked.py "ws/ETL.Notebook"` |
414| `fab api -A powerbi .../refreshes` | Trigger semantic model refresh | `fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}'` |
415
416Flags:
417- `-P key:type=value` (parameters, type is `string|int|bool`)
418- `--id` (job run ID)
419- `-w` (wait on cancel)
420- `--timeout` (overall timeout for synchronous runs)
421- `--polling_interval` (status poll cadence)
422
423Jobs map to different endpoints depending on item type:
424
425- Notebooks and pipelines:
426 - Run synchronously: `fab job run "ws/ETL.Notebook" -P date:string=2025-01-01`
427 - Run asynchronously: `fab job start "ws/ETL.Notebook"`
428 - Check status: `fab job run-status "ws/Nb.Notebook" --id <job-id>`
429 - List history: `fab job run-list "ws/Nb.Notebook"`
430 - Verify the REAL outcome: a job `Completed` only means the process finished -- a notebook can catch its own exception and exit a failure payload while still showing `Completed`. Read its exit value, or use [`scripts/run_notebook_checked.py`](./scripts/run_notebook_checked.py); details in [notebooks.md](./references/notebooks.md#the-notebooks-exit-value-the-only-reliable-success-signal)
431 - Python / PySpark kernels, Livy sessions, cell-level CRUD: [notebooks.md](./references/notebooks.md)
432- Semantic model refresh (not exposed as `fab job`):
433 - Trigger: `fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes" -X post -i '{"type":"Full"}'`
434 - Check current run before starting a new one (409 if already running): `fab api -A powerbi "groups/<ws-id>/datasets/<model-id>/refreshes?\$top=1"`
435 - Enhanced refresh, incremental policies, partition targeting: [semantic-models.md](./references/semantic-models.md)
436- Dataflow refresh:
437 - Gen1 and Gen2 have different endpoints: [dataflows.md](./references/dataflows.md)
438- Scheduling:
439 - Per-item schedules via the scheduler API: [notebooks.md](./references/notebooks.md), [reference.md](./references/reference.md)
440
441Check references before running jobs:
442
443- [notebooks.md](./references/notebooks.md)
444- [semantic-models.md](./references/semantic-models.md)
445- [dataflows.md](./references/dataflows.md)
446- [reference.md](./references/reference.md)
447
448
449### Fabric admin operations (auditing, management)
450
451| Command | Purpose | Example |
452|---|---|---|
453| `fab api "admin/items"` | Cross-workspace item search | `fab api "admin/items" -P "type=SemanticModel" -q "itemEntities[?contains(name,'Sales')]"` |
454| `fab api "admin/workspaces"` | Workspace inventory | `fab api "admin/workspaces"` |
455| `fab api "admin/tenantsettings"` | Tenant settings | `fab api "admin/tenantsettings"` |
456| `fab api "admin/capacities"` | Capacity inventory | `fab api "admin/capacities"` |
457| `fab api -X post .../update` | Update tenant setting | `fab api -X post "admin/tenantsettings/<name>/update" -i body.json` |
458
459Flags:
460- `-P key=value` (query params, e.g. `type=SemanticModel`)
461- `-q` (JMESPath filter)
462- `-X post` + `-i` (write ops)
463- `--show_headers` (inspect `Retry-After` on 429)
464
465Admin-scope work is gated behind the Fabric / Power BI admin role. Confirm access first with `fab api "admin/capacities" 2>&1 | head -5`; if it errors, stop rather than retry.
466
467Two entry points cover most admin tasks:
468
469- Governance audits (tenant settings, delegated overrides, Entra SG scoping):
470 - Use the `audit-tenant-settings` skill from the `fabric-admin` plugin. It owns the curated metadata baseline, the audit + change-detection script, delegated-override enumeration, and the Entra SG investigation workflow.
471 - Invoke it whenever the question combines tenant posture with group membership, override scope, or drift against the baseline.
472- Raw admin APIs (cross-workspace search, activity events, artifact access, item search):
473 - Patterns in [admin.md](./references/admin.md)
474 - Rate limit: 25 write requests / minute; honor `Retry-After` on 429
475 - Print the exact command and wait for user confirmation before any destructive admin operation
476
477Check references before admin work:
478
479- [admin.md](./references/admin.md)
480- [permissions.md](./references/permissions.md) for workspace / item ACL exposure audits
481
482
483### Definitions and deployment (item definitions, deployment pipelines, git integration, cicd)
484
485| Command | Purpose | Example |
486|---|---|---|
487| `fab get -q "definition"` | Read raw definition | `fab get "ws/Model.SemanticModel" -q "definition" -f` |
488| `fab export` | Export item to local | `fab export "ws/Nb.Notebook" -o ./backup -f` |
489| `fab import` | Import item from local | `fab import "ws/Nb.Notebook" -i ./backup/Nb.Notebook -f` |
490| `fab cp` | Copy between workspaces | `fab cp "dev/Item" "prod.Workspace" -f` |
491| `fab api "deploymentPipelines"` | Deployment pipelines API | `fab api "deploymentPipelines" -q "value[]"` |
492
493Flags:
494- `-o` (output path for `fab export`)
495- `-i` (input path or JSON body for `fab import`)
496- `--format` (definition format for export / import)
497- `-f` (skip overwrite and sensitivity prompts)
498
499> [!IMPORTANT]
500> **The poll interval is by far the biggest performance lever for any definition change.**
501> Creating or updating an item definition is a long-running operation (LRO): the API returns
502> `202 Accepted` with a `Retry-After: 20` header. `fab import`, `nb create`, and `nb cell edit`
503> wait roughly that long between status polls, so a notebook that the server finishes in ~1s
504> takes them 25-60s. Neither `fab` nor `nb` exposes a knob to change that interval.
505> For notebook definition changes, strongly prefer [`scripts/deploy_notebook.py`](./scripts/deploy_notebook.py),
506> which polls the LRO every ~0.3s (tunable via `--poll-interval`) and creates in ~1-2s or updates
507> in place in ~1s. Auto-detects create vs update. When you must roll your own for another item
508> type, the rule is the same: poll `updateDefinition` / create at ~0.3s, not the advertised 20s.
509> ```bash
510> python3 scripts/deploy_notebook.py "ws.Workspace/ETL.Notebook" -i ./ETL.Notebook # create or update in place
511> ```
512
513Every Fabric item has a serializable definition. Move definitions between environments depending on scope:
514
515- Single item:
516 - Round-trip locally: `fab export` then `fab import` (always `mkdir -p` the output directory first; `fab export` does not create intermediate directories and fails with `[InvalidPath]`)
517 - Same-tenant shortcut, no local hop: `fab cp "dev/Item" "prod.Workspace"`
518- Semantic model as PBIP (TMDL + blank report):
519 - Export the model with `fab export`, create the report with `pbir new report`, then combine
520 them with `pbir report merge-to-thick`; see [import-download-deploy.md](./references/import-download-deploy.md)
521- Full workspace snapshot (items + lakehouse files):
522 - Backups, offline analysis, cross-tenant forks: [`scripts/download_workspace.py`](./scripts/download_workspace.py)
523- Promotion between Dev, Test, Prod:
524 - Fabric deployment pipelines API (covers all item types)
525 - Power BI pipelines API (Power BI items only, but finer-grained deploy flags like `allowPurgeData`, `allowTakeOver`)
526 - When to use each, selective deploy, LRO polling: [deployment-pipelines.md](./references/deployment-pipelines.md)
527- Git integration (connect workspace to repo, branch, commit, update from git):
528 - Workspace git section in [workspaces.md](./references/workspaces.md)
529
530Check references before deploying:
531
532- [import-download-deploy.md](./references/import-download-deploy.md) ; export / import / copy / move, PBIP round-trips, migration patterns, rebinding gotchas
533- [deployment-pipelines.md](./references/deployment-pipelines.md)
534- [semantic-models.md](./references/semantic-models.md)
535- [reports.md](./references/reports.md)
536- [paginated-reports.md](./references/paginated-reports.md)
537- [notebooks.md](./references/notebooks.md)
538- [workspaces.md](./references/workspaces.md)
539
540
541## Related skills
542
543- `audit-tenant-settings` (in the `fabric-admin` plugin) ; Fabric governance workflow covering tenant settings, delegated overrides (capacity / domain / workspace), and the Entra security groups those settings reference. Read-only; holds the curated metadata baseline and the audit + change-detection script.
544
545## Gotchas
546
547- **IMPORTANT:** DON'T try to use `fab ls` on items that aren't data items (.Lakehouse, .Warehouse, etc); use `fab ls` to find workspaces and items, and use `fab get` to look at definitions
548- ALWAYS Use the `-f` flag when using `fab get`, `fab import`, `fab export`, etc. as described above
549- ONLY fallback to `fab api` when a command doesn't exist
550- **Definition changes feel slow but aren't:** `fab import` / `nb create` / `nb cell edit` take 25-60s to push a notebook definition only because they poll the LRO at the server's `Retry-After: 20`. The work is ~1s. Use [`scripts/deploy_notebook.py`](./scripts/deploy_notebook.py) (tight-polls at ~0.3s) for definition changes; the poll interval is the single biggest lever
551
552## References
553
554**Reference map** (which references cluster together; follow the links between them, not just this list):
555
556```
557etl / notebooks
558 notebooks.md ── run jobs, exit value, scheduling
559 ├─ querying-data.md ── nb exec / Livy, DuckDB/sqlcmd, SQL-endpoint sync
560 └─ lakehouses.md ── attach, table ops, OneLake shortcuts, SQL-endpoint id
561 (cross-plugin) executing-spark, using-duckdb ── etl plugin: ephemeral Spark, local Delta
562
563data items
564 lakehouses.md · warehouses.md · sql-databases.md · semantic-models.md
565 └─ all feed querying-data.md (route priority) and notebooks.md (load then read)
566
567governance / deploy
568 admin.md · permissions.md · tags.md · folders.md
569 import-download-deploy.md ─ deployment-pipelines.md ─ workspaces.md (git status)
570 (cross-plugin) audit-tenant-settings ── fabric-admin plugin
571```
572
573**Skill references:**
574
575- [Import, Download, and Deploy](./references/import-download-deploy.md) - Export / import / copy / move items, PBIP round-trips, dev-to-prod migration patterns
576- [Querying Data](./references/querying-data.md) - Query semantic models in DAX and lakehouses or warehouses in SQL with DuckDB
577- [Lakehouses](./references/lakehouses.md) - Endpoints, file/table operations, OneLake paths
578- [Warehouses](./references/warehouses.md) - Create, browse, query via DuckDB, load data
579- [SQL Databases](./references/sql-databases.md) - Create, browse, query via DuckDB, auto-mirroring
580- [Semantic Models](./references/semantic-models.md) - TMDL, DAX, refresh, storage mode
581- [Reports](./references/reports.md) - Export, import, visuals, fields
582- [Paginated Reports](./references/paginated-reports.md) - RDL upload, export-to-file, datasources, parameters
583- [Notebooks](./references/notebooks.md) - Python/PySpark kernels, metadata, cell CRUD, Livy execution, scheduling
584- [Workspaces](./references/workspaces.md) - Create, manage, permissions
585- [Permissions](./references/permissions.md) - Sharing and distribution, workspace roles, item permissions, apps, embed, B2B, deployment pipeline permissions, licensing and capacity SKUs
586- [Deployment Pipelines](./references/deployment-pipelines.md) - CI/CD, deploy stages, selective deploy, LRO polling
587- [Dataflows](./references/dataflows.md) - Gen1 and Gen2, refresh, publish, admin
588- [Dashboards](./references/dashboards.md) - Tiles, clone (dashboards are not reports)
589- [Org Apps](./references/org-apps.md) - Read-only API for distributed content packages
590- [Scorecards](./references/scorecards.md) - Goals, check-ins, status rules (Preview API)
591- [Gateways](./references/gateways.md) - Datasources, credentials, dataset binding
592- [Folders](./references/folders.md) - Organize items into folders via API; includes best practices for structuring workspaces
593- [Tags](./references/tags.md) - Create, apply, and audit tenant/domain tags on items and workspaces via `fab api` (no native `fab tag` command)
594- [fab vs az CLI](./references/fab-vs-az-cli.md) - When to use which; capacity, networking, Key Vault, monitoring, CMK, CI/CD
595- [Admin APIs](./references/admin.md) - Cross-workspace search, tenant operations, governance
596- [API Reference](./references/fab-api.md) - Capacities, domains, misc API patterns
597- [Connections](./references/connections.md) - Create, update, list connections programmatically; credential types (WorkspaceIdentity, SPN, Basic); OAuth2 limitations
598- [Service Principals](./references/service-principals.md) - Create an SP with az CLI, grant it workspace access, clear the tenant-setting gate, authenticate `fab` as it (real login vs env-token testing), rotation and teardown
599- [Full Command Reference](./references/reference.md) - All commands detailed
600
601**Scripts** (scripts that you can execute):
602
603- [search_across_workspaces.py](./scripts/search_across_workspaces.py) ; cross-workspace governance complement to `fab find` (last visit, last refresh, owner, storage mode, capacity SKU, Copilot readiness); see [workspaces.md](./references/workspaces.md#cross-workspace-search) for when to choose which
604- [get-downstream-reports.py](./scripts/get-downstream-reports.py) ; find all reports connected to a given semantic model across accessible workspaces (no admin required)
605- [execute_dax.py](./scripts/execute_dax.py) ; execute DAX queries against semantic models; output as table, csv, or json
606- [query_lakehouse_duckdb.py](./scripts/query_lakehouse_duckdb.py) ; query lakehouse or warehouse Delta tables via DuckDB against OneLake (reuses `az login`); output as table, csv, or json
607- [query_sql_endpoint.py](./scripts/query_sql_endpoint.py) ; query lakehouse SQL endpoint, warehouse, or SQL database via `sqlcmd` (reuses `az login` through `ActiveDirectoryAzCli`); output as table, csv, or json
608- [create_direct_lake_model.py](./scripts/create_direct_lake_model.py) ; create a Direct Lake semantic model from lakehouse tables
609- [download_workspace.py](./scripts/download_workspace.py) ; download a full workspace with all item definitions and lakehouse files
610- [run_notebook_checked.py](./scripts/run_notebook_checked.py) ; run a notebook and check its exit value, exiting non-zero when the notebook's own `{ok:false}` verdict fails despite a `Completed` job status (reads the exit value via the notebook job-instance beta endpoint)
611- [deploy_notebook.py](./scripts/deploy_notebook.py) ; create or update a notebook definition fast (~1-2s) by tight-polling the LRO instead of the CLI's ~20s `Retry-After` cadence; auto-detects create vs update, `--poll-interval` is the performance lever. Strongly prefer this over `fab import` / `nb` for any notebook definition change
612
613See [scripts/README.md](./scripts/README.md) for detailed usage, arguments, and examples. Always search the `scripts/` folder before writing a new helper; a script may already exist for the task.
614
615**External references** (request markdown when possible):
616
617- fab CLI: [GitHub Source](https://github.com/microsoft/fabric-cli) | [Docs](https://microsoft.github.io/fabric-cli/)
618- Microsoft: [Fabric CLI Learn](https://learn.microsoft.com/en-us/rest/api/fabric/articles/fabric-command-line-interface)
619- APIs: [Fabric API](https://learn.microsoft.com/en-us/rest/api/fabric/articles/) | [Power BI API](https://learn.microsoft.com/en-us/rest/api/power-bi/)
620- DAX: [dax.guide](https://dax.guide/) - use `dax.guide/<function>/` e.g. `dax.guide/addcolumns/`
621- Power Query: [powerquery.guide](https://powerquery.guide/) - use `powerquery.guide/function/<function>`
622- [Power Query Best Practices](https://learn.microsoft.com/en-us/power-query/best-practices)
623
624---
625
626**Source:** [`data-goblin/power-bi-agentic-development`](https://github.com/data-goblin/power-bi-agentic-development) → `plugins/fabric-cli/skills/fabric-cli/SKILL.md`