pbir-cli

name: pbir-cli description: 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 , pbir-cli, pbir set/get/ls/add/new/rm/validate/publish, or any specific pbir subcommand.

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