fabric-cli

Fabric CLI — Connection Management

Overview

The fabric-app-data CLI manages Fabric data source connections in a fabric.yaml file. It supports multiple profiles (dev, staging, production) and generates TypeScript config that the @microsoft/fabric-app-data consumes at runtime.

Workflow

npx fabric-app-data init                     # 1. Create fabric.yaml
npx fabric-app-data add sales --from-url "https://app.fabric.microsoft.com/..."
                                     # 2. Add connections
npx

Then in your app:

Config discovery

All commands except init walk up the directory tree from the current working directory until they find a fabric.yaml. This means you can run the CLI from any subdirectory of your project (e.g. from src/queries/ or a nested package) and it will pick up the project's root fabric.yaml automatically.

init is the exception — it always writes fabric.yaml to the current working directory, so run it from the project root.

Commands

npx fabric-app-data init

Create a new fabric.yaml in the current directory.

npx fabric-app-data add

Add a connection to a profile. Two modes:

From Fabric portal URL (preferred when the user pastes a URL):

Explicit IDs (use this after search to register a chosen result):

To register a model the user named (rather than linked), run search first, pick the right row, then call add with that row's -w/-i. add never searches — discovery and registration are separate steps.

Important: Prefer the short flags -w and -i (long forms --workspace and --item). Use one consistent style per command.

The URL parser extracts workspace ID, item ID, and type automatically. Supported URL segments: semanticmodels, modeling, lakehouses, warehouses. "me" is accepted as workspace ID for My Workspace items.

Options:

• -p, --profile <name> — target profile (defaults to active)

npx fabric-app-data search

Find a semantic model by display name via the Fabric Catalog Search endpoint. Useful when the user knows the model name but not the workspace + item ids. search only returns results — it never registers a connection; follow it with add -w <workspaceId> -i <itemId>.

Options:

• --type <type> — scope the search to a Fabric item type (default semanticModel). The type is forwarded to Catalog Search, which returns whatever item types it supports.
• -w, --workspace <nameOrId> — restrict results to a single workspace (display name or GUID)
• --max-results <n> — cap on hits returned (default 10, hard cap 50)
• --json — emit machine-readable JSON

Caveats — read before using:

• Catalog Search is fuzzy and tokenized. It never returns empty for any query — even nonsense strings produce ranked hits. A non-empty response does not imply a confident match. Always reason over the displayName values before adding a connection.
• Exit code is 0 when at least one hit is returned, 1 when none are. Use this to branch in scripts.
• Items in your personal My workspace come back with workspaceId set to the me sentinel — pass -w me to add (and to query), since My Workspace has no separate workspace GUID in the Fabric APIs.
• JSON output (--json) is the preferred format for agents: it includes source (catalog / none), workspaceFilter, truncated, and a normalized results[] shape (itemId, itemType, displayName, description, workspaceId, workspaceName) — enough metadata to disambiguate same-named models in different workspaces.

npx fabric-app-data remove <alias>

Remove a connection by alias.

npx fabric-app-data list

List all connections in a profile.

npx fabric-app-data use <profile>

Switch the active profile and auto-regenerate the config file.

npx fabric-app-data generate

Generate fabric.generated.ts from the active profile.

npx fabric-app-data query

Execute a DAX query against a semantic model using the same SDK pipeline as the running app. Aliases: execute, exec.

Options:

• -q, --query <query> — inline DAX query text
• -f, --file <path> — path to a .dax file (alternative to --query)
• -l, --limit <rows> — maximum rows to return (default: 1000, max: 1000)
• -p, --profile <name> — profile name (defaults to activeProfile)

Result trimming: By default, results are capped at 1000 rows to keep output manageable. When the result is trimmed, the JSON output includes a _cliWarning field indicating how many rows were returned out of the total. This is a CLI-only limitation — the full dataset is available in the running app. If more rows are needed, refine the DAX query with filters or aggregations instead.

fabric.yaml Structure

Generated Output

fabric.generated.ts exports a plain config object:

Add fabric.generated.ts to .gitignore — regenerate from fabric.yaml as needed.