Power BI Report Authoring Toolkit

⚠️ Public preview. The CLI command surface and library exports may change between 0.x versions. Pin to exact versions or expect breaking changes.

Command-line tooling for Power BI report (PBIR) authoring workflows: visual catalog lookup, formatting capability discovery, PBIR literal expression encoding and decoding, theme value helpers, and PBIR conformance validation. Designed for LLM agent workflows that author or validate PBIR files programmatically.

Scope: the toolkit reads and analyses; report files are produced and edited by your authoring agent or editor of choice, and verified in Power BI Desktop via @microsoft/powerbi-desktop-bridge-cli. Fabric publishing is out of scope.

Usage

npm install -g @microsoft/powerbi-report-authoring-cli
powerbi-report-author --help

Commands

Run powerbi-report-author --help for the full list. Top-level command groups:

| Group | Examples | Purpose | |---|---|---| | catalog | catalog list, catalog describe <visualType> | Built-in visual types, roles, formatting keys | | formatting | formatting list-objects <visualType>, formatting describe-object <visualType> <object>, formatting describe-property, formatting search, formatting list-vcos, formatting effective-properties | Discover formatting objects, properties, enum values, selectors | | expr | expr encode --kind <bool\|number\|integer\|string\|color\|themeColor> <value> [percent], expr decode '<json>' | Encode/decode PBIR literal expressions | | theme | theme encode --kind <…> <value>, theme shade-color <hex> <percent> | Theme-JSON value helpers | | validate | validate <path-to-.pbip-or-.Report> | Full PBIR conformance check (JSON Schema, IDs, formatting, theme, layout) | | preview-pages / preview-visuals / preview-filters / preview-themes | preview-visuals <path> [--with-derived] | Read-only enumeration for audits | | doctor | doctor | Environment self-check (Node, ajv, metadata provider, schema reachability) |

Output contract

Every command emits exactly one JSON object on stdout. The envelope is shape-discriminated — success has a top-level data field, failure has a top-level error field.

Success:

{ "data": { /* per-command shape */ } }

Failure (CLI level — invalid usage, file not found, unexpected exception):

{ "error": { "code": "...", "message": "...", "retryable": false, "details": {} } }

By default the envelope is minified single-line JSON so it stays inline-readable in agent harnesses (≈ 3× smaller than pretty-printed). Two global flags adjust this:

• --pretty — 2-space indented JSON for human reading.
• --out <file> — write the full envelope to <file> and emit a one-line summary envelope on stdout ({ "data": { "result": "...", "errorCount": ..., "warningCount": ..., "outFile": "..." } } for validate, { "data": { "outFile": "..." } } for other commands). Use when the artifact is large or you want to hand it off to another tool.

Progress messages and human-readable error output from the underlying commander library (usage hints on bad CLI input) are written to stderr; agent code paths only need to read stdout.

validate diagnostic shape

validate emits diagnostics grouped by code:

{
  "data": {
    "result": "succeeded" | "succeededWithWarnings" | "failed",
    "errorCount": N,
    "warningCount": N,
    "reportPath": "/abs/path/to/<Report>.Report",
    "diagnostics": {
      "<PBIR_CODE>": {
        "severity": "error" | "warning",
        "items": [
          { "message": "...", "file": "/abs/path/to/file.json", "path": "objects.foo.bar" },
          /* ... */
        ]
      }
    }
  }
}

diagnostics is omitted when result === "succeeded". severity is hoisted to the group level (it's intrinsic per code, so it doesn't vary across items). path is a dotted JSON path within file (not a JSON Pointer / not JSONPath RFC-9535 — just a readable dotted path). process.exitCode is 1 whenever result === "failed", 0 otherwise.

Severity policy

Severity is intrinsic to each diagnostic code (no --strict flag, no env vars). Catalog-violation codes emit as errors because they indicate real bugs, not transient metadata staleness. Two codes stay as warnings to act as a custom-visual escape hatch: PBIR_VISUAL_TYPE_UNKNOWN and PBIR_THEME_VISUAL_UNKNOWN.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations.

Please do not report security vulnerabilities through public GitHub issues.

For security reporting information, locations, contact information, and policies, please review the latest guidance for Microsoft repositories at https://aka.ms/SECURITY.md.

Code of conduct

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

See the full Microsoft Open Source Code of Conduct.