power-bi-report

name	power-bi-report
description	Scaffold, validate, preview, and manage Power BI PBIR report projects using pbi-cli. Invoke this skill whenever the user mentions "create report", "new report", "PBIR", "scaffold", "validate report", "report structure", "preview report", "report info", "reload Desktop", "convert report", ".pbip project", "report project", or wants to understand the PBIR folder format, set up a new report from scratch, or work with the report as a whole. For specific tasks, see also: power-bi-visuals (charts, binding), power-bi-pages (page management), power-bi-themes (themes, formatting), power-bi-filters (page/visual filters).
tools	pbi-cli

Power BI Report Skill

Manage Power BI PBIR report projects at the top level -- scaffolding, validation, preview, and Desktop integration. No connection to Power BI Desktop is needed for most operations.

PBIR Format

PBIR (Enhanced Report Format) stores reports as a folder of JSON files:

MyReport.Report/
  definition.pbir            # dataset reference
  definition/
    version.json             # PBIR version
    report.json              # report settings, theme
    pages/
      pages.json             # page order
      page_abc123/
        page.json            # page settings
        visuals/
          visual_def456/
            visual.json      # visual type, position, bindings

Each file has a public JSON schema from Microsoft for validation. PBIR is GA as of January 2026 and the default format in Desktop since March 2026.

Creating a Report

# Scaffold a new report project
pbi report create ./MyProject --name "Sales Report"

# With dataset reference
pbi report create ./MyProject --name "Sales" --dataset-path "../Sales.Dataset"

This creates the full folder structure with definition.pbir, report.json, version.json, and an empty pages/ directory.

Report Info and Validation

# Show report metadata summary (pages, theme, dataset)
pbi report info
pbi report info --path ./MyReport.Report

# Validate report structure and JSON files
pbi report validate

Validation checks:

• Required files exist (definition.pbir, report.json, version.json)
• All JSON files parse without errors
• Schema URLs are present and consistent
• Page references in pages.json match actual page folders

Preview

Start a live HTML preview of the report layout:

pbi report preview

Opens a browser showing all pages with visual placeholders, types, positions, and data bindings. The preview auto-refreshes when files change.

Requires the preview optional dependency: pip install pbi-cli-tool[preview]

Desktop Integration

# Trigger Power BI Desktop to reload the current report
pbi report reload

Power BI Desktop's Developer Mode auto-detects TMDL changes but not PBIR changes. This command sends a keyboard shortcut to the Desktop window to trigger a reload. Requires the reload optional dependency: pip install pbi-cli-tool[reload]

Suppressing Auto-Sync (--no-sync)

By default, every write command (add-page, delete-page, set-background, set-theme, etc.) automatically syncs Power BI Desktop after each operation. When building a report in multiple steps, this causes Desktop to reload after every single command.

Use --no-sync on the report command group to suppress per-command syncs, then call pbi report reload once at the end:

# BAD: Desktop reloads after every command
pbi report add-page --display-name "Overview" --name overview
pbi report set-background overview --color "#F2F2F2"

# GOOD: suppress sync during build, reload once at the end
pbi report --no-sync add-page --display-name "Overview" --name overview
pbi report --no-sync set-background overview --color "#F2F2F2"
pbi report reload

--no-sync is available on: report, visual, filters, and bookmarks command groups.

Convert

# Convert a .Report folder into a distributable .pbip project
pbi report convert ./MyReport.Report --output ./distributable/

Path Resolution

All report commands auto-detect the .Report folder:

1. Explicit: pbi report --path ./MyReport.Report info
2. Auto-detect: walks up from CWD looking for *.Report/definition/
3. From .pbip: finds sibling .Report folder from .pbip file

Workflow: Build a Complete Report

This workflow uses commands from multiple skills:

# 1. Scaffold report (this skill)
pbi report create . --name "SalesDashboard" --dataset-path "../SalesModel.Dataset"

# 2. Add pages (power-bi-pages skill)
pbi report add-page --display-name "Overview" --name overview
pbi report add-page --display-name "Details" --name details

# 3. Add visuals (power-bi-visuals skill)
pbi visual add --page overview --type card --name revenue_card
pbi visual add --page overview --type bar --name sales_by_region

# 4. Bind data (power-bi-visuals skill)
pbi visual bind revenue_card --page overview --field "Sales[Total Revenue]"
pbi visual bind sales_by_region --page overview \
    --category "Geo[Region]" --value "Sales[Amount]"

# 5. Apply theme (power-bi-themes skill)
pbi report set-theme --file brand-colors.json

# 6. Validate (this skill)
pbi report validate

Combining Model and Report

pbi-cli covers both the semantic model layer and the report layer:

# Model layer (requires pbi connect)
pbi connect
pbi measure create Sales "Total Revenue" "SUM(Sales[Amount])"

# Report layer (no connection needed)
pbi report create . --name "Sales"
pbi visual add --page overview --type card --name rev_card
pbi visual bind rev_card --page overview --field "Sales[Total Revenue]"

Related Skills

Skill	When to use
power-bi-visuals	Add, bind, update, delete visuals
power-bi-pages	Add, remove, configure pages and bookmarks
power-bi-themes	Themes, conditional formatting
power-bi-filters	Page and visual filters

JSON Output

pbi --json report info
pbi --json report validate

---

Gotchas

• report validate passes a PBIR that Desktop refuses to open: Validation only checks JSON structure and required files — it does not verify dataset binding, schema-URL versions, or visual queryState consistency. A clean validate followed by a Desktop "cannot open report" is a known footgun.
• --dataset-path is relative to the .Report folder, not the CWD: A ../Sales.Dataset argument resolves correctly at create time, but if you later move the .Report folder the binding silently breaks. Use a stable workspace layout or absolute paths in CI.
• pbi report reload sends keyboard shortcuts to whatever window has focus: If the user is typing in another app when the reload fires, keystrokes land in that app instead. Run reload only at the end of a batch and tell the user not to context-switch.
• report convert to .pbip does not bundle the semantic model: It produces a .pbip shell referencing the dataset by path. Distributing the resulting folder without also packaging the .SemanticModel directory yields a "dataset not found" error on open.
• PBIR schema versions are pinned per file, not per project: Mixing files written by different Desktop versions (e.g. one page edited in March-2026 build, another in January-2026 build) can fail validation in one and pass in another. Always upgrade the whole project together.
• --no-sync only applies to the command group it's on: pbi visual --no-sync add ... followed by pbi report set-background ... will still sync after the second command. Set --no-sync on every group involved in the batch.