跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

pbir-cli

This skill should be used whenever the user mentions "pbir", "pbir-cli", "Power BI reports", or "PBI reports", works with .pbir, .pbip, or .pbix files, or wants to refresh, screenshot, or visually verify a report that is open in Power BI Desktop. Covers creating, exploring, formatting, validating, and publishing Power BI reports through the pbir CLI and object model, plus driving Power BI Desktop (canvas reload, page screenshots) and querying connected or local semantic models.

data-goblin · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add data-goblin/power-bi-agentic-development --skill pbir-cli

技能说明


name: pbir-cli description: This skill should be used whenever the user mentions "pbir", "pbir-cli", "Power BI reports", or "PBI reports", works with .pbir, .pbip, or .pbix files, or wants to refresh, screenshot, or visually verify a report that is open in Power BI Desktop. Covers creating, exploring, formatting, validating, and publishing Power BI reports through the pbir CLI and object model, plus driving Power BI Desktop (canvas reload, page screenshots) and querying connected or local semantic models.

Working with Power BI reports using pbir

CLI for exploring, building, managing, formatting Power BI reports. All commands use pbir.

IMPORTANT: ALWAYS use pbir CLI commands to inspect and modify reports. NEVER write, replace, copy, or patch report JSON files directly. If the CLI does not expose a required mutation, stop and report the missing capability; do not fall back to file editing. Reading JSON through pbir cat, pbir get, or read-only examples is allowed.

IMPORTANT: FIRST Read and adhere to the mental model in MENTAL-MODEL.md.

When pbir is missing

Install it with uv tool install pbir-cli (or pip install pbir-cli). That is the route to use in every ordinary case, including when the command is missing entirely.

bin/fetch.sh downloads a self-contained portable build instead. Reach for it only when pbir is not installed and installing it is not possible: no network access to PyPI, no Python, or a locked-down machine that forbids installs. A portable build does not update with uv tool upgrade, so preferring it when a normal install would have worked leaves the user on a stale CLI. If an install failed, fix the install rather than routing around it.

Keeping the Fabric CLI current

When publishing to Fabric (pbir publish) alongside the fabric-cli plugin, check the installed Fabric CLI (fab) if publishing reports a compatibility problem. Upgrade with uv tool upgrade ms-fabric-cli only when required or requested, and honor any user-pinned version.

Learning from Mistakes

Log learnings about the pbir CLI in the project's memory file: gotchas, unexpected behavior, user expectations, and design preferences. Use the agent-appropriate path:

  • Claude Code: .claude/rules/pbir-cli.md
  • Cursor: .cursor/rules/pbir-cli.mdc
  • GitHub Copilot: .github/instructions/pbir-cli.instructions.md

Keep entries concise and generalizable. The memory file is not a change log. Prune redundancy, link out to references and examples rather than restating them.

How to use pbir

General workflow

  1. Explore the report. The report must be in PBIR format: pbip, pbir-only, or pbix-with-PBIR-metadata. Prefer pbir or pbip. Whenever the user mentions Power BI Desktop or says the report is open in Desktop, run pbir desktop list FIRST: it maps each running instance to the file it has open (locating the report on disk) and confirms the bridge works before any edits begin. pbir desktop is Windows-only; on macOS and Linux do not use it (every invocation fails). Instead deploy with pbir publish to a sandbox workspace in Fabric and verify the rendered report in the browser via the Chrome MCP tools.
  2. Identify the model. Reports generally should be thin reports connected to a remote model in Power BI or Fabric.
  3. Clarify intent. For vague or open-ended instructions, consult references/vague-prompts.md and use AskUserQuestion to understand expectations and report context before mutating anything.
  4. Plan changes. For new reports, pages, or visuals, draft a wireframe or mock-up for the user to approve before building.
  5. Make changes. Reach for relevant files in references/, examples/, and related skills like pbi-report-design.
  6. Validate. Mutating commands validate their own writes. Run explicit pbir validate after a coherent batch of changes and before completion; use narrower checks while iterating and --all for the final confidence pass. For visual confirmation, prefer the local loop when the report is open in Power BI Desktop: pbir desktop refresh then pbir desktop screenshot and inspect the PNG (see "Desktop Integration" below). Otherwise ask permission to publish to a sandbox workspace with pbir publish and inspect rendering via Chrome MCP, devtools CLI, or Playwright.
  7. Iterate. Expect multiple rounds. Push back on one-shot expectations from vague prompts.
  8. Record learnings. Add concise, generalizable entries to the memory file noted above.

Path syntax

pbir uses a filesystem paradigm for identifying reports, pages, visuals etc. and glob syntax for bulk operations.

Format: ReportName.Report/PageName.Page/VisualName.Visual

  • Type suffixes (.Report, .Page, .Visual) are required
  • Quote paths with spaces: "My Report.Report/Dashboard.Page"
  • Use glob patterns for bulk operations: "Report.Report/**/*.Visual" (requires --force/-f for set and rm)
    • *.Visual; all visuals on current page
    • Page.Page/*.Visual; all visuals on a specific page
    • **/*.Visual; all visuals across all pages
    • **/card*.Visual; visuals whose name starts with "card"
    • **/*.Report/**/*.Visual; all visuals across all reports
  • Properties via get or set and dot notation: "Report.Report/Page.Page/Visual.Visual.title.fontSize"
  • Filters/bookmarks: "Report.Report/filter:Name", "Report.Report/bookmark:Name"
  • If multiple reports match, disambiguate with parent folder prefix
  • Absolute filesystem paths work too: "C:\Reports\Sales.Report", "C:\Reports\Flash.pbix" (globs do not combine with absolute paths)
  • Workspace destinations use .Workspace suffix: "My Workspace.Workspace/Report.Report"

Critical Rules

Follow all rules below.

  1. ASK user for clarifications and push back on one-shot prompt requests. Pursue an iterative multi-step way-of-working

  2. CHECK references before starting work. Identify relevant [references](references/

阅读完整来源 ↗