Metadata-Version: 2.4
Name: pbi-enterprise-cli
Version: 4.0.0
Summary: Power BI one-stop-shop platform — CLI for AI-driven Power BI development
License: MIT AND LicenseRef-Microsoft-AS-Client-Libraries
Keywords: power-bi,cli,dax,tmdl,pbir
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: pythonnet>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.105.2; extra == "ai"
Provides-Extra: viz
Requires-Dist: Pillow>=10.0; extra == "viz"
Requires-Dist: wcag-contrast-ratio>=0.9; extra == "viz"
Requires-Dist: playwright>=1.44; extra == "viz"
Provides-Extra: xmla
Requires-Dist: msal>=1.28; extra == "xmla"
Provides-Extra: server
Requires-Dist: fastapi>=0.136.3; extra == "server"
Requires-Dist: uvicorn>=0.48.0; extra == "server"
Provides-Extra: sources
Requires-Dist: sqlalchemy>=2.0; extra == "sources"
Requires-Dist: openpyxl>=3.1.5; extra == "sources"
Requires-Dist: httpx>=0.27; extra == "sources"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: ruff>=0.15.15; extra == "dev"
Requires-Dist: mypy>=2.1.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Provides-Extra: all
Requires-Dist: pbi-enterprise-cli[ai,dev,server,sources,viz,xmla]; extra == "all"
Dynamic: license-file

# pbi-cli

> Full-stack Power BI automation from the command line — semantic model management, report authoring, governance enforcement, DAX testing, deployment pipelines, and 30 Claude Code skills.

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Tests](https://img.shields.io/badge/tests-575%20passing-brightgreen)
![Coverage](https://img.shields.io/badge/coverage-71%25-yellow)
![Version](https://img.shields.io/badge/version-4.0.0--dev-orange)

---

## What it does

`pbi-cli` gives you a single `pbi` command that covers every layer of Power BI development — no clicking through the Desktop UI, no manual file editing, no proprietary tooling dependencies.

| Area | Commands |
|---|---|
| **Semantic model** | `pbi model` — tables, columns, relationships, lint, lineage |
| **DAX measures** | `pbi measure` — add, update, delete, AI-generate |
| **DAX testing** | `pbi dax` — query, validate, YAML unit-test suites |
| **Source profiling** | `pbi source` — SQL, Excel, CSV, REST APIs → star-schema scaffold |
| **Report authoring** | `pbi report` — pages, bookmarks (PBIR GA format) |
| **Visuals** | `pbi visual` — 17 visual types, colour-scale & data-bar formatting |
| **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 + custom plugin system, `--fail-on` CI gate |
| **Security (RLS)** | `pbi security` — role add/delete/test |
| **Partitions** | `pbi partition` — add, refresh, delete |
| **Deployment** | `pbi deploy` — snapshot, diff, push via XMLA |
| **Snapshots** | `pbi snapshot` — create, list, restore, diff — model rollback |
| **Environments** | `pbi env` — named connections, use, diff, promote (dev→prod) |
| **TMDL** | `pbi database` — export / import TMDL snapshots |
| **Docs** | `pbi docs` — markdown/Confluence data dictionary, audit log |
| **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 30 Claude Code Power BI skills |

---

## Backends

The same CLI works against three backends — swap with `--backend`:

| Backend | When to use |
|---|---|
| `desktop` (default) | Local Power BI Desktop open with a `.pbip` project |
| `xmla` | Power BI Premium or Microsoft Fabric — no Desktop required |
| `mock` | CI pipelines, unit tests, demos — zero infrastructure |

---

## Installation

**Base install** (semantic model, governance, DAX, report authoring):
```bash
pip install pbi-enterprise-cli
```

**Optional feature groups:**
```bash
pip install "pbi-enterprise-cli[ai]"       # Claude AI measure generation
pip install "pbi-enterprise-cli[xmla]"     # XMLA auth (MSAL)
pip install "pbi-enterprise-cli[sources]"  # SQL / Excel / REST profiling
pip install "pbi-enterprise-cli[viz]"      # WCAG theme validation, screenshots
pip install "pbi-enterprise-cli[server]"   # Authenticated FastAPI REST server
pip install "pbi-enterprise-cli[all]"      # Everything
```

> **Requirements:** Python 3.10+. The `desktop` and `xmla` backends require Windows and the AMO .NET assemblies (installed with Power BI Desktop).

---

## Quick Start

```bash
# Check your setup
pbi doctor

# Connect to open Power BI Desktop and inspect the model
pbi model tables
pbi model relationships
pbi measure list

# Run governance checks (exit code 3 on errors — CI safe)
pbi govern check --fail-on error

# Auto-fix safe violations (PascalCase, missing format strings, etc.)
pbi govern fix --auto

# Add a measure
pbi measure add \
  --table Sales \
  --name "Total Revenue" \
  --expression "SUM(Sales[Revenue])" \
  --format-string "#,0.00" \
  --description "Net revenue after discounts"

# Run DAX unit tests
pbi dax test --suite tests/fixtures/measures/sales_suite.yaml

# Profile a SQL source and scaffold a star-schema model
pbi source profile --source "mssql://server/SalesDW" --output json
pbi source scaffold --source "mssql://server/SalesDW" \
  --output ./MyModel.SemanticModel/definition/
```

---

## Governance & CI/CD

Built-in rules + BPA (Best Practice Analyzer) run out of the box.
Drop a `.py` file in `~/.pbi-cli/rules/` to add organisation-specific rules.

```bash
pbi govern rules              # list all built-in + plugin rules
pbi govern check --fail-on error    # exit 3 on violations — CI gate
pbi --json govern check       # structured {summary, violations} JSON output
pbi govern fix --auto         # auto-fix PascalCase, format strings, folders
```

### BPA Compatibility

```bash
# Microsoft community rules (fetched live — same as Tabular Editor)
pbi govern bpa check

# Local rule set
pbi govern bpa check --file ./BPARules.json

# Filter by severity or category
pbi govern bpa check --severity error --category Performance
```

### GitHub Actions

Copy `.github/workflows/pbi-govern.yml` from this repo — it runs governance on every PR,
fails on errors, and posts a summary comment automatically.

```yaml
# One-liner governance gate for your own repo:
- run: pbi --backend mock --json govern check --fail-on error
```

See also `azure-pipelines-govern.yml` for Azure DevOps.

---

## Snapshots & Rollback

```bash
# Save a snapshot before risky changes
pbi snapshot create --label before-refactor

# See all snapshots
pbi snapshot list

# Diff current model against a snapshot
pbi snapshot diff 20260530_142300_before-refactor

# Restore (requires --confirm)
pbi snapshot restore 20260530_142300_before-refactor --confirm
```

---

## Multi-Environment Support

Named connections in `~/.pbi-cli/connections.json` — switch with one command:

```bash
pbi connections add           # interactive wizard
pbi env list                  # show all environments
pbi env use fabric-dev        # set default
pbi env promote fabric-dev fabric-prod --confirm   # deploy dev → prod
```

See `docs/auth/xmla-auth.md` for service principal, managed identity, and interactive auth.

---

## Authenticated REST Server

```bash
# Generate a key
export PBI_SERVER_KEY=$(pbi server generate-key)

# Start server (localhost-only by default)
pbi server start

# Call the API
curl -H "X-PBI-API-Key: $PBI_SERVER_KEY" http://localhost:7788/api/tables
```

The server binds to `127.0.0.1` by default. Use `--host 0.0.0.0` only behind a firewall.
All endpoints require the `X-PBI-API-Key` header — no unauthenticated access.

---

## XMLA Backend

Connect to Power BI Premium or Fabric without Desktop:

```bash
# Add a named connection
pbi connections add

# Use it
pbi --connection fabric-prod model tables
pbi --connection fabric-prod govern check --fail-on error
pbi --connection fabric-prod deploy push --workspace "Sales-PROD"
```

Full auth guide: [docs/auth/xmla-auth.md](docs/auth/xmla-auth.md)

---

## Claude Code Skills (30 skills)

Install Power BI skills into Claude Code for AI-assisted development:

```bash
# Install all 30 skills
pbi skills install --all

# Check compatibility with current CLI version
pbi skills check

# Install specific skills
pbi skills install power-bi-dax power-bi-governance
```

**30 bundled skills:**

| Skill | Purpose |
|---|---|
| `power-bi-advisor` | Master orchestrator — routes any question to the right skill |
| `power-bi-dax` | DAX measures, time intelligence, VAR/RETURN patterns |
| `power-bi-modeling` | Star schema, relationships, dimensional design |
| `power-bi-power-query` | M language, ETL, REST API connectors, query folding |
| `power-bi-performance` | Query optimisation, VertiPaq, DAX Studio patterns |
| `power-bi-rls-security` | Dynamic RLS, hierarchy security, OLS |
| `power-bi-themes` | WCAG-compliant themes, brand palettes |
| `power-bi-layout` | Shelf-packing auto-layout, navigation patterns |
| `power-bi-report` | Report pages, bookmarks, drillthrough |
| `power-bi-visual-selection` | Which visual for which data question |
| `power-bi-visuals` | Visual add/configure, conditional formatting |
| `power-bi-governance` | Rules, auto-fix, custom plugins, BPA |
| `power-bi-deployment` | XMLA deploy, snapshot, diff, rollback |
| `power-bi-deployment-pipeline` | Git integration, CI/CD, Azure DevOps |
| `power-bi-fabric` | OneLake, Medallion, Direct Lake, RTI, KQL |
| `power-bi-copilot` | Copilot setup, Q&A synonyms, Smart Narratives, AI visuals |
| `power-bi-templates` | Starter templates: Sales, Finance, HR, Operations, Marketing |
| `power-bi-sources` | SQL/Fabric/REST profiling, star-schema scaffold |
| `power-bi-docs` | Data dictionary, measure catalog, ERDs |
| `power-bi-testing` | DAX unit tests, regression suites, CI integration |
| `power-bi-security` | RLS, OLS, workspace roles |
| `power-bi-partitions` | Partition strategy, incremental refresh |
| `power-bi-diagnostics` | Doctor, environment checks, troubleshooting |
| `power-bi-patterns` | End-to-end workflows, design patterns |
| `power-bi-pages` | Drillthrough, tooltip pages, mobile layout |
| `power-bi-filters` | Visual, page, and report-level filters |
| `power-bi-design-system` | Brand consistency, typography, colour systems |
| `power-bi-page-designer` | Full page design from business domain description |
| `power-bi-project-orchestrator` | End-to-end project orchestration |
| `power-bi-troubleshooter` | Guided troubleshooting workflows |

---

## Global Flags

| Flag | Purpose |
|---|---|
| `--backend desktop\|xmla\|mock` | Select backend (default: `desktop`) |
| `--dry-run` | Preview changes without applying them |
| `--json` | Machine-readable JSON 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 |

See [STABILITY.md](STABILITY.md) for the full API stability policy.

---

## Environment Variables

| Variable | Purpose |
|---|---|
| `ANTHROPIC_API_KEY` | Claude AI for `pbi measure generate` |
| `PBI_SERVER_KEY` | API key for `pbi server start` (required) |
| `PBI_CLIENT_SECRET` | Service principal secret for XMLA connections |
| `PBI_REST_BEARER` | Default Bearer token for REST source profiling |

---

## Documentation

| Document | Contents |
|---|---|
| [docs/auth/xmla-auth.md](docs/auth/xmla-auth.md) | XMLA auth: service principal, managed identity, interactive |
| [docs/deployment.md](docs/deployment.md) | Snapshot format, diff algorithm, push safety, rollback |
| [docs/source-profiling.md](docs/source-profiling.md) | Source types, classification logic, scaffold output |
| [STABILITY.md](STABILITY.md) | Stable command surface, exit code contract, deprecation policy |
| [MAINTAINERS.md](MAINTAINERS.md) | Maintainer team, support SLAs, release process |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Branch strategy, coding standards, PR guide |

---

## Development

```bash
git clone https://github.com/mudassir09/pbi-enterprise-cli.git
cd pbi-enterprise-cli
pip install -e ".[all]"

# Run the full test suite (575 tests, ~7 s)
python -m pytest

# Lint
ruff check src/ tests/

# Type check
mypy src/
```

---

## License

[MIT](LICENSE) — © 2026 Mudassir
