---
id: MinaSaad1/pbi-cli/power-bi-report
version: "3b1915a3"
license: MIT
install: manual
updated: 2026-07-27
---

# Power BI Report — Power BI Report lets you build PBIR projects from the ground up using pbi-cli, handling scaffolding, validation, live preview, and Desktop sync. Work with the folder-based JSON structure directly—no Desktop connection required for most tasks.

Publisher: MinaSaad1 · Stars: 424 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/MinaSaad1/pbi-cli`

## SKILL.md

# 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

```bash
# 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

```bash
# 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:

```bash
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

```bash
# 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 saves and closes the open `.pbip` in Desktop, re-applies
any PBIR edits that Desktop's save would overwrite, then reopens the file.

Requires the `reload` optional dependency (installs `pywin32`):
`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.
The sync closes Desktop with save and reopens the `.pbip` (it does not send a
keyboard shortcut), so users will see Desktop close and relaunch after each
write. When building a report in multiple steps, this causes Desktop to
close-and-reopen 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:

```bash
# 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

```bash
# 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

## Schema Rules (Don't Break These)

These constraints are not obvious but will silently crash PBI Desktop on open:

### `.pbip` artifacts — only `report` is allowed

The `.pbip` file's `artifacts` array must contain ONLY a `report` entry.
Never add a `dataset` entry — the schema rejects it:

```json
// CORRECT
"artifacts": [{ "report": { "path": "MyReport.Report" } }]

// WRONG — crashes on open with a schema validation error
"artifacts": [
  { "report": { "path": "MyReport.Report" } },
  { "dataset": { "path": "MyModel.SemanticModel" } }
]
```

The semantic model is linked via `definition.pbir`, not the `.pbip` artifacts.

### `definition.pbir` path — must be a non-null string

`datasetReference.byPath.path` must always be a non-null string pointing to the
SemanticModel folder. Setting it to `null` is a schema violation:

```json
// CORRECT
"datasetReference": { "byPath": { "path": "../MyModel.SemanticModel" } }

// WRONG — null is not allowed by the schema
"datasetReference": { "byPath": { "path": null } }
```

### Always validate before opening Desktop

```bash
pbi report validate
```

Run this after every structural change. It catches JSON parse errors (including
trailing commas), missing required files, and broken page references before
PBI Desktop sees them.

## Workflow: Build a Complete Report

This workflow uses commands from multiple skills:

```bash
# 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:

```bash
# Model layer (requires pbi connect)
pbi connect
pbi measure create "Total Revenue" -e "SUM(Sales[Amount])" -t Sales

# 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

```bash
pbi --json report info
pbi --json report validate
```


[View on SkillFed](https://skillfed.io/MinaSaad1/pbi-cli/power-bi-report) · [View on GitHub](https://github.com/MinaSaad1/pbi-cli)