convez.ai
MCP ServerDados & AnalyticsAvançado
mudassir09

pbi-enterprise-cli

mudassir09/pbi-enterprise-cli

Automação Power BI/Fabric com BPA, DAX lint e MCP para agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

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

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 meses
Versão
v1.2.0
Issues abertas
0
Contribuidores
3

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.

CI codecov PyPI Python License Downloads


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 file backend reads TMDL/PBIP folders straight from your repo (pure Python, no .NET): governance, BPA, lint, docs, and semantic diff run against real models on ubuntu-latest
  • Live DAX on any OS — the rest backend runs DAX against any published dataset via the executeQueries API; the xmla backend 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 serve exposes every capability to Cursor/Copilot/Claude Desktop; pbi ask turns 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 desktop and xmla backends require Windows. The file, rest, and mock backends 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

AreaCommands
Semantic modelpbi model — tables, columns, relationships, lint, lineage
DAX measurespbi measure — add, update, delete, AI-generate, audit
DAX testingpbi dax — query, validate, YAML unit-test suites, coverage
DAX toolingpbi dax format (offline formatter) + pbi dax lint (static rules)
Report analysispbi report lint / field-usage / diff / a11y — PBIR intelligence
Source profilingpbi source — SQL, Excel, CSV, REST → star-schema scaffold
Calendarpbi calendar — generate date tables, fiscal year, mark-as-date-table
Report authoringpbi report — pages, bookmarks, drillthrough (PBIR GA format)
Visualspbi visual — 32 visual types, conditional formatting, data bars
Layoutpbi layout — shelf-packing auto-layout, named templates
Themespbi theme — generate WCAG-compliant themes from a brand colour
Filterspbi filter — relative-date, TopN, basic value filters
Governancepbi govern — built-in rules + BPA + plugins, SARIF, PR comments, tenant-wide scan, AI explain, AI-readiness audit
Tenant adminpbi tenant — usage analytics, access review, stale datasets, sensitivity labels
Security (RLS)pbi security — role add/delete/test, perspectives
Testingpbi test — data quality (DAX-compiled), schema contracts, RLS matrix, synthetic seed
Partitionspbi partition — add, refresh, delete, incremental refresh
Deploymentpbi deploy — snapshot, diff, push via XMLA
Fabricpbi fabric — items (full CRUD), workspaces, git sync, deployment pipelines, OneLake, capacity ops, jobs, Direct Lake, Fabric IQ ontologies (preview)
Snapshotspbi snapshot — create, list, restore, diff — model rollback
Environmentspbi env — named connections, use, diff, promote, drift detection
Model diffpbi diff — semantic TMDL diff (paths or git refs) + release notes
TMDLpbi database — export / import TMDL snapshots
Power Querypbi pquery — list M queries, query-folding analysis, M lint
Operationspbi ops — refresh orchestration, chains, health checks, webhooks
Migrationpbi migrate — Direct Lake readiness, PBIX extraction, dbt interop
Docspbi docs — data dictionary, lineage, Mermaid ERD, MkDocs site
AI & agentspbi ask (NL→DAX), pbi mcp serve (MCP server), pbi introspect
Scaffoldingpbi init — tests + CI workflow + pre-commit + config in one step
Diagnosticspbi doctor — check pythonnet, optional deps, platform
Watch modepbi watch — re-run governance + DAX tests on file change
REST APIpbi server — authenticated FastAPI server for pipeline integration
Skillspbi skills — install, list, check 10 Claude Code Power BI skills

Five-Backend Architecture

BackendWhen to useRequires
desktop (default)Local Power BI Desktop with a .pbip project openWindows + Desktop
xmlaPower BI Premium or Microsoft Fabric — no DesktopWindows + MSAL ([xmla] extra)
fileTMDL/PBIP folders straight from the repo — governance, lint, docs, diffNothing — works on Linux/macOS
restLive DAX against any published dataset (executeQueries API)A token — works on Linux/macOS
mockCI pipelines, unit tests, demosNothing — 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
SkillCovers
power-bi-modelingStar schema, source profiling, partitions, incremental refresh, calendar, M queries
power-bi-daxDAX authoring, Time Intelligence, YAML unit tests, filter context, design patterns
power-bi-performanceQuery tracing, benchmarking, VertiPaq, storage vs formula engine
power-bi-report-designPages, 32 visual types, bookmarks, drillthrough, auto-layout, conditional formatting
power-bi-design-systemWCAG themes, brand colours, typography, custom visual SDK
power-bi-governanceBuilt-in rules, BPA, custom plugins, auto-fix, CI gate
power-bi-security-and-docsRLS, perspectives, role testing, data dictionary, lineage, audit logs
power-bi-deploymentXMLA deploy, TMDL snapshots, multi-environment promotion, auth setup
power-bi-diagnosticspbi doctor, pythonnet/AMO resolution, error playbook, connection troubleshooting
power-bi-project-orchestratorCoordinates 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

FlagPurpose
--backend desktop|xmla|mock|file|restSelect backend (default: desktop)
--path <folder>TMDL/PBIP project folder (file backend)
--dry-runPreview changes without applying them
--json / --yamlMachine-readable output
--connection <name>Use a named connection from ~/.pbi-cli/connections.json
--port 5000Desktop local server port

Exit Code Contract

CodeMeaning
0Success
1User error — bad args, missing flags
2Connection error — Desktop not open, XMLA unreachable
3Validation error — governance violation, schema error
4Operation error — TOM write failed, partial completion

Environment Variables

VariablePurpose
ANTHROPIC_API_KEYClaude AI for pbi measure generate
PBI_SERVER_KEYAPI key for pbi server start
PBI_CLIENT_SECRETService principal secret for XMLA connections
PBI_REST_BEARERDefault 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

DocumentContents
docs/SOP.mdStandard Operating Procedure — the recommended end-to-end workflow using every feature
docs/auth/xmla-auth.mdXMLA auth: service principal, managed identity, device flow
docs/deployment.mdSnapshot format, diff algorithm, push safety, rollback
CHANGELOG.mdRelease history
SECURITY.mdSecurity policy and vulnerability reporting
CONTRIBUTING.mdBranch strategy, coding standards, PR guide
STABILITY.mdStable command surface, exit code contract, deprecation policy

License

MIT © Mudassir — see LICENSE.

The bundled AMO/ADOMD client libraries are licensed under the Microsoft Software License Terms.

Ver o original no GitHub

Bom para

Relacionados