julianobarbosa/power-bi-report

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.