pbi-enterprise-cli
mudassir09/pbi-enterprise-cli
Automação Power BI/Fabric com BPA, DAX lint e MCP para agentes IA
Ver no GitHubCLI enterprise para automação de Power BI e Microsoft Fabric com suporte a múltiplos backends (TMDL, XMLA, REST), análise BPA nativa em Python, testes e lint de DAX, e servidor MCP para agentes IA. Roda em qualquer OS sem dependências Windows.
Instalação
npx convez-ai mudassir09/pbi-enterprise-cli1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Governança e validação de modelos de dados em CI/CD
- Testes automatizados de medidas DAX com lint e formatação
- Integração de agentes IA (Claude, Copilot) para consultas de dados
- Orquestração de ciclo de vida Fabric (workspaces, pipelines, capacidade)
- Detecção de desvios e contratos de schema em repositórios
Veredito

Ferramenta madura e completa para engenheiros de dados e devops em ecosistemas Power BI/Fabric. O suporte nativo em Python para TMDL e a implementação pure-Python do BPA eliminam fricção em pipelines CI/CD Linux. MCP server e skills Claude agregam valor real para automação com IA.
README
A tradução para o português deste README ainda está na fila.
pbi-enterprise-cli is the enterprise-grade Power BI & Microsoft Fabric automation CLI — five backends (including a pure-Python TMDL reader that needs no Windows), the only Python-native BPA governance runner, full Fabric REST coverage, DAX testing + lint + format, PBIR report intelligence, a declarative test platform, an MCP server for AI agents, and 10 Claude Code skills.
Key differentiators vs alternatives:
- Real artifacts on any OS — the
filebackend reads TMDL/PBIP folders straight from your repo (pure Python, no .NET): governance, BPA, lint, docs, and semantic diff run against real models onubuntu-latest - Live DAX on any OS — the
restbackend runs DAX against any published dataset via theexecuteQueriesAPI; thexmlabackend gives full read/write on Windows - Python-native BPA runner — the only Python implementation of Best Practice Analyzer; same ruleset as Tabular Editor, zero extra tooling
- Full Fabric lifecycle — items (CRUD via the Item Definition API), workspaces, git sync, deployment pipelines, OneLake, capacity pause/resume/scale, jobs, Direct Lake diagnostics
- Quality platform — DAX lint/format, report lint + field-usage analysis, dbt-style data tests, schema contracts, RLS matrices, drift detection — all CI-gateable with exit codes and SARIF
- AI-agent native —
pbi mcp serveexposes every capability to Cursor/Copilot/Claude Desktop;pbi askturns English into executed DAX; 10 Claude Code skills install in one step - One-step CI — a published GitHub Action and pre-commit hooks: the governance gate is one
uses:line
Installation
Recommended — uv (fastest, manages Python automatically, no PATH issues on Windows):
uv tool install pbi-enterprise-cli
uv tool install "pbi-enterprise-cli[all]" # all optional features
Alternative — pipx:
pipx install pbi-enterprise-cli
Fallback — pip:
pip install pbi-enterprise-cli
With specific extras:
uv tool install "pbi-enterprise-cli[ai,xmla]" # Claude AI + XMLA/Fabric
uv tool install "pbi-enterprise-cli[sources]" # SQL / Excel / REST profiling
uv tool install "pbi-enterprise-cli[server]" # FastAPI REST server
uv tool install "pbi-enterprise-cli[viz]" # WCAG theme validation
Requirements: Python 3.10–3.13. The
desktopandxmlabackends require Windows. Thefile,rest, andmockbackends work on Linux and macOS — CI pipelines need no Windows runner for governance, BPA, lint, DAX tests, docs, or diff.
60-Second Quickstart
# 1. Verify setup
pbi doctor
# 2. Connect to open Power BI Desktop + install all 10 Claude Code skills
pbi connect
# 3. Explore the model
pbi model tables
pbi measure list
# 4. Run governance and BPA
pbi govern check --fail-on error
pbi govern bpa check --severity error
# 5. Fix safe violations automatically
pbi govern fix --auto
# 6. Run DAX unit tests + lint
pbi dax test --suite ./tests/measures/
pbi dax lint --fail-on error
# 7. Deploy to Fabric (XMLA — or `pbi fabric item update` from any OS)
pbi deploy push --connection fabric-prod
No Desktop open? Everything above also works straight off the repo files:
pbi --backend file --path . govern check # governance on real TMDL, any OS
pbi --backend file --path . docs site # data-dictionary site from the repo
pbi ask "top 10 customers by revenue" # English → DAX → results (rest/xmla)
Before vs After
Command Reference
| Area | Commands |
|---|---|
| Semantic model | pbi model — tables, columns, relationships, lint, lineage |
| DAX measures | pbi measure — add, update, delete, AI-generate, audit |
| DAX testing | pbi dax — query, validate, YAML unit-test suites, coverage |
| DAX tooling | pbi dax format (offline formatter) + pbi dax lint (static rules) |
| Report analysis | pbi report lint / field-usage / diff / a11y — PBIR intelligence |
| Source profiling | pbi source — SQL, Excel, CSV, REST → star-schema scaffold |
| Calendar | pbi calendar — generate date tables, fiscal year, mark-as-date-table |
| Report authoring | pbi report — pages, bookmarks, drillthrough (PBIR GA format) |
| Visuals | pbi visual — 32 visual types, conditional formatting, data bars |
| Layout | pbi layout — shelf-packing auto-layout, named templates |
| Themes | pbi theme — generate WCAG-compliant themes from a brand colour |
| Filters | pbi filter — relative-date, TopN, basic value filters |
| Governance | pbi govern — built-in rules + BPA + plugins, SARIF, PR comments, tenant-wide scan, AI explain, AI-readiness audit |
| Tenant admin | pbi tenant — usage analytics, access review, stale datasets, sensitivity labels |
| Security (RLS) | pbi security — role add/delete/test, perspectives |
| Testing | pbi test — data quality (DAX-compiled), schema contracts, RLS matrix, synthetic seed |
| Partitions | pbi partition — add, refresh, delete, incremental refresh |
| Deployment | pbi deploy — snapshot, diff, push via XMLA |
| Fabric | pbi fabric — items (full CRUD), workspaces, git sync, deployment pipelines, OneLake, capacity ops, jobs, Direct Lake, Fabric IQ ontologies (preview) |
| Snapshots | pbi snapshot — create, list, restore, diff — model rollback |
| Environments | pbi env — named connections, use, diff, promote, drift detection |
| Model diff | pbi diff — semantic TMDL diff (paths or git refs) + release notes |
| TMDL | pbi database — export / import TMDL snapshots |
| Power Query | pbi pquery — list M queries, query-folding analysis, M lint |
| Operations | pbi ops — refresh orchestration, chains, health checks, webhooks |
| Migration | pbi migrate — Direct Lake readiness, PBIX extraction, dbt interop |
| Docs | pbi docs — data dictionary, lineage, Mermaid ERD, MkDocs site |
| AI & agents | pbi ask (NL→DAX), pbi mcp serve (MCP server), pbi introspect |
| Scaffolding | pbi init — tests + CI workflow + pre-commit + config in one step |
| Diagnostics | pbi doctor — check pythonnet, optional deps, platform |
| Watch mode | pbi watch — re-run governance + DAX tests on file change |
| REST API | pbi server — authenticated FastAPI server for pipeline integration |
| Skills | pbi skills — install, list, check 10 Claude Code Power BI skills |
Five-Backend Architecture
| Backend | When to use | Requires |
|---|---|---|
desktop (default) | Local Power BI Desktop with a .pbip project open | Windows + Desktop |
xmla | Power BI Premium or Microsoft Fabric — no Desktop | Windows + MSAL ([xmla] extra) |
file | TMDL/PBIP folders straight from the repo — governance, lint, docs, diff | Nothing — works on Linux/macOS |
rest | Live DAX against any published dataset (executeQueries API) | A token — works on Linux/macOS |
mock | CI pipelines, unit tests, demos | Nothing — works on Linux/macOS |
# Swap with --backend
pbi --backend file --path . govern check --fail-on error # real artifacts, any OS
pbi --backend rest dax query "EVALUATE TOPN(10, Sales)" # live Fabric, any OS
pbi --backend xmla model tables # Fabric without Desktop
pbi --backend desktop measure list # local Desktop (default)
The Only Python-Native BPA Runner
pbi-enterprise-cli is the only Python-native implementation of the Best Practice Analyzer — run the same rule engine used by Tabular Editor without installing .NET 6 or Tabular Editor itself.
# Microsoft community BPA rules (fetched live — same ruleset as Tabular Editor)
pbi govern bpa check
# Filter to errors only — safe CI gate
pbi govern bpa check --severity error
# Local corporate rule file
pbi govern bpa check --file ./governance/CorpBPARules.json
# JSON output for downstream tooling
pbi --json govern bpa check --severity error
GitHub Actions governance gate — works on ubuntu-latest, no Windows runner needed:
- name: BPA governance gate
run: pbi --backend mock govern bpa check --severity error
Custom governance plugin — drop a .py file in ~/.pbi-cli/rules/:
from pbi_cli.governance.engine import GovernanceRule, Violation
class NoHardcodedDatesRule(GovernanceRule):
id = "custom.no-hardcoded-dates"
severity = "error"
def check(self, model) -> list[Violation]:
return [
Violation(self, f"Measure '{m.name}' contains a hardcoded year")
for m in model.measures
if "2024" in m.expression or "2025" in m.expression
]
Claude Code Skills
Run pbi connect to install all 10 skills into ~/.claude/skills/ in one step:
pbi connect # connects to Desktop + installs skills + prints model summary
Or install manually:
pbi skills install --all
pbi skills check # verify compatibility with installed CLI version
| Skill | Covers |
|---|---|
power-bi-modeling | Star schema, source profiling, partitions, incremental refresh, calendar, M queries |
power-bi-dax | DAX authoring, Time Intelligence, YAML unit tests, filter context, design patterns |
power-bi-performance | Query tracing, benchmarking, VertiPaq, storage vs formula engine |
power-bi-report-design | Pages, 32 visual types, bookmarks, drillthrough, auto-layout, conditional formatting |
power-bi-design-system | WCAG themes, brand colours, typography, custom visual SDK |
power-bi-governance | Built-in rules, BPA, custom plugins, auto-fix, CI gate |
power-bi-security-and-docs | RLS, perspectives, role testing, data dictionary, lineage, audit logs |
power-bi-deployment | XMLA deploy, TMDL snapshots, multi-environment promotion, auth setup |
power-bi-diagnostics | pbi doctor, pythonnet/AMO resolution, error playbook, connection troubleshooting |
power-bi-project-orchestrator | Coordinates multi-skill workflows: model → DAX → governance → report → deploy |
CI/CD Integration
Full governance + BPA + DAX lint + tests run on ubuntu-latest against the real TMDL artifacts in your repo — no Windows runner, no Power BI infrastructure.
One step with the published GitHub Action:
# .github/workflows/pbi-govern.yml
name: Power BI Governance
on: [push, pull_request]
permissions:
pull-requests: write
security-events: write
jobs:
govern:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: mudassir09/pbi-enterprise-cli@v1
with:
path: .
fail-on: error
comment-pr: "true" # governance summary as a PR comment
sarif: pbi-governance.sarif # violations in the code-scanning UI
Or hand-rolled, with SARIF + drift detection:
- run: pip install pbi-enterprise-cli
- run: pbi --backend file --path . govern check --fail-on error --sarif gov.sarif
- run: pbi --backend file --path . dax lint --fail-on error
- run: pbi --backend file --path . dax format --check
- run: pbi --backend file --path . report lint --pbip . --fail-on error
- run: pbi diff main . --git --release-notes model-changes.md
- uses: github/codeql-action/upload-sarif@v3
with: { sarif_file: gov.sarif }
Pre-commit hooks (.pre-commit-config.yaml):
repos:
- repo: https://github.com/mudassir09/pbi-enterprise-cli
rev: v1.1.0
hooks:
- id: pbi-govern
- id: pbi-dax-lint
- id: pbi-dax-format
Scaffold all of this in one command: pbi init.
Global Flags
| Flag | Purpose |
|---|---|
--backend desktop|xmla|mock|file|rest | Select backend (default: desktop) |
--path <folder> | TMDL/PBIP project folder (file backend) |
--dry-run | Preview changes without applying them |
--json / --yaml | Machine-readable output |
--connection <name> | Use a named connection from ~/.pbi-cli/connections.json |
--port 5000 | Desktop local server port |
Exit Code Contract
| Code | Meaning |
|---|---|
0 | Success |
1 | User error — bad args, missing flags |
2 | Connection error — Desktop not open, XMLA unreachable |
3 | Validation error — governance violation, schema error |
4 | Operation error — TOM write failed, partial completion |
Environment Variables
| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY | Claude AI for pbi measure generate |
PBI_SERVER_KEY | API key for pbi server start |
PBI_CLIENT_SECRET | Service principal secret for XMLA connections |
PBI_REST_BEARER | Default Bearer token for REST source profiling |
Contributing
Contributions are welcome. See CONTRIBUTING.md for setup instructions, branch strategy, and the PR process.
Good First Issues are labelled good first issue — these are self-contained tasks with clear acceptance criteria and no deep context required.
Documentation
| Document | Contents |
|---|---|
| docs/SOP.md | Standard Operating Procedure — the recommended end-to-end workflow using every feature |
| docs/auth/xmla-auth.md | XMLA auth: service principal, managed identity, device flow |
| docs/deployment.md | Snapshot format, diff algorithm, push safety, rollback |
| CHANGELOG.md | Release history |
| SECURITY.md | Security policy and vulnerability reporting |
| CONTRIBUTING.md | Branch strategy, coding standards, PR guide |
| STABILITY.md | Stable command surface, exit code contract, deprecation policy |
License
The bundled AMO/ADOMD client libraries are licensed under the Microsoft Software License Terms.