Skip to content
ZYNXTECH

pbidriver

WebDriver for Power BI Desktop, so AI agents can see and drive the reports they edit.

Agents can already write DAX and edit PBIP files, but they cannot see the result. pbidriver gives them pixel-exact captures, the numbers behind every visual, slicers, menus, dialogs, DAX and Performance Analyzer timings, from a CLI that prints one JSON object per call.

pip install pbidriver
npx pbidriver

> pbidriver shot --page "Overview" --annotate

{"ok": true, "file": "pbidriver_shots/...png",

"alerts": {"blocked": false}, ...}

> pbidriver read --visual 4

{"ok": true, "points": [...], ...}

> pbidriver slicer --visual 5 --select "West"

{"ok": true, ...}

> ▍

commands, each printing one JSON object
25commands, each printing one JSON object
views it can capture, from the canvas to TMDL
5views it can capture, from the canvas to TMDL
dialog technologies it detects and answers
3dialog technologies it detects and answers
agents with setup guides, Claude Code to Cursor
4agents with setup guides, Claude Code to Cursor

The gap it closes

Coding agents can write DAX and edit the files of a PBIP project. What they cannot do is look at the report afterwards. A screenshot of the whole desktop is noisy and needs the window in focus, and publishing to the Power BI service to check each change breaks the fast loop of edit, look, fix.

pbidriver runs locally against Power BI Desktop. Every command is a CLI call that prints one JSON object, so any agent that can run a shell command can use it: Claude Code, Codex, GitHub Copilot, Cursor or a script of your own.

The name means “driver” as in WebDriver, the thing that drives an app for automation. It is not a data connector or an ODBC driver.

A short session

pbidriver launch "C:\reports\Sales.pbix"
pbidriver shot --page "Overview" --annotate
pbidriver read --page "Overview"
pbidriver slicer --visual "Region" --select "West" --shot
pbidriver dax "EVALUATE TOPN(5, Sales)"

shot --annotate saves a PNG of the canvas with each visual’s index drawn on it, so the agent can refer to “visual 18” in its next command. read returns chart points, card values, table cells and slicer state. Each call prints one JSON object, and any call that touches the UI also reports alerts, such as a dialog blocking the window.

What an agent can do with it

Verb What it covers
See Pixel-exact PNGs of the canvas, one visual, every visual, the whole UI, or the Table, Model, DAX query and TMDL views. Works when the canvas is larger than the window, when the window is minimized and when it sits behind others.
Read Chart data points, cards, tables and matrices (virtualized grids are scrolled through), slicer options and their selection, all formatted the way Power BI formats them.
Stay unblocked Blocking dialogs are detected on every call, then read, captured and answered with dialog --click. Input is refused while a modal is open. Broken visuals are reported.
Interact Real mouse and keyboard input: slicers, clicks, scrolling (sideways too, in wide tables), typing, tooltips, context and “More options” menus, bookmarks.
Understand Every page, visual, field, filter and bookmark from the report file, plus the model’s tables, columns, measures with their DAX, and relationships.
Measure Performance Analyzer timings per visual, split into DAX query, visual display and other, optionally with each visual’s query.
Close the loop Reload a PBIP after edits on disk, save, and close while answering the save prompt.

How it works

  • DevTools. Power BI Desktop draws its interface in WebView2, one Chromium page per view. launch starts an instance with a private WebView2 profile and a remote debugging port, which gives it its own browser process, so it works next to your other Power BI windows. pbidriver attaches with Playwright over the Chrome DevTools Protocol.
  • Pixel-exact captures. Only the target’s rectangle is captured, so panes and scrollbars never leak in. If the canvas does not fit the window, the viewport is emulated larger for the capture and then restored. A minimized window is restored without taking focus and put back exactly as it was.
  • Data. Built-in visuals bind each data point to its element along with tooltip info, so values come out exactly as Power BI shows them. Tables and matrices are read cell by cell through their ARIA grid roles.
  • Dialogs. Power BI uses three technologies. In-app dialogs are read from the DOM. Native WinForms dialogs are read from their child windows and clicked with BM_CLICK. Legacy Internet Explorer dialogs, such as the “save your changes?” prompt, are read and clicked through their own HTML via WM_HTML_GETOBJECT.
  • DAX. Windows PowerShell loads the ADOMD.NET client that ships inside Power BI Desktop and queries the local model engine. Nothing extra is installed.
  • Desktop Bridge. On Power BI Desktop from June 2026, Microsoft’s local JSON-RPC API provides page snapshots, reloads and unsaved state for any open window, including ones pbidriver did not launch.

From Node.js

The pbidriver npm package runs the same CLI from Node, for JavaScript projects and agents that reach for npx first:

npx pbidriver shot --page "Overview" --annotate

It finds the Python side on its own: an interpreter named in PBIDRIVER_PYTHON, else uvx (which downloads and caches the matching version on first use), else Python 3.9+ on the path, installing the matching version once with pip. Installer output goes to stderr, so stdout stays a single JSON object. There is a typed JavaScript API as well:

const { run } = require('pbidriver');

const shot = await run(['shot', '--page', 'Overview', '--annotate']);
if (shot.ok) console.log('PNG at', shot.file);

Power BI’s internals are reached through Windows APIs that Python handles well, so the npm package starts the Python CLI rather than reimplementing it. Both packages ship together from the same release, and a test checks that their version numbers match.

Drop-in instructions for agents

The README includes a block to paste into CLAUDE.md or AGENTS.md. It tells the agent how to start, look, read numbers, deal with alerts and dialogs, reload after editing PBIP files and finish cleanly. The documentation site has setup pages for Claude Code, GitHub Copilot, Codex and Cursor.

Limits, written down

  • The DOM selectors are Power BI internals. They are tested on Power BI Desktop 2.152 (March 2026) and 2.159 (November 2026). A monthly update can rename them, so they are grouped in one place.
  • Custom visuals render in sandboxed iframes. They can be captured and clicked, but their data cannot be read; use dax with the fields from inventory instead.
  • perf and bookmarks look for English ribbon labels.
  • launch opens a DevTools port on 127.0.0.1. While that instance runs, any program on the machine could drive it, including your signed-in Power BI session. Close it when you are done.

Questions

Can an AI agent see a Power BI Desktop report?
Yes, with pbidriver. pbidriver shot saves a pixel-exact PNG of a report page, one visual or every view, and pbidriver read returns the values behind the visuals as JSON. Neither needs the Power BI service or a screenshot of the whole desktop.
Does pbidriver need the Power BI service, a Pro licence or publishing?
No. It works entirely against Power BI Desktop on your own Windows machine. Nothing is uploaded or published.
Does it work with Claude Code, GitHub Copilot, Codex or Cursor?
Yes. It is a command-line tool that prints JSON, so any agent that can run shell commands can use it. The documentation has setup pages for each, and no MCP server or plugin is needed.
How is it different from Microsoft's Power BI Desktop Bridge?
The Desktop Bridge reports the open file, reloads PBIP projects and captures report pages. pbidriver uses it where it helps and adds reading visual data, slicers, clicks and menus, captures of the Table, Model, DAX query and TMDL views, dialog handling, DAX queries and Performance Analyzer timings. It also works on builds older than the Bridge.
Is there an npm package?
Yes. npx pbidriver runs the same CLI from Node.js through uv or Python 3.9+, and require('pbidriver').run([...]) resolves with each command's JSON result.
Does it work on macOS or Linux?
No. Power BI Desktop only runs on Windows, so pbidriver needs Windows 10 or 11.