@microsoft/fabric-app-data-cli

CLI for Fabric Apps - Analytics — project setup, data connections, and code generation

Quick Reference

Package: @microsoft/fabric-app-data-cli Purpose: CLI tool for initializing projects, managing Fabric data connections, generating TypeScript config, and executing DAX queries locally. Use when: You need to set up a Fabric Apps project, add/remove data connections, generate fabric.generated.ts, or test DAX queries from the terminal. Do NOT use when: You need the runtime SDK in your app code (use @microsoft/fabric-app-data), or you need to render data (use @microsoft/fabric-visuals or @microsoft/fabric-datagrid). Key exports: createProgram() (programmatic API — most usage is via the fabric-app-data CLI binary) Peer dependencies: None Install: npm install @microsoft/fabric-app-data-cli or npm install -g @microsoft/fabric-app-data-cli

Ecosystem Context

@microsoft/fabric-app-data-cli is the local-development CLI for the Fabric Apps - Analytics stack.

• It uses @microsoft/fabric-app-data-cli-proxy when executing DAX queries locally, constructing DirectFabricApiProxy and passing it into FabricClient.
• The wider ecosystem uses @powerbi/lyra-fabric-auth as a token-provider package for Fabric clients and proxies; this CLI currently authenticates its query flow with its own Azure-CLI-based AzCliTokenProvider.
• It generates fabric.generated.ts, which is consumed by the @microsoft/fabric-app-data SDK.
• The generated config fits app projects that render results with packages such as @microsoft/fabric-visuals and @microsoft/fabric-datagrid.

CLI Commands

Executable name:

fabric-app-data <command>

Supported item types for connection management:

• semanticModel
• lakehouse
• warehouse

init

Purpose: create a new fabric.yaml in the current working directory.

Syntax:

fabric-app-data init [options]

Options:

| Option | Type | Description | | --- | --- | --- | | -p, --profile <name> | string | Initial profile name. Default: dev. | | --force | boolean | Overwrite an existing fabric.yaml in the current directory. |

Notes:

• init always writes fabric.yaml in the current directory.
• If a parent directory already contains fabric.yaml, the command warns that the new file will shadow it.

add

Purpose: add a Fabric connection to a profile.

Syntax:

fabric-app-data add <type> <alias> --workspace <id> --item <id> [options]
fabric-app-data add <alias> --from-url <url> [options]

Options:

| Option | Type | Description | | --- | --- | --- | | -w, --workspace <id> | string | Fabric workspace ID. | | --workspace-id <id> | string | Alias for --workspace. | | --workspaceId <id> | string | Alias for --workspace. | | -i, --item <id> | string | Fabric item ID. | | --item-id <id> | string | Alias for --item. | | --itemId <id> | string | Alias for --item. | | --from-url <url> | string | Fabric or Power BI URL to parse for workspace ID, item ID, and item type. | | --url <url> | string | Alias for --from-url. | | --alias <name> | string | Connection alias instead of positional <alias>. | | --name <name> | string | Alias for --alias. | | --type <type> | string | Item type instead of positional <type>. | | -p, --profile <name> | string | Target profile. Defaults to activeProfile. |

Behavior:

• --from-url supports Fabric portal /groups/... URLs and OneLake /onelake/details/... URLs.
• If the target profile does not exist, add creates it.
• Adding an existing alias overwrites that alias in the target item-type group.

remove

Purpose: remove a connection alias from a profile.

Syntax:

fabric-app-data remove <alias> [options]

Options:

| Option | Type | Description | | --- | --- | --- | | -p, --profile <name> | string | Target profile. Defaults to activeProfile. |

Behavior:

• The command searches all item-type groups in the selected profile.
• If the removed alias was the last entry in a group, that group is deleted from the YAML.

use

Purpose: switch the active profile and regenerate output immediately.

Syntax:

fabric-app-data use <profile> [options]

Options:

| Option | Type | Description | | --- | --- | --- | | -o, --output <path> | string | Output file path for regenerated TypeScript. |

Behavior:

• Updates activeProfile in fabric.yaml.
• Regenerates the output file after switching.
• Without --output, regeneration writes fabric.generated.ts next to the resolved fabric.yaml.

list

Purpose: list all connections in a profile.

Syntax:

fabric-app-data list [options]

Options:

| Option | Type | Description | | --- | --- | --- | | -p, --profile <name> | string | Profile to list. Defaults to activeProfile. |

Output:

• Groups connections by semanticModels, lakehouses, and warehouses.
• Prints each alias plus its workspaceId and itemId.

generate

Purpose: generate TypeScript config from a profile.

Syntax:

fabric-app-data generate [options]

Options:

| Option | Type | Description | | --- | --- | --- | | -o, --output <path> | string | Output file path. | | -p, --profile <name> | string | Profile to generate from. Defaults to activeProfile. |

Behavior:

• Without --output, writes fabric.generated.ts next to the resolved fabric.yaml.
• With --output, a relative path is resolved from the current working directory.

execute

Purpose: execute DAX queries during local development.

Syntax:

fabric-app-data query <alias> --query "<DAX>"
fabric-app-data query <alias> --file <path.dax>
fabric-app-data query <sourceType> <alias> --query "<DAX>"

Command names:

• Primary command: query
• Aliases: execute, exec

Options:

| Option | Type | Description | | --- | --- | --- | | -q, --query <query> | string | Inline DAX query text. | | -f, --file <path> | string | Read DAX query text from a file. | | -p, --profile <name> | string | Profile name. Defaults to activeProfile. | | -l, --limit <rows> | string | Maximum rows returned. Default: 1000. Max: 1000. |

Behavior:

• If only one positional argument is provided, it is treated as the alias and sourceType defaults to semanticModel.
• Query execution currently supports semanticModel only.
• Output is JSON.
• Error output is serialized as JSON with status: "error".
• Successful results larger than the requested limit are truncated and include _cliWarning.
• Permission errors caused by INFO.* functions may include _cliHint recommending INFO.VIEW.*.

Programmatic API

Package root export:

import { createProgram } from "@microsoft/fabric-app-data-cli";

Signature:

function createProgram(): Command;

Notes:

• createProgram() returns a configured commander Command instance with all CLI commands registered.
• src/index.ts exposes no additional public exports.

Configuration

Configuration file name:

fabric.yaml

Generated file default:

fabric.generated.ts

Discovery rules:

• add, remove, use, list, generate, and query/execute walk up from the current working directory to find the nearest fabric.yaml.
• Discovery stops at the filesystem root or at a directory containing .git if that directory does not also contain fabric.yaml.
• init is the exception: it always creates fabric.yaml in the current working directory.

Required structure:

activeProfile: dev
profiles:
  dev:
    semanticModels:
      sales:
        workspaceId: "workspace-id"
        itemId: "item-id"
    lakehouses:
      trips:
        workspaceId: "workspace-id"
        itemId: "item-id"
    warehouses:
      finance:
        workspaceId: "workspace-id"
        itemId: "item-id"

Schema rules:

• activeProfile must be a non-empty string.
• profiles must be an object.
• activeProfile must exist in profiles.
• Each connection entry must contain non-empty workspaceId and itemId.

Key Constraints & Gotchas

Azure CLI authentication is required

# ✅ DO: Sign in before running queries
az login
npx fabric-app-data query sales --query "EVALUATE ROW("x", 1)"

# ❌ DON'T: Run queries without signing in — auth will fail
npx fabric-app-data query sales --query "EVALUATE ..."  # Error: not authenticated

fabric.yaml is the source of truth

• All connection commands (add, remove, use, list) read/write fabric.yaml.
• generate and use derive TypeScript output from fabric.yaml.
• init creates fabric.yaml in the current directory; other commands walk up to find the nearest one.

Generated output location

# ✅ DO: Specify output path explicitly if needed
npx fabric-app-data generate -o src/fabric.generated.ts

# Default: fabric.generated.ts is written next to fabric.yaml, not necessarily the cwd

Query execution limitations

• Only semanticModel DAX queries are supported. Lakehouse and warehouse queries are not implemented.
• Results are capped at 1000 rows maximum.
• Output is JSON; errors include status: "error".

Minimal Usage Examples

Initialize a project, add a semantic model, and generate TypeScript config:

npx fabric-app-data init
npx fabric-app-data add semanticModel sales --workspace <workspace-id> --item <item-id>
npx fabric-app-data generate -o src/fabric.generated.ts

Add a connection from a Fabric URL instead of explicit IDs:

npx fabric-app-data add sales --from-url "https://app.fabric.microsoft.com/groups/<workspace-id>/semanticmodels/<item-id>"

Switch profiles and regenerate:

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

Execute a DAX query locally:

npx fabric-app-data query sales --query "EVALUATE ROW(\"test\", 1)"

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations.

Please do not report security vulnerabilities through public GitHub issues.

For security reporting information, locations, contact information, and policies, please review the latest guidance for Microsoft repositories at https://aka.ms/SECURITY.md.

Code of conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

See full Microsoft Open Source Code of Conduct

Usage

fabric-app-data <command>

Authentication

By default, the CLI authenticates using Azure CLI (az account get-access-token). You must be signed in via az login.

Using the RAYFIN_TOKEN environment variable

If the RAYFIN_TOKEN environment variable is set to a non-empty value, the CLI uses that token directly instead of calling Azure CLI. This is useful for CI environments or scenarios where a pre-acquired token is available.

export RAYFIN_TOKEN="<your-access-token>"
fabric-app-data <command>

Using the RAYFIN_FABRIC_API_URL environment variable

If the RAYFIN_FABRIC_API_URL environment variable is set to a non-empty value, the CLI overrides both the Fabric REST API and Power BI API endpoints with that URL. This is useful for sovereign clouds, daily rings, local development proxies, or routing through a credential proxy mounted under a path prefix.

export RAYFIN_FABRIC_API_URL="https://custom.fabric.api/v1"
fabric-app-data <command>

Accepted shapes (all are back-compatible — /v1 is appended only when the resolved path does not already end in /v1):

| Input | Effective Fabric API base | Effective Power BI base | | --- | --- | --- | | https://custom.fabric.api | https://custom.fabric.api/v1 | https://custom.fabric.api/v1.0/myorg | | https://custom.fabric.api/v1 | https://custom.fabric.api/v1 | https://custom.fabric.api/v1.0/myorg | | https://custom.fabric.api/v1/ | https://custom.fabric.api/v1 | https://custom.fabric.api/v1.0/myorg | | https://my-proxy.example.com/cli-proxy/fabric/<conn> | https://my-proxy.example.com/cli-proxy/fabric/<conn>/v1 | https://my-proxy.example.com/cli-proxy/fabric/<conn>/v1.0/myorg | | https://my-proxy.example.com/cli-proxy/fabric/<conn>/v1 | https://my-proxy.example.com/cli-proxy/fabric/<conn>/v1 | https://my-proxy.example.com/cli-proxy/fabric/<conn>/v1.0/myorg |

Anything supplied after the origin is preserved verbatim, so any path prefix (e.g. a credential proxy sub-path) carries through to both Fabric and Power BI requests:

export RAYFIN_FABRIC_API_URL="https://my-proxy.example.com/cli-proxy/fabric/abc"
fabric-app-data query sales --query "EVALUATE ROW(\"test\", 1)"