fabric-cli

# Fabric CLI (`fab`) Filesystem-style CLI over the Fabric + Power BI REST APIs. Paths use `Workspace.Workspace/Item.ItemType/...`. The `.ItemType` suffix is **mandatory** on items. Workspaces use `.Workspace`; hidden roots like `.capacities`, `.connections`, `.domains`, `.gateways` expose tenant resources. **Version / install:** v1.5 went GA March 2026; current is v1.7.x (v1.7.0 shipped 2026-08-18, after v1.6.1 on 2026-04-29). Install with `pip install ms-fabric-cli` or `uv tool install ms-fabric-cli`. Requires Python 3.10, 3.11, 3.12, or 3.13. Pre-installed in Fabric Notebooks (no install step needed when running `!fab ...` from a notebook cell). Confirm version with `fab --version`. Canonical per-command reference: [microsoft.github.io/fabric-cli](https://microsoft.github.io/fabric-cli/). Release notes: [github.com/microsoft/fabric-cli/releases](https://github.com/microsoft/fabric-cli/releases). **Interactive (REPL) mode:** `fab config set mode interactive` switches `fab` to a persistent shell where commands no longer need the `fab` prefix and `cd` state survives between calls. Default is command-line mode. **AI assets (v1.5+):** The repo's [`.ai-assets/`](https://github.com/microsoft/fabric-cli/tree/main/.ai-assets) folder bundles `context/`, `modes/`, `prompts/`, and `skills/` files designed to be loaded by AI coding assistants (Copilot, Claude, Cursor) so the assistant can author `fab` invocations correctly. These are *consumable artifacts*, not CLI verbs — there is no `fab agent` or `fab ai` subcommand. ## Authentication `fab` reuses the current Azure CLI session (`az login`). It auto-acquires tokens for Fabric and Power BI audiences. Storage / OneLake operations via `fab api -A storage` require the same Az CLI session. `fab auth` tokens do **not** work for OneLake storage calls from external tools — acquire via `az account get-access-token --resource https://storage.azure.com` instead (OneLake's audience is Azure Storage, not the Fabric API). ## Path Syntax ``` Workspace.Workspace/Item.ItemType[/Files|Tables/...] .capacities/MyCap.Capacity .connections/conn.Connection .domains/Analytics.Domain .gateways/gw.Gateway ``` Names with spaces or apostrophes work inside double quotes with no escaping: `"Claude Code's Workspace.Workspace"`. ## Core Command Reference ### Navigation & Discovery | Command | Purpose | |---|---| | `fab ls [path]` | List workspaces / items / files / tables | | `fab ls -l` | Long format | | `fab ls -a` | Include hidden roots | | `fab ls -q "<jmespath>"` | Filter server response (replaces many `fab api` calls) | | `fab cd <path>` | Change working path (session-scoped) | | `fab pwd` | Current path | | `fab exists <path>` | Returns `* true` / `* false` | | `fab get <path> [-v] [-q <jmespath>] [-o <file>]` | Item details; `-v` all properties | | `fab desc .<ItemType>` | List commands supported by an item type | | `fab find "<text>" [-P type=[...]] [-l]` | OneLake-catalog search across all workspaces by display name / description / workspace name (**v1.6+**). `-P` uses `key=value` / `key!=value` with `[a,b]` bracket syntax (distinct from the JSON-array form `fab deploy` uses) | | `fab open <path>` | Open the workspace or item in the browser | ### Item CRUD | Command | Purpose | |---|---| | `fab mkdir <path> [-P key=value,...]` | Create workspace or item; `-P capacityname=...` for workspaces | | `fab set <path> -q <prop> -i <value>` | Update a single property (e.g. `displayName`, `description`, `semanticModelId`) | | `fab rm <path> -f [--hard]` | Delete (alias `del`); `--hard` permanently deletes an item (no recovery, **v1.6+**) | | `fab cp <src> <dst> [-r] [-f] [-bpc]` | Copy item or files; `-bpc` blocks cross-folder same-name conflicts | | `fab mv <src> <dst> [-r] [-f]` | Move / rename | | `fab export <path> -o <dir> [-a] [-f] [--format py]` | Export item definition; `-a` entire workspace | | `fab bulk-export <path> -o <dir> --recursive [-f]` | Export every supported item in a `.Workspace` or `.Folder`, folder structure kept (**v1.7+**); `--recursive` is required for both targets, and `-f` also waves through a non-empty output dir | | `fab import <path> -i <dir> -f` | Import definition from local folder (`-f` required for non-interactive) | | `fab ln <link-path> --target <target-path>` | Create a OneLake shortcut (alias `mklink`) | ### Access Control | Command | Purpose | |---|---| | `fab acl ls <path> [-l]` | List permissions | | `fab acl get <path> -q "<jmespath>"` | Query specific ACL fields | | `fab acl set <path> -I <objectId> -R <Role> [-f]` | Grant role | | `fab acl rm <path> -I <upn\|clientId> -f` | Revoke | Role values by resource: | Resource | Roles | |---|---| | Workspace | `Admin`, `Member`, `Contributor`, `Viewer` | | Connection | `Owner`, `User`, `UserWithReshare` | | Gateway | `Admin`, `ConnectionCreator`, `ConnectionCreatorWithResharing` | ### Assignment | Command | Purpose | |---|---| | `fab assign .capacities/<C>.Capacity -W <ws>` | Assign workspace to capacity | | `fab assign .domains/<D>.Domain -W <ws> -f` | Assign workspace to domain | | `fab unassign .capacities/<C>.Capacity -W <ws>` | Unassign | | `fab start .capacities/<C>.Capacity` | Resume capacity | | `fab stop .capacities/<C>.Capacity -f` | Pause capacity (stops all workloads) | **The `.domains` verbs are tenant-admin only.** `ls`, `get`, `mkdir`, `rm`, `set`, `assign` and `unassign` against `.domains` all require tenant-level Fabric Administrator privileges (fab docs, 2026-09-12) — the capacity verbs above do not. A workspace admin holding a domain contributor role can still assign their own workspace through the Core API, which `fab` reaches only as a passthrough: `fab api -X post "workspaces/$WS_ID/assignToDomain" -i '{"domainId":"<id>"}'`. See the fabric-catalog-governance skill. ### Labels | Command | Purpose | |---|---| | `fab label list-local` | Configured sensitivity labels | | `fab label set <path> --name <Label>` | Apply label | | `fab label rm <path> -f` | Remove label | **All `fab label` commands require tenant-level Fabric Administrator privileges**, and they resolve names from a local JSON file registered with `fab config set local_definition_labels <json_path>` — `list-local` lists that file, not the tenant's labels. ### Jobs | Command | Purpose | |---|---| | `fab job run <path> [--timeout <s>] [--polling_interval <s>]` | Synchronous run | | `fab job run <path> -P key:type=value,...` | With typed parameters (`string`, `int`, `bool`) | | `fab job start <path>` | Async (fire and forget) | | `fab job run-list <path> [--schedule]` | List runs / scheduled runs | | `fab job run-status <path> --id <jobId>` | Single run status | | `fab job run-cancel <path> --id <jobId> [--wait]` | Cancel | | `fab job run-sch <path> --type daily --interval 10:00 --enable` | Create schedule | | `fab job run-update <path> --id <schedId> [--enable\|--disable]` | Update schedule | | `fab job run-rm <path> --id <schedId> -f` | Delete schedule | `fab job run` auto-selects the right job type per item (notebook / pipeline / semantic model refresh / Spark job) — no manual `jobType` equivalent to the REST API required. ### Tables (Lakehouse) | Command | Purpose | |---|---| | `fab table schema <path>` | Show Delta table schema | | `fab table load <path> --file <Files/...> --mode append\|overwrite` | Load file into Delta table (non-schema lakehouses only) | | `fab table optimize <path> [--vorder] [--zorder col1,col2]` | OPTIMIZE + optional Z-order | | `fab table vacuum <path> --retain_n_hours <N>` | VACUUM | ## REST API Passthrough (`fab api`) Direct REST access when native commands don't cover the operation. ```bash fab api "<endpoint>" # Fabric (default) fab api -A powerbi "<endpoint>" # Power BI fab api -A storage "<onelake path>" # OneLake DFS fab api -A azure "<endpoint>" # Azure RM fab api -X post "<endpoint>" -i '<json>|<file>' # POST with body fab api "<endpoint>" -q "value[0].id" # JMESPath filter ``` **`-i` sets `Content-Type: application/json` for you — don't pass `-H` for it.** `fab api -i` hands the body to the client as `json=`, and the client sets that header on every request that is not a multipart upload; only the separate `--file` path skips it, where `requests` supplies its own boundary type. A `-H` you pass is merged *after* the default, so it overrides rather than supplies. Measured 2026-09-13 against `fab` **1.7.0** (`client/fab_api_client.py`, `commands/api/fab_api_request.py`). Upstream's `skills-for-fabric` adds `-H "Content-Type=application/json"` to its own POST example and Learn's `fab api` example carries it too — on this version that is redundant, not required. If you do pass it, the form is `key=value` (`=`, not `:` — that is `fab` syntax, not HTTP syntax). | Audience | Flag | Base URL | Use Cases | |---|---|---|---| | Fabric | *(default)* | `api.fabric.microsoft.com` | Items, workspaces, operations, admin | | Power BI | `-A powerbi` | `api.powerbi.com` | Refresh, datasets, datasources, deployment pipelines, DAX execute, gateways, activity events, admin | | Storage | `-A storage` | OneLake DFS/Blob | File enumeration with `-P resource=filesystem,recursive=...` | | Azure | `-A azure` | `management.azure.com` | Capacity pause/resume, ARM resources | **Idiom — extract an ID and chain:** ```bash WS_ID=$(fab get "Prod.Workspace" -q "id" | tr -d '"') MODEL_ID=$(fab get "Prod.Workspace/Model.SemanticModel" -q "id" | tr -d '"') fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}' ``` ## Workspace Deployment (`fab deploy`, v1.5+) One-command CI/CD that wraps the [fabric-cicd](https://microsoft.github.io/fabric-cicd/latest/) Python library. Deploys items from local source folders to a target workspace, with environment-aware parameterization. Use this — not `fab api` — for code-first workspace promotion from a Git checkout. ```bash fab deploy --config <config_file> [-tenv <env>] [-P '<json-array>'] [-f] [--output_format <fmt>] [--bulk_publish] ``` | Flag | Purpose | |---|---| | `--config <file>` | **Required.** Path to the deployment YAML. Defines source items, target workspace, item-types-in-scope, and the parameter file. | | `-tenv`, `--target_env <env>` | Picks the env block (e.g. `dev` / `test` / `prod`) from the config + parameter file. | | `-P`, `--params '<json>'` | JSON-array of override parameters: `'[{"p1":"v1","p2":"v2"}]'`. **Quote the whole array** — single object form (`-P key=value`) is *not* what this verb accepts (that's `fab find`'s param style — they differ). | | `-f`, `--force` | Skip interactive confirmation (required in CI). | | `--output_format <fmt>` | Override output format (json / text / etc.). |