fabric-cli

name	fabric-cli
description	How to use fabric-app-data CLI to manage Fabric data source connections. Maintain workspace/item IDs in a fabric.yaml file with profiles, add connections by ID or Fabric portal URL, and generate TypeScript config for use with @microsoft/fabric-app-data.

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 fabric-app-data generate -o src/fabric.generated.ts
                                     # 3. Generate TypeScript config

Then in your app:

import { FabricClient } from "@microsoft/fabric-app-data";
import { fabricConfig } from "./fabric.generated.js";

const client = new FabricClient({ proxy, ...fabricConfig });

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 init                    # default "dev" profile
npx fabric-app-data init -p production      # custom profile name
npx fabric-app-data init --force            # overwrite existing

npx fabric-app-data add

Add a connection to a profile. Two modes:

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

npx fabric-app-data add <alias> --from-url "<Fabric portal URL>"

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

npx fabric-app-data add semanticModel <alias> -w <workspaceId> -i <itemId>

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>.

npx fabric-app-data search "<name>"
npx fabric-app-data search "<name>" --json              # machine-readable output (preferred for agents)
npx fabric-app-data search "<name>" -w "<workspace>"    # restrict to one workspace (name or GUID)
npx fabric-app-data search "<name>" --max-results 5

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 remove sales
npx fabric-app-data remove sales -p staging

npx fabric-app-data list

List all connections in a profile.

npx fabric-app-data list
npx fabric-app-data list -p production

npx fabric-app-data use <profile>

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

npx fabric-app-data use production
npx fabric-app-data use staging -o src/config/fabric.generated.ts

npx fabric-app-data generate

Generate fabric.generated.ts from the active profile.

npx fabric-app-data generate
npx fabric-app-data generate -o src/fabric.generated.ts
npx fabric-app-data generate -p production

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.

npx fabric-app-data query <alias> --query '<DAX>'
npx fabric-app-data query <alias> --file src/queries/revenue.dax
npx fabric-app-data query semanticModel <alias> --query '<DAX>'  # explicit source type
npx fabric-app-data query <alias> --query '<DAX>' --limit 50     # return at most 50 rows
npx fabric-app-data query <alias> --query '<DAX>' --profile staging

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

activeProfile: dev
profiles:
  dev:
    semanticModels:
      sales:
        workspaceId: "00c98f7c-..."
        itemId: "03f2dc11-..."
      myModel:
        workspaceId: "me"
        itemId: "c078a68d-..."
  production:
    semanticModels:
      sales:
        workspaceId: "aabbccdd-..."
        itemId: "11223344-..."

Generated Output

fabric.generated.ts exports a plain config object:

// fabric.generated.ts — AUTO-GENERATED from fabric.yaml (profile: dev). Do not edit.

export const fabricConfig = {
  semanticModels: {
    sales: {
      workspaceId: '00c98f7c-...',
      itemId: '03f2dc11-...',
    },
  },
} as const;

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