powerbi-pbi-cli
Skill3 starsChanged 7 months agoMITView on GitHub
The pbi CLI (pbi-cli) for driving Power BI Desktop and PBIR reports from the terminal — visual bind with Column vs Measure resolution from the semantic model, implicit aggregation wrappers, --kind and --aggregation overrides, batching with --no-sync, and what pbi report reload actually does (closes and reopens Desktop, not a keyboard shortcut). Use when the user mentions: pbi CLI, pbi-cli, pbi visual bind, pbi visual bulk-bind, pbi report reload, pbi measure create, pbi connect, sync_desktop, --no-sync, broken slicer after bind, measure reference will not resolve, pbi-cli skills install, import-custom pbiviz.
In this repository58 other files it gives its agents.
- powerbi-audit-tenant-settingsSkill
- powerbi-bpa-rulesSkill
- powerbi-connect-pbidSkill
- powerbi-connectSkill
- powerbi-create-pbi-reportSkill
- powerbi-c-sharp-scriptingSkill
- powerbi-custom-visualsSkill
- powerbi-cyber-securitySkill
- powerbi-data-catalog-lineageSkill
- powerbi-data-governance-traceabilitySkill
- powerbi-data-transformationSkill
- powerbi-dax-masterySkill
- powerbi-dax-performanceSkill
- powerbi-daxSkill
- powerbi-deneb-visualsSkill
- powerbi-doctorSkill
- powerbi-duckdb-lakehouseSkill
- powerbi-fabric-appsSkill
- powerbi-fabric-app-templatesSkill
- powerbi-fabric-capacitySkill
- powerbi-fabric-cliSkill
- powerbi-fabric-pipelinesSkill
- powerbi-fabricSkill
- powerbi-lineage-analysisSkill
- powerbi-measure-glossarySkill
- powerbi-medallion-architectureSkill
- powerbi-modelSkill
- powerbi-modifying-theme-jsonSkill
- powerbi-paginated-reportsSkill
- powerbi-pbip-formatSkill
- powerbi-pbir-cliSkill
- powerbi-pbir-format-enhancedSkill
- powerbi-performance-scaleSkill
- powerbi-power-querySkill
- powerbi-project-managementSkill
- powerbi-python-visualsSkill
- powerbi-refresh-semantic-modelSkill
- powerbi-report-authoringSkill
- powerbi-report-conversionSkill
- powerbi-report-designSkill
- powerbi-reportSkill
- powerbi-report-structureSkill
- powerbi-report-themingSkill
- powerbi-review-reportSkill
- powerbi-review-semantic-modelSkill
- powerbi-r-visualsSkill
- powerbi-security-rlsSkill
- powerbi-source-integrationSkill
- powerbi-spark-livySkill
- powerbi-standardize-naming-conventionsSkill
- powerbi-star-schema-modelingSkill
- powerbi-svg-visualsSkill
- powerbi-te2-cliSkill
- powerbi-te-cliSkill
- powerbi-te-docsSkill
- powerbi-testing-validationSkill
- powerbi-time-series-dataSkill
- powerbi-tmdlSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 179
Read the
warningsarray: Every time. - Very specific: line 182
Use --no-sync for multi-step builds, then one explicit pbi report reload.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The pbi CLI
pbi-cli (Mina Saad, MIT) drives Power BI Desktop and PBIR report folders from the terminal:
semantic model edits over the local Analysis Services instance, and report-layer edits written
straight into PBIR JSON. It overlaps pbi-agent deliberately — use whichever is installed, and
know the differences below, because the failure modes are not the same.
Target version: ≥ 3.12.0. Earlier versions wrap every bound field as a Measure, which
silently produces broken slicers and tables. Check with pbi --version — and note that
--version itself only became trustworthy in 3.12.0, where it reads from package metadata
instead of a hardcoded constant that had drifted.
Two entry points, and it matters
| Entry point | Owns |
pbi | all model and report work — connect, model, measure, report, visual, filters, bookmarks, format, database |
pbi-cli | only skill management: pbi-cli skills install / list / uninstall |
pbi skills install does not exist. Claude Code integration is opt-in by design: pbi connect
does not write to ~/.claude/.
pipx install pbi-cli
pbi-cli skills install # opt in to the skill pack
pbi connect # attach to the open Desktop instancepbi visual bind — the part that costs people a day
Binding a field writes a field reference into visual.json. Whether it is written as a
Column or a Measure, and whether it is wrapped in an aggregation, decides whether the
visual renders at all.
How the kind is resolved (3.12.0+)
In order:
- The TMDL or
model.bimthat the report'sdefinition.pbirpoints at — on disk, no connection needed. - The live model via
pbi connect, opened only for fields missing on disk. - A per-visual role default; slicers default to
Column.
Names are canonicalised to the model's casing, and a measure referenced under the wrong table
is rewritten against its home table. A field found in neither place produces a warnings
entry rather than a silent guess — read the warnings. A warning here means the visual will
render empty, and reading it now is cheaper than opening Desktop to find out.
bind output carries kind and resolved_by per field. Check them. resolved_by telling
you a field came from a role default when you expected the model usually means the
definition.pbir path is wrong.
Implicit aggregation
A column bound to a value role — chart Y, matrix values, card, table — must be wrapped in
the aggregation Desktop would apply, not written as a bare Column. 3.12.0 does this:
- The function comes from the column's
summarizeByin the model, falling back toSumfor numeric columns. - On charts and matrices, a non-summarizable column (text, or
summarizeBy: none) is wrapped as a count, matching Desktop. - Tables and cards keep it as a plain column.
- Category, row, legend and slicer fields are never aggregated.
Overrides, when the model's summarizeBy is not what this visual needs:
pbi visual bind … --kind auto|column|measure
pbi visual bind … --aggregation sum|average|count|distinct-count|min|max|median|stdev|variance|noneFunction codes follow Microsoft's PBIR semanticQuery schema. Reach for --kind only when
resolution is demonstrably wrong — forcing it is how the pre-3.12 breakage happened in the
first place.
Role flags on bind, matching bulk-bind: --column, --line, --x, --y. --column
binds table columns and matrix column groups.
Preconditions
A measure must exist in the TMDL before you bind it. visual bind writes a reference; it
does not create the measure. Create it first:
pbi measure create "Total Revenue" -e "SUM(Sales[Amount])" -t SalesName positional, -e/--expression, -t/--table. The three-positional form
(pbi measure create Sales "Total Revenue" "SUM(...)") is rejected by Click — it appears in
older skill docs and is wrong.
Symptom table
| Symptom | Cause |
| Slicer renders broken or empty | field written as Measure — pre-3.12 bind, or a forced --kind measure |
| Column in a table shows one aggregated row | aggregation applied where a plain column was wanted — --aggregation none or --kind column |
| Chart Y axis blank | bare Column where Desktop expects an aggregate — let 3.12 resolve it, don't force column |
| Field silently absent | a warnings entry you did not read; the field is not in the model |
.pbip will not open in Desktop | schema violation, not a bind problem — see below |
pbi report reload is not a keyboard shortcut
It calls sync_desktop(): saves and closes the open .pbip, re-applies the PBIR edits that
Desktop's save would have overwritten, then reopens the file. It does not send
Ctrl+Shift+F5. Older skill text claimed it did, and people went looking in Microsoft's
shortcut docs for a key that was never pressed.
The consequence is bigger than the naming: every write command auto-syncs by default, so
pbi visual update closes and reopens Desktop. In a multi-step build that means one
close/reopen cycle per command.
# Batch: suppress per-command sync, then sync once at the end
pbi report … --no-sync
pbi visual … --no-sync
pbi filters … --no-sync
pbi bookmarks … --no-sync
pbi report reload--no-sync exists on the report, visual, filters and bookmarks groups. Use it for
anything beyond a single edit.
Desktop discovery notes that matter when reload appears to do nothing:
- Process discovery uses PowerShell
Get-CimInstance Win32_Process, notwmic—wmicwas removed from Windows 11 24H2 and later, where older versions reported "Power BI Desktop is not running" while it plainly was. If you see that message on current Windows, check the version before anything else. - Discovery matches the project name exactly, not a substring of ancestor directory names. The loose match in earlier versions could force-close, save and reopen a different person's session. Do not downgrade past this.
- The save prompt after close is polled, not checked once, and the deadline accommodates a large model write. A reload that looks hung on a big model is probably saving.
PBIP schema rules — the "won't open in Desktop" set
Desktop refuses a project on schema violations, usually with an unhelpful message:
definition.pbirmust point at a real model path, and the.pbipartifact entry must match.- Theme JSON carries properties that crash Desktop on open; validate a theme before shipping it
(
powerbi-modifying-theme-json). - Measures referenced by a visual must exist in the TMDL.
- PBIR 2.7.0 sets
additionalProperties: falseon the query object: the legacyCommandsblock (SemanticQueryDataShapeCommand) is a hard schema violation. OnlyqueryStateprojections are valid. 3.10.6+ no longer writes it; a hand-edited or migratedvisual.jsonstill might. - A missing
layoutOptimizationis not an error — the real Microsoft schema does not require it. Validators that flag it are checking a stale schema. report set-backgroundmust writetransparencyalongside the colour. Desktop defaults a missingtransparencyto 100 — fully invisible — so the colour silently does not render.
Other commands worth knowing
pbi visual import-custom dist/my.pbiviz [--replace] # embed a built .pbiviz; --replace by GUID
pbi visual list-custom # embedded vs public, with a kind column
pbi visual remove-custom <guid-or-name> # deregister and delete
pbi database diff-tmdl <folderA> <folderB> # offline TMDL diff; lineageTag-only noise stripped
pbi report validate # PBIR validationpbi-agent has equivalents for the custom-visual trio (pbi-agent visual import-custom,
list-custom, remove-custom) — the PBIR embedding logic there was ported from pbi-cli under
MIT and is credited in ATTRIBUTIONS.md. Use one tool per report; mixing them mid-build makes
a failure hard to attribute.
Guardrails
- Check
pbi --version≥ 3.12.0 before anybindwork. The pre-3.12 bind failure is silent at write time and only visible when a human opens the report. - Read the
warningsarray. Every time. - Close/reopen of Desktop touches the user's open session and unsaved state. Say what you are about to sync before the first write of a session.
- Use
--no-syncfor multi-step builds, then one explicitpbi report reload. - Model edits over a live Desktop connection are not transactional. For anything structural,
work in TMDL under source control (
powerbi-tmdl) and deploy, rather than mutating a live model.
Related skills
| Need | Skill |
| PBIR JSON structure | powerbi-pbir-format-enhanced, powerbi-pbip-format |
pbir.tools instead of pbi | powerbi-report-structure, powerbi-pbir-cli |
| Authoring a custom visual to import | powerbi-custom-visuals |
| Theme JSON that opens in Desktop | powerbi-modifying-theme-json |
| TMDL the binds resolve against | powerbi-tmdl, powerbi-model |
| Measures to bind | powerbi-dax-mastery |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

