用途：pbir-cli 是操作 Power BI 报表的命令行工具，用于探索、构建、管理、格式化 .pbir、.pbip 或 .pbix 报表。重要原则是始终使用 pbir CLI 命令检查和修改报表，绝不直接写入、替换、复制或修补报表 JSON 文件；若某变更未被 CLI 暴露，应停止并报告缺失能力，不得退回到文件编辑。通过 pbir cat、pbir get 只读读取 JSON 是允许的。
安装：pbir 缺失时用 uv tool install pbir-cli 或 pip install pbir-cli 安装。bin/fetch.sh 仅用于无法正常安装（无 PyPI 网络、无 Python 或禁止安装）时的便携构建，便携构建不会随 uv tool upgrade 更新。
主要用法：报表路径采用文件系统式语法，如 ReportName.Report/PageName.Page/VisualName.Visual，类型后缀必填，含空格路径需加引号，批量操作用 glob。属性通过 get/set 加点号访问。常用命令包括 pbir ls、pbir tree、pbir validate、pbir get、pbir pages json、pbir add visual、pbir visuals bind、pbir theme set-formatting、pbir visuals preset、pbir schema describe、pbir model 等。首次使用应遵守 MENTAL-MODEL.md 的心智模型。
工作流：先探索报表，确认模型（通常为连接远程模型的瘦报表），澄清意图，规划变更，执行变更，随后验证。修改命令会自行验证写入，完成一批变更及最终完成前运行 pbir validate，迭代时用更窄检查，最终用 --all。
桌面集成：Windows 上报表在 Power BI Desktop 打开时，可先用 pbir desktop list，随后 pbir desktop refresh 与 pbir desktop screenshot 获取 PNG 检查渲染。pbir desktop 仅限 Windows；macOS/Linux 无法使用，需发布到沙盒工作区并在浏览器中检查渲染。
限制：不直接编辑报表 JSON；设置属性前先用 pbir schema describe 发现对象与属性，不猜测属性名；优先主题级格式化；模型字段名不应猜测。其他费用、平台细节暂未提供。