# Power BI Desktop Bridge CLI

Command-line tooling for automating Power BI Desktop through the Desktop Bridge named
pipe. It is designed for agent workflows that edit PBIR/PBIP files, reload the
open report in Desktop, capture screenshots, and verify rendered output.

## Usage

```bash
npm install -g @microsoft/powerbi-desktop-bridge-cli
powerbi-desktop status
```

## Commands

| Command | Purpose |
|---------|---------|
| `powerbi-desktop open <path.pbip\|path.pbix>` | Launch Power BI Desktop with a report |
| `powerbi-desktop status [--pid <pid>]` | List bridge instances, current files, unsaved-change state, and PBIR pages resolved from each instance's current file |
| `powerbi-desktop manifest --pid <pid>` | Print the Desktop Bridge manifest for one Desktop instance |
| `powerbi-desktop reload --pid <pid>` | Reload the selected Desktop instance's current PBIP/PBIR report definition. For semantic model changes, use the semantic-model workflow and reopen the PBIP if changes are not reflected. |
| `powerbi-desktop screenshot <page-id> --pid <pid> [--scale <1-3>]` | Capture one report page from one selected Desktop instance; CLI default scale is `2` |
| `powerbi-desktop screenshot-all --pid <pid> --output-dir <dir> [--scale <1-3>]` | Capture every page listed in the selected Desktop instance's current PBIR `pages.json`; CLI default scale is `2` |

Most commands operate on a single Power BI Desktop process. When more than one
Desktop instance is available, run `powerbi-desktop status` first and pass the
desired bridge PID with `--pid`.

Commands write machine-readable JSON to stdout. Progress messages and
non-contract diagnostics are written to stderr so stdout can be piped safely to
other tools.

`reload` reloads the PBIP/PBIR report currently open in the selected Desktop
instance. It does not accept a separate report path; open the desired report in
Desktop first, then target that Desktop process with `--pid`.

Run reload and screenshot operations serially for a given PID. Discovery
commands such as `status` can run concurrently, but overlapping operations
against the same Desktop process may be cancelled or time out. Use
`--wait-seconds` when the report is still loading or immediately after a reload.

## 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](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). 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](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](https://opensource.microsoft.com/codeofconduct/).