microsoft/fabric-cli-core

Fabric CLI Core

This skill defines safe, consistent defaults for an AI agent helping users operate Microsoft Fabric via the Fabric CLI (fab).

1 - Fabric CLI mental model (paths and entities)

Automation Scripts

Ready-to-use Python scripts for core CLI tasks. Run any script with --help for full options.

| Script | Purpose | Usage | |--------|---------|-------| | health_check.py | Verify CLI installation, auth status, and connectivity | python scripts/health_check.py [--workspace WS] |

Scripts are located in the scripts/ folder of this skill.

Paths and Entities

• Treat Fabric as a filesystem-like hierarchy with consistent dot (.) entity suffixes in paths (e.g., .Workspace, .Folder, .SemanticModel).
• The hierarchy structure is:
  • Tenant: The top-level container for everything.
  • Workspace: Personal or team workspace holding folders, items, and workspace-level elements.
  • Folder: Container for organizing items within a workspace (supports ~10 levels of nesting).
  • Item: Individual resource within a workspace or folder (e.g., Notebook, SemanticModel, Lakehouse).
  • OneLakeItem: OneLake storage item residing within a Lakehouse (tables, files, etc.).
• Prefer and generate paths like:
  • /Workspace1.Workspace/Notebook1.Notebook
  • /Workspace1.Workspace/FolderA.Folder/SemanticModel1.SemanticModel
  • /Workspace1.Workspace/FolderA.Folder/lh1.Lakehouse/Tables (OneLakeItem)
• When a user provides an ambiguous identifier, ask for the full path (or infer with stated assumptions).

2 - Modes (interactive vs command line)

• Be explicit about which mode a user is in:
  • Interactive mode behaves like a REPL and runs commands without the fab prefix.
  • Command line mode runs one command per invocation and is best for scripts/automation.
• The selected mode is preserved between sessions. If a user exits and logs back in, the CLI resumes in the same mode last used.
• When you provide instructions, show commands in command line mode unless the user says they're in interactive mode.

3 - Authentication (public-safe guidance)

• Prefer these auth patterns and do not invent new flows:
  1. Interactive user: fab auth login (browser/WAM where supported).
  2. Service principal (secret/cert): use environment variables / secure mechanisms; avoid embedding secrets in files.
  3. Service principal (federated credential): use the federated token environment variable (FAB_SPN_FEDERATED_TOKEN) and do not persist the raw token.
  4. Managed identity: supported for Azure-hosted workloads; no credentials required.
• Never ask users to paste secrets into chat or print them back.

4 - Sensitive data handling (strict)

• Never log or output tokens, passwords, client secrets, or raw federated tokens.
• Validate all user inputs that could affect security:
  • Paths: Sanitize file paths and API parameters.
  • GUIDs: Validate resource identifiers before use.
  • JSON: Validate JSON inputs for proper format.
• If a user shares sensitive strings, advise rotating/regenerating them and moving to secure storage.

5 - Hidden entities and discovery

• Hidden entities are special resources not normally visible, following a dot-prefixed naming convention (similar to UNIX hidden files).
• Tenant-level hidden entities (accessed from root):
  • .capacities — fab ls .capacities / fab get .capacities/<name>.Capacity
  • .gateways — fab ls .gateways / fab get .gateways/<name>.Gateway
  • .connections — fab ls .connections / fab get .connections/<name>.Connection
  • .domains — fab ls .domains / fab get .domains/<name>.Domain
• Workspace-level hidden entities (accessed within a workspace):
  • .managedidentities — fab ls ws1.Workspace/.managedidentities
  • .managedprivateendpoints — fab ls ws1.Workspace/.managedprivateendpoints
  • .externaldatashares — fab ls ws1.Workspace/.externaldatashares
  • .sparkpools — fab ls ws1.Workspace/.sparkpools
• To show hidden resources, recommend ls -a / ls --all.

6 - Errors and troubleshooting guidance

• When describing failures, include:
  • What the command was trying to do
  • The likely cause
  • The next actionable step
• If the CLI surfaces an error code/message, keep it intact and do not paraphrase away the key identifiers. (Fabric CLI emphasizes stable error codes/messages.)
• Include request IDs for API errors to aid debugging when available.

7 - Output conventions for the agent

• Default to concise, runnable steps.
• When recommending commands, include:
  • Preconditions (auth, correct workspace/path)
  • Expected result
  • How to verify (e.g., follow-up fab ls / fab get)

8 - Safety defaults

• Ask before suggesting commands that delete, overwrite, or change access/permissions.
• If the user explicitly confirms, proceed with a clear rollback note when possible.

9 - Platform and troubleshooting reference

• Supported platforms: Windows, Linux, macOS.
• Supported shells: zsh, bash, PowerShell, cmd (Windows command prompt).
• Python versions: 3.10, 3.11, 3.12, 3.13.
• CLI file storage (useful for troubleshooting):
  • Config files are stored in ~/.config/fab/:
    • cache.bin — encrypted auth token cache
    • config.json — non-sensitive CLI settings
    • auth.json — non-sensitive auth info
    • context-<session_id> — path context for command-line mode sessions
  • Debug logs are written to:
    • Windows: %AppData%/fabcli_debug.log
    • macOS: ~/Library/Logs/fabcli_debug.log
    • Linux: ~/.local/state/fabcli_debug.log

10 - Critical operational rules

• First run: Always run fab auth status to verify authentication before executing commands. If not authenticated, ask the user to run fab auth login.
• Learn before executing: Always use fab --help and fab <command> --help the first time you use a command to understand its syntax.
• Start simple: Try the basic fab command alone first before piping or chaining.
• Non-interactive mode: Use fab in command-line mode when working with coding agents. Interactive mode doesn't work with automation.
• Force flag: Use -f when executing commands if the flag is available to run non-interactively (skips confirmation prompts).
• Verify before acting: If workspace or item name is unclear, ask the user first, then verify with fab ls or fab exists before proceeding.
• Permission errors: If a command is blocked by permissions, stop and ask the user for clarification; never try to circumvent it.

11 - Common item types

| Extension | Description | |-----------|-------------| | .Workspace | Workspace container | | .Folder | Folder within workspace | | .SemanticModel | Power BI dataset/semantic model | | .Report | Power BI report | | .Dashboard | Power BI dashboard | | .Notebook | Fabric notebook | | .Lakehouse | Lakehouse | | .Warehouse | Data warehouse | | .DataPipeline | Data pipeline | | .SparkJobDefinition | Spark job definition | | .Eventstream | Real-time event stream | | .KQLDatabase | KQL database | | .MLModel | ML model | | .MLExperiment | ML experiment | | .Capacity | Fabric capacity (hidden) | | .Gateway | Data gateway (hidden) | | .Connection | Connection (hidden) |

Use fab desc .<ItemType> to explore any item type.

12 - Command references

For detailed command syntax and working examples, see:

• Quick Start Guide — Copy-paste examples for common tasks
• Full Command Reference — All commands with flags and patterns
• Semantic Models — TMDL, DAX queries, refresh, storage modes
• Notebooks — Job execution, parameters, scheduling
• Reports — Export, import, rebind to models
• Workspaces — Create, manage, permissions
• Querying Data — DAX and lakehouse table queries
• API Reference — Direct REST API access patterns
• Create Workspaces — Workspace creation workflows