--- name: pbir-cli description: This skill should be used whenever the user mentions "pbir", "pbir-cli", "Power BI reports", or "PBI reports", works with .pbir, .pbip, or .pbix files, or wants to refresh, screenshot, or visually verify a report that is open in Power BI Desktop. Covers creating, exploring, formatting, validating, and publishing Power BI reports through the pbir CLI and object model, plus driving Power BI Desktop (canvas reload, page screenshots) and querying connected or local semantic models. ---

# Working with Power BI reports using `pbir`

CLI for exploring, building, managing, formatting Power BI reports. All commands use `pbir`.

**IMPORTANT:** ALWAYS use `pbir` CLI commands to inspect and modify reports. NEVER write, replace, copy, or patch report JSON files directly. If the CLI does not expose a required mutation, stop and report the missing capability; do not fall back to file editing. Reading JSON through `pbir cat`, `pbir get`, or read-only examples is allowed.

**IMPORTANT:** FIRST Read and adhere to the mental model in [MENTAL-MODEL.md](important/MENTAL-MODEL.md).

## When `pbir` is missing

Install it with `uv tool install pbir-cli` (or `pip install pbir-cli`). That is the route to use in every ordinary case, including when the command is missing entirely.

`bin/fetch.sh` downloads a self-contained portable build instead. Reach for it **only** when `pbir` is not installed *and* installing it is not possible: no network access to PyPI, no Python, or a locked-down machine that forbids installs. A portable build does not update with `uv tool upgrade`, so preferring it when a normal install would have worked leaves the user on a stale CLI. If an install failed, fix the install rather than routing around it.

## Keeping the Fabric CLI current

When publishing to Fabric (`pbir publish`) alongside the `fabric-cli` plugin, check the installed Fabric CLI (`fab`) if publishing reports a compatibility problem. Upgrade with `uv tool upgrade ms-fabric-cli` only when required or requested, and honor any user-pinned version.

## Learning from Mistakes

Log learnings about the `pbir` CLI in the project's memory file: gotchas, unexpected behavior, user expectations, and design preferences. Use the agent-appropriate path:

- **Claude Code:** `.claude/rules/pbir-cli.md` - **Cursor:** `.cursor/rules/pbir-cli.mdc` - **GitHub Copilot:** `.github/instructions/pbir-cli.instructions.md`

Keep entries concise and generalizable. The memory file is not a change log. Prune redundancy, link out to references and examples rather than restating them.

## How to use `pbir`

### General workflow

1. Explore the report. The report must be in PBIR format: pbip, pbir-only, or pbix-with-PBIR-metadata. Prefer pbir or pbip. Whenever the user mentions Power BI Desktop or says the report is open in Desktop, run `pbir desktop list` FIRST: it maps each running instance to the file it has open (locating the report on disk) and confirms the bridge works before any edits begin. `pbir desktop` is Windows-only; on macOS and Linux do not use it (every invocation fails). Instead deploy with `pbir publish` to a sandbox workspace in Fabric and verify the rendered report in the browser via the Chrome MCP tools. 2. Identify the model. Reports generally should be thin reports connected to a remote model in Power BI or Fabric. 3. Clarify intent. For vague or open-ended instructions, consult **`references/vague-prompts.md`** and use `AskUserQuestion` to understand expectations and report context before mutating anything. 4. Plan changes. For new reports, pages, or visuals, draft a wireframe or mock-up for the user to approve before building. 5. Make changes. Reach for relevant files in `references/`, `examples/`, and related skills like `pbi-report-design`. 6. Validate. Mutating commands validate their own writes. Run explicit `pbir validate` after a coherent batch of changes and before completion; use narrower checks while iterating and `--all` for the final confidence pass. For visual confirmation, prefer the local loop when the report is open in Power BI Desktop: `pbir desktop refresh` then `pbir desktop screenshot` and inspect the PNG (see "Desktop Integration" below). Otherwise ask permission to publish to a sandbox workspace with `pbir publish` and inspect rendering via Chrome MCP, devtools CLI, or Playwright. 7. Iterate. Expect multiple rounds. Push back on one-shot expectations from vague prompts. 8. Record learnings. Add concise, generalizable entries to the memory file noted above.

### Path syntax

`pbir` uses a filesystem paradigm for identifying reports, pages, visuals etc. and glob syntax for bulk operations.

Format: `ReportName.Report/PageName.Page/VisualName.Visual`

- Type suffixes (`.Report`, `.Page`, `.Visual`) are required - Quote paths with spaces: `"My Report.Report/Dashboard.Page"` - Use glob patterns for bulk operations: `"Report.Report/**/*.Visual"` (requires `--force/-f` for `set` and `rm`) - `*.Visual`; all visuals on current page - `Page.Page/*.Visual`; all visuals on a specific page - `**/*.Visual`; all visuals across all pages - `**/card*.Visual`; visuals whose name starts with "card" - `**/*.Report/**/*.Visual`; all visuals across all reports - Properties via `get` or `set` and dot notation: `"Report.Report/Page.Page/Visual.Visual.title.fontSize"` - Filters/bookmarks: `"Report.Report/filter:Name"`, `"Report.Report/bookmark:Name"` - If multiple reports match, disambiguate with parent folder prefix - Absolute filesystem paths work too: `"C:\Reports\Sales.Report"`, `"C:\Reports\Flash.pbix"` (globs do not combine with absolute paths) - Workspace destinations use `.Workspace` suffix: `"My Workspace.Workspace/Report.Report"`

## Critical Rules

Follow all rules below.

0. **ASK user for clarifications and push back on one-shot prompt requests.** Pursue an iterative multi-step way-of-working

1. **CHECK references before starting work.** Identify relevant [references](references/) and [examples](examples/) that can help you understand the user requirements

2. **NEVER edit report JSON files directly.** Always use `pbir` CLI commands. Use `pbir cat` or `pbir get` to inspect JSON or properties; use `pbir set` for any property not covered by a dedicated command.

3. **Discover before setting.** Run `pbir schema describe <type>` to list a visual type's objects, then `pbir schema describe <type> <object>` for property names, types, ranges, and enums before formatting. Do not guess property names

4. **Theme-first formatting.** Check `pbir visuals format` before applying bespoke formatting; the theme may already set the property. Prefer `pbir theme set-formatting` for changes that apply to all visuals of a type. Reserve `pbir visuals title/background/border` for one-off overrides

5. **Validate proportionally.** Mutating commands already validate their writes. Run `pbir validate "Report.Report"` after each coherent batch and before completion. Use `--qa` for overlap/overflow checks, `--fields` for model field verification, and `--all` for the final confidence pass

6. **Verify rendering through the Desktop bridge.** When the report is open in Power BI Desktop, run `pbir desktop refresh` after every change unless the user asks not to, then `pbir desktop screenshot` and inspect the PNG after every meaningful change. Validation cannot catch rendering problems (overlap, truncation, wrong field, illegible formatting); the screenshot is the only proof a change rendered as intended. When a request involves many changes, ask the user up front whether to refresh after each step (so they watch progress in the canvas) or once at the end. Check availability once with `pbir desktop list` before starting the loop; if the bridge is unavailable, do not retry it after every change (see "When the bridge is unavailable" below)

## Core Workflows

### Exploration and Analysis

Understand existing reports before modifying. **Always check page dimensions and existing visual positions before adding or resizing visuals** setting position/size without knowing the page dimensions causes errors.

```bash pbir desktop list # FIRST if Desktop is mentioned: instances (PID, open file) pbir ls # Find all reports pbir ls "Report.Report" # List pages/filters/theme pbir tree "Report.Report" -v # Full structure with fields pbir validate "Report.Report" # Health check pbir get "Report.Report" # Report properties pbir pages json "Report.Report/Page.Page" # Check page width/height ```

For deeper exploration, consult **`references/exploration.md`**.

### Model Discovery (Required Before Binding Fields)

Always query the connected model to discover correct table/column/measure names. Never guess field names.

```bash pbir model "Report.Report" # Connection info (workspace, model, thick/thin) pbir model "Report.Report" -d # All tables, columns, measures pbir model "Report.Report" -d -t Sales # Filter to specific table pbir model "Report.Report" -q "EVALUATE VALUES('Geography'[Region])" # Check field values pbir model "Report.Report" -q "EVALUATE ROW(\"Revenue\", [Total Revenue])" # Test a measure pbir fields list "Report.Report" # Fields already in use across report ```

Routing depends on the report's model reference: thin reports (`byConnection`) query the Power BI / Fabric service; thick reports (`byPath`) query the local Analysis Services engine of the Power BI Desktop instance that has the report open, so `-q` and `-d` work fully offline against live model state. Local queries need the .NET Framework ADOMD client (found automatically from DAX Studio or Desktop installs; override with `PBIR_ADOMD_DIR`).

For full model query patterns and field binding workflows, consult **`references/fields-and-bindings.md`**.

### Semantic Model + Report Workflows (`te` + `pbir`)

When work crosses both layers, use Tabular Editor CLI (`te`) for semantic-model mutations and `pbir` for report mutations. Model object identity is the boundary: modern `te mv` cascades references inside the model, but report bindings still retain the old `Table.Field` and must be updated with `pbir`.

```powershell te connect "Sales Workspace" "Sales Model" te mv "'Actuals'[Actuals MTD]" "'Actuals'[Sales MTD]" --save te validate --errors-only pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" --dry-run pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" pbir validate "Sales Flash Report.Report" --fields pbir desktop refresh "Sales Flash Report.Report" ```

Use `te deps --downstream` plus `pbir fields find` before a rename, `pbir fields replace-table` after a table rename, and no report rewrite for metadata-only changes such as format strings or descriptions. For renames, moves, additions, deletions, deploy/rebind order, and final gates, consult **`references/te-cli-tandem.md`**.

### Desktop Integration (Refresh and Screenshot)

When the report is open in Power BI Desktop (Windows, with the "external tool access" preview feature enabled), drive the running instance directly. This is the fastest way to visually verify changes; no publishing required.

```bash pbir desktop list # Running instances (PID, open file, unsaved state, pages); `status` is an alias pbir desktop refresh "Report.Report" # Reload on-disk definition into the canvas (`reload` is an alias) pbir desktop refresh "Report.Report" -m # --model: also re-apply the model (TMDL) definition pbir desktop screenshot "Report.Report/Page.Page" -o verify.png pbir desktop screenshot "Report.Report" --all # Every page -> ./screenshots (--output-dir to set; --settle <ms> before first cap

--- name: pbir-cli description: This skill should be used whenever the user mentions "pbir", "pbir-cli", "Power BI reports", or "PBI reports", works with .pbir, .pbip, or .pbix files, or wants to refresh, screenshot, or visually verify a report that is open in Power BI Desktop. Covers creating, exploring, formatting, validating, and publishing Power BI reports through the pbir CLI and object model, plus driving Power BI Desktop (canvas reload, page screenshots) and querying connected or local semantic models. ---

# Working with Power BI reports using `pbir`

CLI for exploring, building, managing, formatting Power BI reports. All commands use `pbir`.

**IMPORTANT:** ALWAYS use `pbir` CLI commands to inspect and modify reports. NEVER write, replace, copy, or patch report JSON files directly. If the CLI does not expose a required mutation, stop and report the missing capability; do not fall back to file editing. Reading JSON through `pbir cat`, `pbir get`, or read-only examples is allowed.

**IMPORTANT:** FIRST Read and adhere to the mental model in [MENTAL-MODEL.md](important/MENTAL-MODEL.md).

## When `pbir` is missing

Install it with `uv tool install pbir-cli` (or `pip install pbir-cli`). That is the route to use in every ordinary case, including when the command is missing entirely.

`bin/fetch.sh` downloads a self-contained portable build instead. Reach for it **only** when `pbir` is not installed *and* installing it is not possible: no network access to PyPI, no Python, or a locked-down machine that forbids installs. A portable build does not update with `uv tool upgrade`, so preferring it when a normal install would have worked leaves the user on a stale CLI. If an install failed, fix the install rather than routing around it.

## Keeping the Fabric CLI current

When publishing to Fabric (`pbir publish`) alongside the `fabric-cli` plugin, check the installed Fabric CLI (`fab`) if publishing reports a compatibility problem. Upgrade with `uv tool upgrade ms-fabric-cli` only when required or requested, and honor any user-pinned version.

## Learning from Mistakes

Log learnings about the `pbir` CLI in the project's memory file: gotchas, unexpected behavior, user expectations, and design preferences. Use the agent-appropriate path:

- **Claude Code:** `.claude/rules/pbir-cli.md` - **Cursor:** `.cursor/rules/pbir-cli.mdc` - **GitHub Copilot:** `.github/instructions/pbir-cli.instructions.md`

Keep entries concise and generalizable. The memory file is not a change log. Prune redundancy, link out to references and examples rather than restating them.

## How to use `pbir`

### General workflow

1. Explore the report. The report must be in PBIR format: pbip, pbir-only, or pbix-with-PBIR-metadata. Prefer pbir or pbip. Whenever the user mentions Power BI Desktop or says the report is open in Desktop, run `pbir desktop list` FIRST: it maps each running instance to the file it has open (locating the report on disk) and confirms the bridge works before any edits begin. `pbir desktop` is Windows-only; on macOS and Linux do not use it (every invocation fails). Instead deploy with `pbir publish` to a sandbox workspace in Fabric and verify the rendered report in the browser via the Chrome MCP tools. 2. Identify the model. Reports generally should be thin reports connected to a remote model in Power BI or Fabric. 3. Clarify intent. For vague or open-ended instructions, consult **`references/vague-prompts.md`** and use `AskUserQuestion` to understand expectations and report context before mutating anything. 4. Plan changes. For new reports, pages, or visuals, draft a wireframe or mock-up for the user to approve before building. 5. Make changes. Reach for relevant files in `references/`, `examples/`, and related skills like `pbi-report-design`. 6. Validate. Mutating commands validate their own writes. Run explicit `pbir validate` after a coherent batch of changes and before completion; use narrower checks while iterating and `--all` for the final confidence pass. For visual confirmation, prefer the local loop when the report is open in Power BI Desktop: `pbir desktop refresh` then `pbir desktop screenshot` and inspect the PNG (see "Desktop Integration" below). Otherwise ask permission to publish to a sandbox workspace with `pbir publish` and inspect rendering via Chrome MCP, devtools CLI, or Playwright. 7. Iterate. Expect multiple rounds. Push back on one-shot expectations from vague prompts. 8. Record learnings. Add concise, generalizable entries to the memory file noted above.

### Path syntax

`pbir` uses a filesystem paradigm for identifying reports, pages, visuals etc. and glob syntax for bulk operations.

Format: `ReportName.Report/PageName.Page/VisualName.Visual`

- Type suffixes (`.Report`, `.Page`, `.Visual`) are required - Quote paths with spaces: `"My Report.Report/Dashboard.Page"` - Use glob patterns for bulk operations: `"Report.Report/**/*.Visual"` (requires `--force/-f` for `set` and `rm`) - `*.Visual`; all visuals on current page - `Page.Page/*.Visual`; all visuals on a specific page - `**/*.Visual`; all visuals across all pages - `**/card*.Visual`; visuals whose name starts with "card" - `**/*.Report/**/*.Visual`; all visuals across all reports - Properties via `get` or `set` and dot notation: `"Report.Report/Page.Page/Visual.Visual.title.fontSize"` - Filters/bookmarks: `"Report.Report/filter:Name"`, `"Report.Report/bookmark:Name"` - If multiple reports match, disambiguate with parent folder prefix - Absolute filesystem paths work too: `"C:\Reports\Sales.Report"`, `"C:\Reports\Flash.pbix"` (globs do not combine with absolute paths) - Workspace destinations use `.Workspace` suffix: `"My Workspace.Workspace/Report.Report"`

## Critical Rules

Follow all rules below.

0. **ASK user for clarifications and push back on one-shot prompt requests.** Pursue an iterative multi-step way-of-working

1. **CHECK references before starting work.** Identify relevant [references](references/) and [examples](examples/) that can help you understand the user requirements

2. **NEVER edit report JSON files directly.** Always use `pbir` CLI commands. Use `pbir cat` or `pbir get` to inspect JSON or properties; use `pbir set` for any property not covered by a dedicated command.

3. **Discover before setting.** Run `pbir schema describe <type>` to list a visual type's objects, then `pbir schema describe <type> <object>` for property names, types, ranges, and enums before formatting. Do not guess property names

4. **Theme-first formatting.** Check `pbir visuals format` before applying bespoke formatting; the theme may already set the property. Prefer `pbir theme set-formatting` for changes that apply to all visuals of a type. Reserve `pbir visuals title/background/border` for one-off overrides

5. **Validate proportionally.** Mutating commands already validate their writes. Run `pbir validate "Report.Report"` after each coherent batch and before completion. Use `--qa` for overlap/overflow checks, `--fields` for model field verification, and `--all` for the final confidence pass

6. **Verify rendering through the Desktop bridge.** When the report is open in Power BI Desktop, run `pbir desktop refresh` after every change unless the user asks not to, then `pbir desktop screenshot` and inspect the PNG after every meaningful change. Validation cannot catch rendering problems (overlap, truncation, wrong field, illegible formatting); the screenshot is the only proof a change rendered as intended. When a request involves many changes, ask the user up front whether to refresh after each step (so they watch progress in the canvas) or once at the end. Check availability once with `pbir desktop list` before starting the loop; if the bridge is unavailable, do not retry it after every change (see "When the bridge is unavailable" below)

## Core Workflows

### Exploration and Analysis

Understand existing reports before modifying. **Always check page dimensions and existing visual positions before adding or resizing visuals** setting position/size without knowing the page dimensions causes errors.

```bash pbir desktop list # FIRST if Desktop is mentioned: instances (PID, open file) pbir ls # Find all reports pbir ls "Report.Report" # List pages/filters/theme pbir tree "Report.Report" -v # Full structure with fields pbir validate "Report.Report" # Health check pbir get "Report.Report" # Report properties pbir pages json "Report.Report/Page.Page" # Check page width/height ```

For deeper exploration, consult **`references/exploration.md`**.

### Model Discovery (Required Before Binding Fields)

Always query the connected model to discover correct table/column/measure names. Never guess field names.

```bash pbir model "Report.Report" # Connection info (workspace, model, thick/thin) pbir model "Report.Report" -d # All tables, columns, measures pbir model "Report.Report" -d -t Sales # Filter to specific table pbir model "Report.Report" -q "EVALUATE VALUES('Geography'[Region])" # Check field values pbir model "Report.Report" -q "EVALUATE ROW(\"Revenue\", [Total Revenue])" # Test a measure pbir fields list "Report.Report" # Fields already in use across report ```

Routing depends on the report's model reference: thin reports (`byConnection`) query the Power BI / Fabric service; thick reports (`byPath`) query the local Analysis Services engine of the Power BI Desktop instance that has the report open, so `-q` and `-d` work fully offline against live model state. Local queries need the .NET Framework ADOMD client (found automatically from DAX Studio or Desktop installs; override with `PBIR_ADOMD_DIR`).

For full model query patterns and field binding workflows, consult **`references/fields-and-bindings.md`**.

### Semantic Model + Report Workflows (`te` + `pbir`)

When work crosses both layers, use Tabular Editor CLI (`te`) for semantic-model mutations and `pbir` for report mutations. Model object identity is the boundary: modern `te mv` cascades references inside the model, but report bindings still retain the old `Table.Field` and must be updated with `pbir`.

```powershell te connect "Sales Workspace" "Sales Model" te mv "'Actuals'[Actuals MTD]" "'Actuals'[Sales MTD]" --save te validate --errors-only pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" --dry-run pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" pbir validate "Sales Flash Report.Report" --fields pbir desktop refresh "Sales Flash Report.Report" ```

Use `te deps --downstream` plus `pbir fields find` before a rename, `pbir fields replace-table` after a table rename, and no report rewrite for metadata-only changes such as format strings or descriptions. For renames, moves, additions, deletions, deploy/rebind order, and final gates, consult **`references/te-cli-tandem.md`**.

### Desktop Integration (Refresh and Screenshot)

When the report is open in Power BI Desktop (Windows, with the "external tool access" preview feature enabled), drive the running instance directly. This is the fastest way to visually verify changes; no publishing required.

```bash pbir desktop list # Running instances (PID, open file, unsaved state, pages); `status` is an alias pbir desktop refresh "Report.Report" # Reload on-disk definition into the canvas (`reload` is an alias) pbir desktop refresh "Report.Report" -m # --model: also re-apply the model (TMDL) definition pbir desktop screenshot "Report.Report/Page.Page" -o verify.png pbir desktop screenshot "Report.Report" --all # Every page -> ./screenshots (--output-dir to set; --settle <ms> before first cap

--- name: pbir-cli description: This skill should be used whenever the user mentions "pbir", "pbir-cli", "Power BI reports", or "PBI reports", works with .pbir, .pbip, or .pbix files, or wants to refresh, screenshot, or visually verify a report that is open in Power BI Desktop. Covers creating, exploring, formatting, validating, and publishing Power BI reports through the pbir CLI and object model, plus driving Power BI Desktop (canvas reload, page screenshots) and querying connected or local semantic models. ---

# Working with Power BI reports using `pbir`

CLI for exploring, building, managing, formatting Power BI reports. All commands use `pbir`.

**IMPORTANT:** ALWAYS use `pbir` CLI commands to inspect and modify reports. NEVER write, replace, copy, or patch report JSON files directly. If the CLI does not expose a required mutation, stop and report the missing capability; do not fall back to file editing. Reading JSON through `pbir cat`, `pbir get`, or read-only examples is allowed.

**IMPORTANT:** FIRST Read and adhere to the mental model in [MENTAL-MODEL.md](important/MENTAL-MODEL.md).

## When `pbir` is missing

Install it with `uv tool install pbir-cli` (or `pip install pbir-cli`). That is the route to use in every ordinary case, including when the command is missing entirely.

`bin/fetch.sh` downloads a self-contained portable build instead. Reach for it **only** when `pbir` is not installed *and* installing it is not possible: no network access to PyPI, no Python, or a locked-down machine that forbids installs. A portable build does not update with `uv tool upgrade`, so preferring it when a normal install would have worked leaves the user on a stale CLI. If an install failed, fix the install rather than routing around it.

## Keeping the Fabric CLI current

When publishing to Fabric (`pbir publish`) alongside the `fabric-cli` plugin, check the installed Fabric CLI (`fab`) if publishing reports a compatibility problem. Upgrade with `uv tool upgrade ms-fabric-cli` only when required or requested, and honor any user-pinned version.

## Learning from Mistakes

Log learnings about the `pbir` CLI in the project's memory file: gotchas, unexpected behavior, user expectations, and design preferences. Use the agent-appropriate path:

- **Claude Code:** `.claude/rules/pbir-cli.md` - **Cursor:** `.cursor/rules/pbir-cli.mdc` - **GitHub Copilot:** `.github/instructions/pbir-cli.instructions.md`

Keep entries concise and generalizable. The memory file is not a change log. Prune redundancy, link out to references and examples rather than restating them.

## How to use `pbir`

### General workflow

1. Explore the report. The report must be in PBIR format: pbip, pbir-only, or pbix-with-PBIR-metadata. Prefer pbir or pbip. Whenever the user mentions Power BI Desktop or says the report is open in Desktop, run `pbir desktop list` FIRST: it maps each running instance to the file it has open (locating the report on disk) and confirms the bridge works before any edits begin. `pbir desktop` is Windows-only; on macOS and Linux do not use it (every invocation fails). Instead deploy with `pbir publish` to a sandbox workspace in Fabric and verify the rendered report in the browser via the Chrome MCP tools. 2. Identify the model. Reports generally should be thin reports connected to a remote model in Power BI or Fabric. 3. Clarify intent. For vague or open-ended instructions, consult **`references/vague-prompts.md`** and use `AskUserQuestion` to understand expectations and report context before mutating anything. 4. Plan changes. For new reports, pages, or visuals, draft a wireframe or mock-up for the user to approve before building. 5. Make changes. Reach for relevant files in `references/`, `examples/`, and related skills like `pbi-report-design`. 6. Validate. Mutating commands validate their own writes. Run explicit `pbir validate` after a coherent batch of changes and before completion; use narrower checks while iterating and `--all` for the final confidence pass. For visual confirmation, prefer the local loop when the report is open in Power BI Desktop: `pbir desktop refresh` then `pbir desktop screenshot` and inspect the PNG (see "Desktop Integration" below). Otherwise ask permission to publish to a sandbox workspace with `pbir publish` and inspect rendering via Chrome MCP, devtools CLI, or Playwright. 7. Iterate. Expect multiple rounds. Push back on one-shot expectations from vague prompts. 8. Record learnings. Add concise, generalizable entries to the memory file noted above.

### Path syntax

`pbir` uses a filesystem paradigm for identifying reports, pages, visuals etc. and glob syntax for bulk operations.

Format: `ReportName.Report/PageName.Page/VisualName.Visual`

- Type suffixes (`.Report`, `.Page`, `.Visual`) are required - Quote paths with spaces: `"My Report.Report/Dashboard.Page"` - Use glob patterns for bulk operations: `"Report.Report/**/*.Visual"` (requires `--force/-f` for `set` and `rm`) - `*.Visual`; all visuals on current page - `Page.Page/*.Visual`; all visuals on a specific page - `**/*.Visual`; all visuals across all pages - `**/card*.Visual`; visuals whose name starts with "card" - `**/*.Report/**/*.Visual`; all visuals across all reports - Properties via `get` or `set` and dot notation: `"Report.Report/Page.Page/Visual.Visual.title.fontSize"` - Filters/bookmarks: `"Report.Report/filter:Name"`, `"Report.Report/bookmark:Name"` - If multiple reports match, disambiguate with parent folder prefix - Absolute filesystem paths work too: `"C:\Reports\Sales.Report"`, `"C:\Reports\Flash.pbix"` (globs do not combine with absolute paths) - Workspace destinations use `.Workspace` suffix: `"My Workspace.Workspace/Report.Report"`

## Critical Rules

Follow all rules below.

0. **ASK user for clarifications and push back on one-shot prompt requests.** Pursue an iterative multi-step way-of-working

1. **CHECK references before starting work.** Identify relevant [references](references/) and [examples](examples/) that can help you understand the user requirements

2. **NEVER edit report JSON files directly.** Always use `pbir` CLI commands. Use `pbir cat` or `pbir get` to inspect JSON or properties; use `pbir set` for any property not covered by a dedicated command.

3. **Discover before setting.** Run `pbir schema describe <type>` to list a visual type's objects, then `pbir schema describe <type> <object>` for property names, types, ranges, and enums before formatting. Do not guess property names

4. **Theme-first formatting.** Check `pbir visuals format` before applying bespoke formatting; the theme may already set the property. Prefer `pbir theme set-formatting` for changes that apply to all visuals of a type. Reserve `pbir visuals title/background/border` for one-off overrides

5. **Validate proportionally.** Mutating commands already validate their writes. Run `pbir validate "Report.Report"` after each coherent batch and before completion. Use `--qa` for overlap/overflow checks, `--fields` for model field verification, and `--all` for the final confidence pass

6. **Verify rendering through the Desktop bridge.** When the report is open in Power BI Desktop, run `pbir desktop refresh` after every change unless the user asks not to, then `pbir desktop screenshot` and inspect the PNG after every meaningful change. Validation cannot catch rendering problems (overlap, truncation, wrong field, illegible formatting); the screenshot is the only proof a change rendered as intended. When a request involves many changes, ask the user up front whether to refresh after each step (so they watch progress in the canvas) or once at the end. Check availability once with `pbir desktop list` before starting the loop; if the bridge is unavailable, do not retry it after every change (see "When the bridge is unavailable" below)

## Core Workflows

### Exploration and Analysis

Understand existing reports before modifying. **Always check page dimensions and existing visual positions before adding or resizing visuals** setting position/size without knowing the page dimensions causes errors.

```bash pbir desktop list # FIRST if Desktop is mentioned: instances (PID, open file) pbir ls # Find all reports pbir ls "Report.Report" # List pages/filters/theme pbir tree "Report.Report" -v # Full structure with fields pbir validate "Report.Report" # Health check pbir get "Report.Report" # Report properties pbir pages json "Report.Report/Page.Page" # Check page width/height ```

For deeper exploration, consult **`references/exploration.md`**.

### Model Discovery (Required Before Binding Fields)

Always query the connected model to discover correct table/column/measure names. Never guess field names.

```bash pbir model "Report.Report" # Connection info (workspace, model, thick/thin) pbir model "Report.Report" -d # All tables, columns, measures pbir model "Report.Report" -d -t Sales # Filter to specific table pbir model "Report.Report" -q "EVALUATE VALUES('Geography'[Region])" # Check field values pbir model "Report.Report" -q "EVALUATE ROW(\"Revenue\", [Total Revenue])" # Test a measure pbir fields list "Report.Report" # Fields already in use across report ```

Routing depends on the report's model reference: thin reports (`byConnection`) query the Power BI / Fabric service; thick reports (`byPath`) query the local Analysis Services engine of the Power BI Desktop instance that has the report open, so `-q` and `-d` work fully offline against live model state. Local queries need the .NET Framework ADOMD client (found automatically from DAX Studio or Desktop installs; override with `PBIR_ADOMD_DIR`).

For full model query patterns and field binding workflows, consult **`references/fields-and-bindings.md`**.

### Semantic Model + Report Workflows (`te` + `pbir`)

When work crosses both layers, use Tabular Editor CLI (`te`) for semantic-model mutations and `pbir` for report mutations. Model object identity is the boundary: modern `te mv` cascades references inside the model, but report bindings still retain the old `Table.Field` and must be updated with `pbir`.

```powershell te connect "Sales Workspace" "Sales Model" te mv "'Actuals'[Actuals MTD]" "'Actuals'[Sales MTD]" --save te validate --errors-only pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" --dry-run pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" pbir validate "Sales Flash Report.Report" --fields pbir desktop refresh "Sales Flash Report.Report" ```

Use `te deps --downstream` plus `pbir fields find` before a rename, `pbir fields replace-table` after a table rename, and no report rewrite for metadata-only changes such as format strings or descriptions. For renames, moves, additions, deletions, deploy/rebind order, and final gates, consult **`references/te-cli-tandem.md`**.

### Desktop Integration (Refresh and Screenshot)

When the report is open in Power BI Desktop (Windows, with the "external tool access" preview feature enabled), drive the running instance directly. This is the fastest way to visually verify changes; no publishing required.

```bash pbir desktop list # Running instances (PID, open file, unsaved state, pages); `status` is an alias pbir desktop refresh "Report.Report" # Reload on-disk definition into the canvas (`reload` is an alias) pbir desktop refresh "Report.Report" -m # --model: also re-apply the model (TMDL) definition pbir desktop screenshot "Report.Report/Page.Page" -o verify.png pbir desktop screenshot "Report.Report" --all # Every page -> ./screenshots (--output-dir to set; --settle <ms> before first cap

--- name: pbir-cli description: This skill should be used whenever the user mentions "pbir", "pbir-cli", "Power BI reports", or "PBI reports", works with .pbir, .pbip, or .pbix files, or wants to refresh, screenshot, or visually verify a report that is open in Power BI Desktop. Covers creating, exploring, formatting, validating, and publishing Power BI reports through the pbir CLI and object model, plus driving Power BI Desktop (canvas reload, page screenshots) and querying connected or local semantic models. ---

# Working with Power BI reports using `pbir`

CLI for exploring, building, managing, formatting Power BI reports. All commands use `pbir`.

**IMPORTANT:** ALWAYS use `pbir` CLI commands to inspect and modify reports. NEVER write, replace, copy, or patch report JSON files directly. If the CLI does not expose a required mutation, stop and report the missing capability; do not fall back to file editing. Reading JSON through `pbir cat`, `pbir get`, or read-only examples is allowed.

**IMPORTANT:** FIRST Read and adhere to the mental model in [MENTAL-MODEL.md](important/MENTAL-MODEL.md).

## When `pbir` is missing

Install it with `uv tool install pbir-cli` (or `pip install pbir-cli`). That is the route to use in every ordinary case, including when the command is missing entirely.

`bin/fetch.sh` downloads a self-contained portable build instead. Reach for it **only** when `pbir` is not installed *and* installing it is not possible: no network access to PyPI, no Python, or a locked-down machine that forbids installs. A portable build does not update with `uv tool upgrade`, so preferring it when a normal install would have worked leaves the user on a stale CLI. If an install failed, fix the install rather than routing around it.

## Keeping the Fabric CLI current

When publishing to Fabric (`pbir publish`) alongside the `fabric-cli` plugin, check the installed Fabric CLI (`fab`) if publishing reports a compatibility problem. Upgrade with `uv tool upgrade ms-fabric-cli` only when required or requested, and honor any user-pinned version.

## Learning from Mistakes

Log learnings about the `pbir` CLI in the project's memory file: gotchas, unexpected behavior, user expectations, and design preferences. Use the agent-appropriate path:

- **Claude Code:** `.claude/rules/pbir-cli.md` - **Cursor:** `.cursor/rules/pbir-cli.mdc` - **GitHub Copilot:** `.github/instructions/pbir-cli.instructions.md`

Keep entries concise and generalizable. The memory file is not a change log. Prune redundancy, link out to references and examples rather than restating them.

## How to use `pbir`

### General workflow

1. Explore the report. The report must be in PBIR format: pbip, pbir-only, or pbix-with-PBIR-metadata. Prefer pbir or pbip. Whenever the user mentions Power BI Desktop or says the report is open in Desktop, run `pbir desktop list` FIRST: it maps each running instance to the file it has open (locating the report on disk) and confirms the bridge works before any edits begin. `pbir desktop` is Windows-only; on macOS and Linux do not use it (every invocation fails). Instead deploy with `pbir publish` to a sandbox workspace in Fabric and verify the rendered report in the browser via the Chrome MCP tools. 2. Identify the model. Reports generally should be thin reports connected to a remote model in Power BI or Fabric. 3. Clarify intent. For vague or open-ended instructions, consult **`references/vague-prompts.md`** and use `AskUserQuestion` to understand expectations and report context before mutating anything. 4. Plan changes. For new reports, pages, or visuals, draft a wireframe or mock-up for the user to approve before building. 5. Make changes. Reach for relevant files in `references/`, `examples/`, and related skills like `pbi-report-design`. 6. Validate. Mutating commands validate their own writes. Run explicit `pbir validate` after a coherent batch of changes and before completion; use narrower checks while iterating and `--all` for the final confidence pass. For visual confirmation, prefer the local loop when the report is open in Power BI Desktop: `pbir desktop refresh` then `pbir desktop screenshot` and inspect the PNG (see "Desktop Integration" below). Otherwise ask permission to publish to a sandbox workspace with `pbir publish` and inspect rendering via Chrome MCP, devtools CLI, or Playwright. 7. Iterate. Expect multiple rounds. Push back on one-shot expectations from vague prompts. 8. Record learnings. Add concise, generalizable entries to the memory file noted above.

### Path syntax

`pbir` uses a filesystem paradigm for identifying reports, pages, visuals etc. and glob syntax for bulk operations.

Format: `ReportName.Report/PageName.Page/VisualName.Visual`

- Type suffixes (`.Report`, `.Page`, `.Visual`) are required - Quote paths with spaces: `"My Report.Report/Dashboard.Page"` - Use glob patterns for bulk operations: `"Report.Report/**/*.Visual"` (requires `--force/-f` for `set` and `rm`) - `*.Visual`; all visuals on current page - `Page.Page/*.Visual`; all visuals on a specific page - `**/*.Visual`; all visuals across all pages - `**/card*.Visual`; visuals whose name starts with "card" - `**/*.Report/**/*.Visual`; all visuals across all reports - Properties via `get` or `set` and dot notation: `"Report.Report/Page.Page/Visual.Visual.title.fontSize"` - Filters/bookmarks: `"Report.Report/filter:Name"`, `"Report.Report/bookmark:Name"` - If multiple reports match, disambiguate with parent folder prefix - Absolute filesystem paths work too: `"C:\Reports\Sales.Report"`, `"C:\Reports\Flash.pbix"` (globs do not combine with absolute paths) - Workspace destinations use `.Workspace` suffix: `"My Workspace.Workspace/Report.Report"`

## Critical Rules

Follow all rules below.

0. **ASK user for clarifications and push back on one-shot prompt requests.** Pursue an iterative multi-step way-of-working

1. **CHECK references before starting work.** Identify relevant [references](references/) and [examples](examples/) that can help you understand the user requirements

2. **NEVER edit report JSON files directly.** Always use `pbir` CLI commands. Use `pbir cat` or `pbir get` to inspect JSON or properties; use `pbir set` for any property not covered by a dedicated command.

3. **Discover before setting.** Run `pbir schema describe <type>` to list a visual type's objects, then `pbir schema describe <type> <object>` for property names, types, ranges, and enums before formatting. Do not guess property names

4. **Theme-first formatting.** Check `pbir visuals format` before applying bespoke formatting; the theme may already set the property. Prefer `pbir theme set-formatting` for changes that apply to all visuals of a type. Reserve `pbir visuals title/background/border` for one-off overrides

5. **Validate proportionally.** Mutating commands already validate their writes. Run `pbir validate "Report.Report"` after each coherent batch and before completion. Use `--qa` for overlap/overflow checks, `--fields` for model field verification, and `--all` for the final confidence pass

6. **Verify rendering through the Desktop bridge.** When the report is open in Power BI Desktop, run `pbir desktop refresh` after every change unless the user asks not to, then `pbir desktop screenshot` and inspect the PNG after every meaningful change. Validation cannot catch rendering problems (overlap, truncation, wrong field, illegible formatting); the screenshot is the only proof a change rendered as intended. When a request involves many changes, ask the user up front whether to refresh after each step (so they watch progress in the canvas) or once at the end. Check availability once with `pbir desktop list` before starting the loop; if the bridge is unavailable, do not retry it after every change (see "When the bridge is unavailable" below)

## Core Workflows

### Exploration and Analysis

Understand existing reports before modifying. **Always check page dimensions and existing visual positions before adding or resizing visuals** setting position/size without knowing the page dimensions causes errors.

```bash pbir desktop list # FIRST if Desktop is mentioned: instances (PID, open file) pbir ls # Find all reports pbir ls "Report.Report" # List pages/filters/theme pbir tree "Report.Report" -v # Full structure with fields pbir validate "Report.Report" # Health check pbir get "Report.Report" # Report properties pbir pages json "Report.Report/Page.Page" # Check page width/height ```

For deeper exploration, consult **`references/exploration.md`**.

### Model Discovery (Required Before Binding Fields)

Always query the connected model to discover correct table/column/measure names. Never guess field names.

```bash pbir model "Report.Report" # Connection info (workspace, model, thick/thin) pbir model "Report.Report" -d # All tables, columns, measures pbir model "Report.Report" -d -t Sales # Filter to specific table pbir model "Report.Report" -q "EVALUATE VALUES('Geography'[Region])" # Check field values pbir model "Report.Report" -q "EVALUATE ROW(\"Revenue\", [Total Revenue])" # Test a measure pbir fields list "Report.Report" # Fields already in use across report ```

Routing depends on the report's model reference: thin reports (`byConnection`) query the Power BI / Fabric service; thick reports (`byPath`) query the local Analysis Services engine of the Power BI Desktop instance that has the report open, so `-q` and `-d` work fully offline against live model state. Local queries need the .NET Framework ADOMD client (found automatically from DAX Studio or Desktop installs; override with `PBIR_ADOMD_DIR`).

For full model query patterns and field binding workflows, consult **`references/fields-and-bindings.md`**.

### Semantic Model + Report Workflows (`te` + `pbir`)

When work crosses both layers, use Tabular Editor CLI (`te`) for semantic-model mutations and `pbir` for report mutations. Model object identity is the boundary: modern `te mv` cascades references inside the model, but report bindings still retain the old `Table.Field` and must be updated with `pbir`.

```powershell te connect "Sales Workspace" "Sales Model" te mv "'Actuals'[Actuals MTD]" "'Actuals'[Sales MTD]" --save te validate --errors-only pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" --dry-run pbir fields replace "Sales Flash Report.Report" --from "Actuals.Actuals MTD" --to "Actuals.Sales MTD" pbir validate "Sales Flash Report.Report" --fields pbir desktop refresh "Sales Flash Report.Report" ```

Use `te deps --downstream` plus `pbir fields find` before a rename, `pbir fields replace-table` after a table rename, and no report rewrite for metadata-only changes such as format strings or descriptions. For renames, moves, additions, deletions, deploy/rebind order, and final gates, consult **`references/te-cli-tandem.md`**.

### Desktop Integration (Refresh and Screenshot)

When the report is open in Power BI Desktop (Windows, with the "external tool access" preview feature enabled), drive the running instance directly. This is the fastest way to visually verify changes; no publishing required.

```bash pbir desktop list # Running instances (PID, open file, unsaved state, pages); `status` is an alias pbir desktop refresh "Report.Report" # Reload on-disk definition into the canvas (`reload` is an alias) pbir desktop refresh "Report.Report" -m # --model: also re-apply the model (TMDL) definition pbir desktop screenshot "Report.Report/Page.Page" -o verify.png pbir desktop screenshot "Report.Report" --all # Every page -> ./screenshots (--output-dir to set; --settle <ms> before first cap