pbir CLI — Verb Index
Agent-first CLI for manipulating local Power BI reports in PBIR format. Install separately: uv tool install pbir-cli. Verify with pbir --version.
Run discovery before every mutation. pbir schema describe <type>.<container> is the canonical way to confirm a property exists before pbir set. Run pbir validate after every mutation.
Path Syntax
Report.Report/Page.Page/Visual.Visual
- Type suffixes (
.Report, .Page, .Visual) are REQUIRED
- Glob patterns:
**/*.Visual, **/card*.Visual
- Property dot-notation after path:
Visual.Visual.title.fontSize
- Reports must be local PBIR — use
pbir download to fetch from Fabric first
Global Flags
| Flag |
Purpose |
--quiet / -q |
Suppress animations, tips, spinners (prefer for scripts) |
--debug |
Tracebacks, timing, path resolution to stderr |
--version / -V |
Show version |
--show-legacy |
Include legacy non-PBIR reports in listings |
Verb–Noun Groups
| Group |
Entry commands |
Detail |
| Discovery |
pbir ls, pbir tree, pbir find, pbir cat, pbir get |
references/REFERENCE.md § Discovery |
| Schema |
pbir schema types, pbir schema containers, pbir schema describe, pbir schema check, pbir schema upgrade |
references/REFERENCE.md § Schema |
| Property get/set |
pbir set, pbir get, pbir visuals properties, pbir visuals format |
references/REFERENCE.md § Property |
| Report |
pbir new report, pbir report rebind, pbir report convert, pbir report merge, pbir validate, pbir backup, pbir restore |
references/REFERENCE.md § Report |
| Pages |
pbir pages …, pbir add page |
references/REFERENCE.md § Pages |
| Visuals |
pbir add visual, pbir visuals … |
references/REFERENCE.md § Visuals |
| Conditional formatting |
pbir visuals cf …, pbir visuals format-field, pbir visuals format-state |
references/REFERENCE.md § CF |
| Filters |
pbir filters …, pbir add filter |
references/REFERENCE.md § Filters |
| Fields |
pbir fields … |
references/REFERENCE.md § Fields |
| Theme |
pbir theme … |
references/REFERENCE.md § Theme |
| DAX |
pbir dax measures …, pbir dax viscalcs … |
references/REFERENCE.md § DAX |
| Bookmarks & annotations |
pbir bookmarks …, pbir annotations …, pbir add annotation |
references/REFERENCE.md § Bookmarks |
| Connection / publish |
pbir connect, pbir profile, pbir download, pbir publish, pbir open |
references/REFERENCE.md § Connection |
| Model inspection |
pbir model … |
references/REFERENCE.md § Model |
| Removal |
pbir rm |
references/REFERENCE.md § Removal |
| Batch |
pbir batch run, pbir validate |
references/REFERENCE.md § Batch |
Discovery Quickstart
Always run these first — they tell you what already exists before you mutate anything:
pbir ls # All reports with counts
pbir ls --tree # Tree view
pbir ls "Sales.Report" # Pages, filters, theme
pbir ls "Sales.Report/Overview.Page" # Visuals on page
pbir tree "Sales.Report" -v # Tree with field bindings
pbir find "**/*.Visual" --count # Count visuals
pbir find "**/card*.Visual" --json # Glob + JSON
pbir cat "Sales.Report/Overview.Page" # Raw page JSON
pbir cat "Sales.Report/theme" # Theme JSON
pbir schema types # List visual types
pbir schema describe card.title # Properties, types, ranges
See references/REFERENCE.md § Discovery and references/REFERENCE.md § Schema for the full flag set.
Gotchas
| Issue |
Cause |
Fix |
pbir: command not found |
Not installed |
uv tool install pbir-cli |
| Glob pattern returns nothing |
Missing -f flag on set |
Add -f for glob selectors |
| "Report not found" |
Missing .Report type suffix |
Paths require Name.Report, Name.Page, Name.Visual |
set fails with "unknown property" |
Property not discovered first |
Run pbir schema describe <type>.<container> |
| Publish fails after local edits |
Structure invalid |
Run pbir validate before publish |
pbir validate floods SCHEMA_DEGRADED warnings |
Declared visualContainer schema version isn't bundled with the CLI; a fallback schema was used |
Cosmetic, one per file — only errors block. Note schema-valid ≠ engine-valid: verify hand-authored SQExpr shapes against Desktop-serialized reports (e.g. microsoft/BCApps); see pbir-filters § TopN |
| UnicodeEncodeError on Windows |
cp1252 stdout encoding |
Set PYTHONIOENCODING=utf-8 |
| Theme changes not applied per visual |
Visual has inline override |
pbir visuals clear-formatting --only-containers -f |
pbir download fails |
fab CLI not authenticated |
Run fab auth login first |
| Visual overlaps existing header |
Placed coordinates without measuring scaffold |
Inspect the scaffolded page.json before laying out |
pbir new report creates new theme each time |
Default is sqlbi |
Do NOT re-apply unless user requests different theme |
See also
- references/REFERENCE.md — full per-command flag and argument reference
pbir-report-workflow — end-to-end report creation with this CLIpbir-pages — page.json structure consumed by pbir pages …pbir-visual-json — visual.json structure consumed by pbir visuals …pbir-themes — theme JSON structure consumed by pbir theme …
1---2name: pbir-cli3description: Use when running the pbir CLI (install via uv tool install pbir-cli) to inspect or edit local Power BI PBIR reports. Covers path syntax (Report.Report/Page.Page/Visual.Visual with required type suffixes, glob patterns, property dot-notation), verb noun groups — report / page / visual / filter / bookmark / theme / dax / fields / schema / profile / annotation / model — plus discovery verbs (ls / tree / find / cat / get / schema describe) that should run before any mutation, property get/set with glob bulk edits requiring -f, validation and publish flows, download/publish to Fabric workspaces, and batch runs. Detailed per-command flags and arguments live in references/REFERENCE.md. Invoke whenever the user mentions pbir <verb>, pbir-cli, pbir set/get/ls/add/new/rm/validate/publish, or any specific pbir subcommand.4---56## pbir CLI — Verb Index78Agent-first CLI for manipulating local Power BI reports in PBIR format. Install separately: `uv tool install pbir-cli`. Verify with `pbir --version`.910**Run discovery before every mutation.** `pbir schema describe <type>.<container>` is the canonical way to confirm a property exists before `pbir set`. Run `pbir validate` after every mutation.1112### Path Syntax1314```15Report.Report/Page.Page/Visual.Visual16```1718- Type suffixes (`.Report`, `.Page`, `.Visual`) are REQUIRED19- Glob patterns: `**/*.Visual`, `**/card*.Visual`20- Property dot-notation after path: `Visual.Visual.title.fontSize`21- Reports must be local PBIR — use `pbir download` to fetch from Fabric first2223### Global Flags2425| Flag | Purpose |26|---|---|27| `--quiet` / `-q` | Suppress animations, tips, spinners (prefer for scripts) |28| `--debug` | Tracebacks, timing, path resolution to stderr |29| `--version` / `-V` | Show version |30| `--show-legacy` | Include legacy non-PBIR reports in listings |3132### Verb–Noun Groups3334| Group | Entry commands | Detail |35|---|---|---|36| Discovery | `pbir ls`, `pbir tree`, `pbir find`, `pbir cat`, `pbir get` | references/REFERENCE.md § Discovery |37| Schema | `pbir schema types`, `pbir schema containers`, `pbir schema describe`, `pbir schema check`, `pbir schema upgrade` | references/REFERENCE.md § Schema |38| Property get/set | `pbir set`, `pbir get`, `pbir visuals properties`, `pbir visuals format` | references/REFERENCE.md § Property |39| Report | `pbir new report`, `pbir report rebind`, `pbir report convert`, `pbir report merge`, `pbir validate`, `pbir backup`, `pbir restore` | references/REFERENCE.md § Report |40| Pages | `pbir pages …`, `pbir add page` | references/REFERENCE.md § Pages |41| Visuals | `pbir add visual`, `pbir visuals …` | references/REFERENCE.md § Visuals |42| Conditional formatting | `pbir visuals cf …`, `pbir visuals format-field`, `pbir visuals format-state` | references/REFERENCE.md § CF |43| Filters | `pbir filters …`, `pbir add filter` | references/REFERENCE.md § Filters |44| Fields | `pbir fields …` | references/REFERENCE.md § Fields |45| Theme | `pbir theme …` | references/REFERENCE.md § Theme |46| DAX | `pbir dax measures …`, `pbir dax viscalcs …` | references/REFERENCE.md § DAX |47| Bookmarks & annotations | `pbir bookmarks …`, `pbir annotations …`, `pbir add annotation` | references/REFERENCE.md § Bookmarks |48| Connection / publish | `pbir connect`, `pbir profile`, `pbir download`, `pbir publish`, `pbir open` | references/REFERENCE.md § Connection |49| Model inspection | `pbir model …` | references/REFERENCE.md § Model |50| Removal | `pbir rm` | references/REFERENCE.md § Removal |51| Batch | `pbir batch run`, `pbir validate` | references/REFERENCE.md § Batch |5253### Discovery Quickstart5455Always run these first — they tell you what already exists before you mutate anything:5657```bash58pbir ls # All reports with counts59pbir ls --tree # Tree view60pbir ls "Sales.Report" # Pages, filters, theme61pbir ls "Sales.Report/Overview.Page" # Visuals on page62pbir tree "Sales.Report" -v # Tree with field bindings63pbir find "**/*.Visual" --count # Count visuals64pbir find "**/card*.Visual" --json # Glob + JSON65pbir cat "Sales.Report/Overview.Page" # Raw page JSON66pbir cat "Sales.Report/theme" # Theme JSON67pbir schema types # List visual types68pbir schema describe card.title # Properties, types, ranges69```7071See references/REFERENCE.md § Discovery and references/REFERENCE.md § Schema for the full flag set.7273### Gotchas7475| Issue | Cause | Fix |76|---|---|---|77| `pbir: command not found` | Not installed | `uv tool install pbir-cli` |78| Glob pattern returns nothing | Missing `-f` flag on `set` | Add `-f` for glob selectors |79| "Report not found" | Missing `.Report` type suffix | Paths require `Name.Report`, `Name.Page`, `Name.Visual` |80| `set` fails with "unknown property" | Property not discovered first | Run `pbir schema describe <type>.<container>` |81| Publish fails after local edits | Structure invalid | Run `pbir validate` before publish |82| `pbir validate` floods `SCHEMA_DEGRADED` warnings | Declared visualContainer schema version isn't bundled with the CLI; a fallback schema was used | Cosmetic, one per file — only errors block. Note schema-valid ≠ engine-valid: verify hand-authored SQExpr shapes against Desktop-serialized reports (e.g. microsoft/BCApps); see `pbir-filters` § TopN |83| UnicodeEncodeError on Windows | cp1252 stdout encoding | Set `PYTHONIOENCODING=utf-8` |84| Theme changes not applied per visual | Visual has inline override | `pbir visuals clear-formatting --only-containers -f` |85| `pbir download` fails | fab CLI not authenticated | Run `fab auth login` first |86| Visual overlaps existing header | Placed coordinates without measuring scaffold | Inspect the scaffolded page.json before laying out |87| `pbir new report` creates new theme each time | Default is sqlbi | Do NOT re-apply unless user requests different theme |8889### See also9091- [references/REFERENCE.md](references/REFERENCE.md) — full per-command flag and argument reference92- `pbir-report-workflow` — end-to-end report creation with this CLI93- `pbir-pages` — page.json structure consumed by `pbir pages …`94- `pbir-visual-json` — visual.json structure consumed by `pbir visuals …`95- `pbir-themes` — theme JSON structure consumed by `pbir theme …`
wardawgmalvicious