pbir-cli

pbir を使用した Power BI レポートの操作

Power BI レポートを探索、作成、管理、書式設定するための CLI です。すべてのコマンドで pbir を使用します。

IMPORTANT: レポートの確認と変更には、必ず pbir CLI コマンドを使用してください。レポートの JSON ファイルを直接書き込み、置換、コピー、パッチ適用することは絶対にしないでください。CLI で必要な変更を行えない場合は、そこで作業を停止し、機能が不足していることを報告してください。ファイル編集で代替しないでください。pbir cat、pbir get、または読み取り専用の例を通じて JSON を読み取ることは許可されています。

IMPORTANT: 最初に MENTAL-MODEL.md を読み、その考え方に従ってください。

pbir が見つからない場合

uv tool install pbir-cli（または pip install pbir-cli）でインストールしてください。コマンドが完全に見つからない場合も含め、通常のケースでは常にこの方法を使用してください。

bin/fetch.sh は、自己完結型のポータブルビルドをダウンロードします。これを使用するのは、pbir がインストールされておらず、インストールもできない場合に限ってください。たとえば、PyPI にネットワークアクセスできない、Python がない、またはインストールが禁止されたロックダウン環境の場合です。ポータブルビルドは uv tool upgrade では更新されないため、通常のインストールが可能なのにこちらを優先すると、ユーザーが古い CLI を使い続けることになります。インストールに失敗した場合は、別の方法に切り替えるのではなく、インストールの問題を解決してください。

Fabric CLI を最新の状態に保つ

fabric-cli プラグインとともに Fabric に公開する場合（pbir publish）、公開時に互換性の問題が報告されたら、インストール済みの Fabric CLI（fab）を確認してください。アップグレードは必要な場合、または依頼された場合にのみ uv tool upgrade ms-fabric-cli で行い、ユーザーが指定したバージョンを尊重してください。

失敗から学ぶ

pbir CLI に関する学び（注意点、予期しない動作、ユーザーの期待、設計上の好み）を、プロジェクトのメモリファイルに記録してください。エージェントに応じて適切なパスを使用してください。

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

項目は簡潔で、一般化できる内容にしてください。メモリファイルは変更履歴ではありません。重複を削り、内容を繰り返すのではなく、参照資料や例へのリンクを記載してください。

pbir の使用方法

一般的なワークフロー

1. レポートを調べます。レポートは PBIR 形式である必要があります。形式は pbip、pbir-only、または PBIR メタデータを含む pbix です。pbir または pbip を優先してください。ユーザーが Power BI Desktop に言及する場合、またはレポートが Desktop で開かれていると言う場合は、必ず最初に pbir desktop list を実行してください。実行中の各インスタンスで開かれているファイルを対応付け（レポートのディスク上の場所を特定し）、編集を始める前にブリッジが動作することを確認できます。pbir desktop は Windows 専用です。macOS と Linux では使用しないでください（実行するたびに失敗します）。代わりに、pbir publish で Fabric のサンドボックスワークスペースにデプロイし、Chrome MCP ツールを使ってブラウザーでレンダリングされたレポートを確認してください。
2. モデルを特定します。レポートは通常、Power BI または Fabric のリモートモデルに接続された薄型レポートにする必要があります。
3. 意図を明確にします。曖昧な指示や自由度の高い指示の場合は、何かを変更する前に references/vague-prompts.md を参照し、AskUserQuestion を使って期待される内容とレポートのコンテキストを把握してください。
4. 変更を計画します。新しいレポート、ページ、またはビジュアルを作成する場合は、構築する前にワイヤーフレームまたはモックアップを作成し、ユーザーの承認を得てください。
5. 変更を加えます。references/、examples/ の関連ファイルや、pbi-report-design などの関連スキルを確認してください。
6. 検証します。変更を加えるコマンドは、書き込み内容を自動的に検証します。一貫性のある変更一式を加えた後、および完了前に、明示的に pbir validate を実行してください。反復作業中は対象を絞ったチェックを使い、最終確認では --all を使ってください。視覚的な確認には、レポートが Power BI Desktop で開かれている場合、ローカルでの手順を優先してください。pbir desktop refresh を実行してから pbir desktop screenshot を実行し、PNG を確認します（下記の「デスクトップ連携」を参照）。それ以外の場合は、サンドボックスワークスペースへの pbir publish の許可をユーザーに求め、Chrome MCP、devtools CLI、または Playwright でレンダリングを確認してください。
7. 反復します。複数回のやり取りを想定してください。曖昧なプロンプトに対して、1 回で完了することを求められた場合は、必要に応じて異議を唱えてください。
8. 学びを記録します。上記のメモリファイルに、簡潔で汎用性のある内容を記録してください。

ユーザーがレポートを手動で変更し、その変更を取り込むよう求めた場合や、差分から学ぶよう求めた場合は、references/manual-roundtrip-review.md に従ってください。

パス構文

pbir では、レポート、ページ、ビジュアルなどを指定する際にファイルシステムの形式を使用し、一括操作には glob 構文を使用します。

形式：ReportName.Report/PageName.Page/VisualName.Visual

• 型のサフィックス（.Report、.Page、.Visual）は必須です
• スペースを含むパスは引用符で囲みます："My Report.Report/Dashboard.Page"
• 一括操作には glob パターンを使用します："Report.Report/**/*.Visual"（set と rm には --force/-f が必要です）
  • *.Visual：現在のページにあるすべてのビジュアル
  • Page.Page/*.Visual：指定したページにあるすべてのビジュアル
  • **/*.Visual：すべてのページにあるすべてのビジュアル
  • **/card*.Visual：「card」で始まる名前のビジュアル
  • **/*.Report/**/*.Visual：すべてのレポートにあるすべてのビジュアル
• get または set とドット記法でプロパティを指定します："Report.Report/Page.Page/Visual.Visual.title.fontSize"
• フィルター／ブックマーク："Report.Report/filter:Name"、"Report.Report/bookmark:Name"
• 複数のレポートが一致する場合は、親フォルダーのプレフィックスを付けて区別します
• 絶対ファイルシステムパスも使用できます："C:\Reports\Sales.Report"、"C:\Reports\Flash.pbix"（glob と絶対パスは組み合わせられません）
• ワークスペースの保存先には .Workspace サフィックスを使用します："My Workspace.Workspace/Report.Report"

重要なルール

以下のすべてのルールに従ってください。

0. ユーザーに確認事項を尋ね、一度きりのプロンプトでの依頼には慎重に対応してください。 複数の手順を踏む反復的な進め方を優先してください。

1. 作業を始める前に参考資料を確認してください。 ユーザーの要件を理解するのに役立つ参考資料と例を特定してください。

2. レポートの JSON ファイルを直接編集しないでください。 必ず pbir CLI コマンドを使用してください。JSON やプロパティの確認には pbir cat または pbir get を使用し、専用コマンドで扱えないプロパティには pbir set を使用してください。

3. 設定する前に調べてください。 書式を設定する前に pbir schema describe <type> を実行してビジュアルタイプのオブジェクトを一覧表示し、続けて pbir schema describe <type> <object> を実行して、プロパティ名、型、範囲、列挙値を確認してください。プロパティ名を推測してはいけません。

4. テーマを優先して書式設定してください。 独自の書式設定を適用する前に pbir visuals format を確認してください。テーマですでにプロパティが設定されている場合があります。ある種類のすべてのビジュアルに適用する変更には、pbir theme set-formatting を優先してください。pbir visuals title/background/border は個別の上書きに限って使用してください。

5. 変更に応じた検証を行ってください。 変更系コマンドは書き込みを自動的に検証します。まとまりのある変更ごとに、また完了前に pbir validate "Report.Report" を実行してください。重なりやはみ出しの確認には --qa、モデルフィールドの確認には --fields、最終確認には --all を使用してください。

6. Desktop ブリッジを通じてレンダリングを確認してください。 Power BI Desktop でレポートを開いている場合、ユーザーから指示がない限り、変更のたびに pbir desktop refresh を実行してください。その後、pbir desktop screenshot を実行し、意味のある変更のたびに PNG を確認してください。検証ではレンダリング上の問題（重なり、切り詰め、誤ったフィールド、判読しにくい書式設定）を検出できません。変更が意図どおりにレンダリングされたことを証明できるのはスクリーンショットだけです。変更が多数ある場合は、作業を始める前に、ユーザーがキャンバス上で進捗を確認できるよう各手順の後に更新するか、最後に一度だけ更新するかを尋ねてください。ループを始める前に pbir desktop list でブリッジが利用可能かを一度確認してください。ブリッジが利用できない場合は、変更のたびに再試行しないでください（下記の「ブリッジが利用できない場合」を参照）。

7. すべての DAX 式でオブジェクトの参照方法を統一してください。 pbir model -q クエリ、レポートレベルのメジャー、ビジュアル計算では、列を 'Table'[Column]（テーブル名は必ず含め、引用符で囲みます）、メジャーをテーブル名なしの [Measure] として記述してください。-d "Role:Table.Field" と --field の Table.Field 形式は pbir のバインド構文であり、DAX ではありません。これらのフラグ内でのみ使用してください。

基本的なワークフロー

調査と分析

変更を加える前に、既存のレポートを把握してください。ビジュアルを追加またはサイズ変更する前に、必ずページの寸法と既存のビジュアルの位置を確認してください。 ページの寸法を把握せずに位置やサイズを設定すると、エラーが発生します。

pbir desktop list                                # FIRST if Desktop is mentioned: instances (PID, open file)
pbir ls                                          # Find all reports
pbir ls "Report.Report"                          # List pages/filters/theme
pbir tree "Report.Report" -v                     # Full structure with fields
pbir validate "Report.Report"                    # Health check
pbir get "Report.Report"                         # Report properties
pbir pages json "Report.Report/Page.Page"        # Check page width/height

より詳細な調査については、references/exploration.md を参照してください。

モデルの確認（フィールドをバインドする前に必須）

正しいテーブル名、列名、メジャー名を特定するために、必ず接続されているモデルをクエリしてください。フィールド名を推測してはいけません。

pbir model "Report.Report"                       # Connection info (workspace, model, thick/thin)
pbir model "Report.Report" -d                    # All tables, columns, measures
pbir model "Report.Report" -d -t Sales           # Filter to specific table
pbir model "Report.Report" -q "EVALUATE VALUES('Geography'[Region])"  # Check field values
pbir model "Report.Report" -q "EVALUATE ROW(\"Revenue\", [Total Revenue])"  # Test a measure
pbir fields list "Report.Report"                 # Fields already in use across report

レポートのモデル参照に応じて接続先が異なります。シンレポート（byConnection）では Power BI／Fabric サービスにクエリします。厚型レポート（byPath）では、レポートを開いている Power BI Desktop インスタンスのローカル Analysis Services エンジンにクエリします。そのため、-q と -d はライブモデルの状態を対象に、完全にオフラインで動作します。ローカルクエリには .NET Framework ADOMD クライアントが必要です（DAX Studio または Desktop のインストール先から自動検出されます。PBIR_ADOMD_DIR で上書きできます）。

モデルクエリの詳しいパターンとフィールドバインドのワークフローについては、references/fields-and-bindings.md を参照してください。

セマンティックモデルとレポートのワークフロー（te + pbir）

セマンティックモデルの変更には te を、レポートの変更には pbir を使用してください。モデル名の変更はモデル内の関連箇所にも反映されますが、レポートのバインドには古い Table.Field が残ることがあります。te deps --downstream を使用し、その後 pbir fields find/replace を実行して、両方のレイヤーを検証してください。デプロイ順序とワークフロー全体については、references/te-cli-tandem.md を参照してください。

デスクトップ統合（更新とスクリーンショット）

Windows の Power BI Desktop で PBIP/PBIR レポートを開いている場合、最短で表示を確認できるようブリッジを使用します。

pbir desktop list
pbir desktop refresh "Report.Report"
pbir desktop screenshot "Report.Report/Page.Page" -o verify.png

意味のある作業をひとまとまり進めるたびに、PNG を確認してください。PBIX はスクリーンショットに対応していますが、更新には対応していません。macOS/Linux はブリッジに対応していません。ブリッジを利用できない場合は、検証して、許可されたサンドボックスに発行し、サービス上の表示を確認してください。設定、複数インスタンスの動作、トラブルシューティングについては、references/desktop-integration.md を参照してください。

レポートの作成

新しいレポートには、次の項目が標準で含まれます。

• sqlbi テーマ（プロフェッショナルな色とタイポグラフィ）。ユーザーが別のテーマを希望しない限り、pbir theme apply-template は実行しないでください
• ページタイトル用の textbox ビジュアル（位置 (20,20)、高さ 90）を配置した既定の Page 1。新しい textbox は追加せず、既存のページ名を変更してください。タイトルの textbox と重ならないよう、以降のビジュアルは y:120 以下に配置してください。ユーザーが何もないキャンバスを希望する場合は、pbir new report で --no-title を指定すると、既定のタイトル textbox を省略できます

接続するには、--connection "Workspace/Model.SemanticModel" を渡すか、pbir connect で先にアクティブな接続を設定します（保存済みの接続を切り替えるには、必要に応じて pbir profile / pbir connect --profile <name> を使用します）。アクティブな接続が設定されている場合は、接続フラグを省略できます。

pbir new report "Sales.Report" -c "Workspace/Model.SemanticModel"
pbir pages rename "Sales.Report/Page 1.Page" --to "Overview" -f   # Rename default page (new name via --to)
pbir add visual card "Sales.Report/Overview.Page" --title "Revenue" -d "Values:Sales.Revenue" --y 120
pbir add filter Date Year -r "Sales.Report"
pbir validate "Sales.Report"

-d "Role:Table.Field" のデータロール名（例：Values、Category、Y、Series、Indicator）は、ビジュアルタイプの機能スキーマで定義されています。見慣れないビジュアルタイプのロールを確認するには、pbir add visual --list または pbir visuals bind --list-roles を実行してください。CLI はロール名の大文字と小文字を区別しないため、Values: と values: はどちらも使用できます。

手順を追った作成ガイドについては、create-pbi-report スキルを使用してください。

ビジュアルの追加と書式設定

書式設定の階層：基本テーマ -> カスタムテーマ -> ビジュアルタイプの既定値 -> 個別ビジュアルのオーバーライド。個別にビジュアルを書式設定する前に、必ずテーマレベルの書式設定を確認し、優先して使用してください。pbir visuals format を使用すると、適用元のラベル（default/wildcard/visualType/visual）付きで、すべての適用内容を確認できます。

# Add a visual with data binding (role names match the visual capability list)
pbir add visual card "Report.Report/Page.Page" --title "Total Sales" -d "Values:Sales.Revenue"

# ALWAYS check theme cascade first; see what formatting already applies
pbir visuals format "Report.Report/Page.Page/Visual.Visual"

# Set formatting in the THEME (preferred; applies to all visuals of this type)
pbir theme set-formatting "Report.Report" "card.*.border.radius" --value 8

# Only format bespoke if genuinely one-off
pbir visuals title "Report.Report/Page.Page/Visual.Visual" --text "Revenue" --fontSize 14 --show

# Bind more fields
pbir visuals bind "Report.Report/Page.Page/Visual.Visual" -a "Category:Products.ProductName"

# Validate after changes
pbir validate "Report.Report"

# If the report is open in Desktop, confirm the rendering
pbir desktop refresh "Report.Report"
pbir desktop screenshot "Report.Report/Page.Page" -o verify.png   # then Read verify.png

ビジュアルを一括作成する方法については、references/add-new-visual.md を参照してください。 書式設定のワークフローについては、references/format-visuals.md（テーマ優先のアプローチ、プロパティの確認、glob パターン）を参照してください。

レンダリング済みダッシュボードの高速ループ

レンダラーの影響を受ける反復作業、発行の頻度、新しいカードのセレクター、SVG テーブルの密度、最新データのみの折れ線ラベルについては、references/rendered-dashboard-loop.md を参照してください。

ビジュアルグループ

ビジュアルグループを使うと、複数のビジュアルをまとめて、同時に移動・拡大縮小できます。ビジュアルのセットをひとまとまりとして扱いたい場合（ヘッダーストリップ、KPI 行、グラフと注釈の組み合わせなど）に使用してください。

pbir visuals group "Report.Report/Page.Page" --list                       # List groups on page
pbir visuals group "Report.Report/Page.Page" --create "KPI Group"         # Create empty group
pbir visuals group "Report.Report/Page.Page/Group.Visual" --add "Card.Visual" --add "KPI.Visual"
pbir visuals group "Report.Report/Page.Page/Group.Visual" --remove "Card.Visual"
pbir visuals group "Report.Report/Page.Page/Visual.Visual" --ungroup      # Remove this visual from its group
pbir visuals group "Report.Report/Page.Page/Group.Visual" --ungroup       # Ungroup all members and delete the group

既定のモードは ScaleMode です。異なる動作が必要な場合は、--mode で上書きしてください。

スタイルプリセット

スタイルプリセットを使うと、厳選された書式設定のセットを一度に適用できます。ユーザーがすべてのプロパティを個別に指定せず、多くのビジュアルで一貫した見た目を希望する場合に使用してください。

pbir visuals preset --list                                        # Available presets
pbir visuals preset "Report.Report/Page.Page/Visual.Visual" --name minimal
pbir visuals preset "Report.Report/**/*.Visual" --name presentation

プリセットにはテーマが設定されています。ビジュアル全体の一貫性を保つには、pbir theme apply-template と組み合わせてください。

プロパティの確認（書式設定の前に必須）

各ビジュアルタイプには、数百のプロパティを持つオブジェクトが多数あります。値を設定する前に、スキーマ確認ワークフローを使って正しいオブジェクト名とプロパティ名を確認してください。プロパティ名を推測してはいけません。

# Step 1: What objects exist for this visual type? (objects + property counts)
pbir schema describe "lineChart"

# Step 2: What properties does an object have? (includes types, ranges, enums, descriptions)
pbir schema describe "lineChart" "lineStyles"

# Step 3: What's currently set on a live visual? (shows source: default/wildcard/visualType/visual)
pbir visuals format "Report.Report/Page.Page/Visual.Visual"
pbir visuals format "Report.Report/Page.Page/Visual.Visual" -v   # Include unset (None) properties
pbir visuals format "Report.Report/Page.Page/Visual.Visual" -p lineStyles  # Filter to object

# Step 4: Fuzzy search for a property by name
pbir visuals properties -s "marker"

組み込みビジュアルでは、有効なタイプ ID とタイプごとの objects 名の信頼できる一覧は、Microsoft のコアビジュアルカタログ（CLI に同梱され、固定されています）にあります。作成を始める前に、タイプ名やオブジェクト名が存在することを確認してください。

pbir schema types                       # Built-in visual + entity type ids (--vco for universal container objects, --selectors for selector objects)
pbir schema describe "barChart"         # Valid objects + their properties for one type
pbir schema roles "barChart"            # Data roles the type accepts (required? multiple? Column/Measure)
pbir schema describe "tableEx" --json   # Full JSON for agent consumption

pbir schema describe はこのコアカタログ（pbir set が適用する基準）を参照し、値の範囲や列挙値についてはテーマスキーマを追加します。カスタムビジュアルはカタログの対象外です。

スキーマの説明には、実用的な使用上の注意（例：目標線としてのエラーバー、メジャーに基づく動的な値をサポートする title.text）が含まれます。完全な説明を確認するには、--json 出力を使用してください。

すべてのビジュアルタイプについて、すべてのプロパティを網羅した完全なオフラインリファレンスは、references/property-catalogue.md を参照してください。これはスナップショットです。pbir schema types と pbir schema describe が信頼できる情報源です。

一括変更（グロブパターン）

# Set property on ALL visuals in report (glob requires -f)
pbir set "Report.Report/**/*.Visual.title.show" --value false -f

# Find all card visuals
pbir find "Report.Report/**/card*.Visual"

# Format all visuals on a page
pbir visuals title "Report.Report/Page.Page" --show --fontSize 12

条件付き一括操作（--where）

--where は、グロブ操作の対象となるビジュアルを絞り込みます。set とすべての visuals プロパティコマンドで使用できます。

pbir set "Report.Report/**/*.Visual.title.fontSize" --value 16 --where "visual_type=card" -f
pbir visuals legend "Report.Report/**/*.Visual" --show --where "width__gt=400"
pbir visuals resize "Report.Report/**/*.Visual" --width 350 --height 250 --where "visual_type=card"

述語演算子：=、__lt、__gt、__lte、__gte、__in=a|b|c、__contains、__icontains。カンマで結合できます（AND 条件）：--where "visual_type=card,width__gt=300"。演算子の完全な一覧は references/format-visuals.md を参照してください。

条件付き書式

# Find out what a container accepts before writing to it
pbir schema describe barChart.dataPoint          # "Conditional formatting:" line at the bottom

# Create CF (structural; use pbir visuals cf)
pbir visuals cf "Visual" --measure "labels.color _Fmt.StatusColor"
pbir visuals cf "Visual" --gradient --field "Table.Field" --min-color bad --max-color good
pbir visuals cf "Visual" --data-bars --field "Table.Field"
pbir visuals cf "Visual" --image --field "_SVG.Bullet"          # measure-driven image or SVG

# Read / edit / remove CF (dot-path; use pbir set / pbir get)
pbir get "Visual.dataPoint.fill.cf"                             # summary
pbir set "Visual.dataPoint.fill.cf.gradient.min.color" --value "bad"
pbir set "Visual.dataPoint.fill.cf" --remove                    # or --clear
pbir get "Report.Report/**/*.Visual.**.cf"                       # bulk read

条件付き書式はデータポイントの色だけにとどまりません。タイトル、サブタイトル、枠線、ツールチップ、軸の境界値、基準線の値、データラベルのテキスト、エラーバーのスタイルにもメジャーを指定できます。各コンテナーについて信頼できる情報を確認するには pbir schema describe <type>.<container> を実行してください。そこでアスタリスクが付いたプロパティは、カタログから推測したものではなく、レンダリング済みレポートで確認されています。

書式を決めるフィールドと書式を適用するフィールドが異なる場合（ヘルパーメジャーで色付けするグリッド列、コンボチャートの第 2 系列など）、--target-field で対象を指定してください。指定しないと、設定がドライバーのフィールドに適用され、Desktop では誤った列に表示されます。

pbir visuals cf "Grid.Visual" --rules --field "Sales.Margin %" --rule "lt 0 bad" \
  --on values.backColor --target-field "Sales.Revenue"

グラデーション／ルール／アイコン／データバー／画像のオプション、コピー／削除／変換、ベストプラクティスについては、references/conditional-formatting.md を参照してください。

ビジュアルのアクション、ブックマーク、ドリルスルー

pbir visuals action "Visual" --type PageNavigation --target "Details"  # Set action
pbir add bookmark "Report.Report" "Q1 View"                           # Create bookmark
pbir bookmarks page "Report.Report" "Q1 View" "Details"               # Set bookmark target page
pbir pages drillthrough "Report.Report/Details.Page" --table T --field F # Add drillthrough
pbir pages set-tooltip "Report.Report/Tooltip.Page"                   # Configure tooltip

ブックマークの管理については、references/bookmarks.md を参照してください。

フィルター

pbir add filter Table Field -r "Report.Report"                        # Categorical
pbir add filter T F -r "R.Report" --type TopN --n 10 --by-table T2 --by-field F2  # TopN
pbir add filter T F -r "R.Report" --type Advanced --operator GreaterThan --values 1000
pbir add filter Date Date -r "R.Report" --type RelativeDate --period Last30Days

フィルターの作成時には、接続されたセマンティックモデルに対してフィールドが検証されます。検証で解決できない場合（接続がない、モデルに到達できないなど）、未検証のフィルターを作成せず、コマンドはエラーになります。ユーザーが明示的に検証を回避する必要がある場合に限り、--no-validate を使用してください。

フィルターの種類を変更するには、いったん削除してから作成し直してください。フィルターの完全なリファレンスは、references/filters.md を参照してください。

レポートの監査

pbir validate "Report.Report"                       # Structure, schema, fields, QA (use --all)
pbir bpa run "Report.Report"                        # Best Practice Analyzer rule sweep
pbir bpa run "Report.Report" --fix --save           # Apply safe automatic fixes
pbir tree "Report.Report" -v                        # Structure + field bindings
pbir theme colors "Report.Report"                   # Palette and usage
pbir color list "Report.Report"                     # Every hard-coded color literal and where it is used
pbir fields list "Report.Report"                    # Fields in use
pbir dax measures list "Report.Report"              # Extension measures
pbir filters list "Report.Report"                   # Filters at every scope

BPA ルールは pbir bpa rules list/ignore/unignore で管理します。無視したルールはレポートごとに適用されます。包括的な監査チェックリストについては、references/audit-report.md を参照してください。

コマンドリファレンス

コマンドリファレンスの全容は references/cli-reference.md にあります。使い慣れていないコマンドを実行する前に、必ず pbir <command> --help を実行してください。フラグ名とデフォルト値はヘルプの内容が正式な情報です。

コマンドグループの概要：

Getting started:     config (show, init, set, paths), connect (+ --profile), profile, new
Browse and query:    ls (+ --tree), find, get, cat, model     # `tree` is an alias of `ls --tree`
Modify:              set, add, mv, cp, rm, visuals, pages
Data:                fields, filters, dax, bookmarks, annotations
Theme and style:     theme (colors, fonts, set-colors, set-fonts, set-formatting, apply-template), color (list, replace), fonts (list, replace, clear, available)
Schema discovery:    schema (= capabilities) (types, describe, roles, status, upgrade), visuals properties, visuals format
Workflow ops:        validate, backup, restore, publish, download, batch, open, bpa, usage
Desktop (Windows):   desktop (list/status, refresh/reload, screenshot)

分かりにくいグループについての補足：

• connect / profile：pbir connect "Report.Report" はアクティブなコンテキストを設定し、以降のコマンドではレポートのパスを省略できるようにします。pbir profile は名前付きの接続を保存して切り替えます（pbir connect --profile dev）。
• visuals group：ビジュアルグループを使うと、複数のビジュアルをまとめて拡大縮小したり、配置したりできます。以下の「ビジュアルグループ」ワークフローを参照してください。
• visuals preset：名前付きのスタイルプリセット（minimal、bold、clean、emphasis、presentation）を使うと、厳選された書式設定を一度に適用できます。
• bpa：Best Practice Analyzer です。pbir bpa run "Report.Report" はルール違反を報告し、--fix --save は安全な修正を適用します。pbir bpa rules list/ignore/unignore でルールセットを管理します。
• color：pbir color list は、ハードコードされた色リテラルとその使用箇所をすべて列挙します。pbir color replace --from <hex> --to <hex> は、レポート全体で色を置き換えます（--theme／--report で対象範囲を指定します）。インラインの色リテラルではなく、テーマ JSON を編集する theme グループとは異なります。
• fonts：color に相当するタイポグラフィ機能です。pbir fonts list は、レポートとテーマ全体のフォントファミリー／サイズ／太さを監査します。pbir fonts replace --from --to は、フォントファミリーをすべての箇所で置き換えます。pbir fonts clear はビジュアルごとのフォント／書式設定のオーバーライドを削除し、テーマのデフォルトを適用します。テーマ自体のフォントを設定するには、pbir theme set-fonts を使用してください。
• batch：pbir batch は、グロブで指定した対象に対して、複数のステップを含むレビュー済みの JSON 仕様（version: 2）を実行します。plan は plan_digest を出力し、run --plan-digest は計画に差異がある場合、実行を拒否します。繰り返し可能で監査可能な一括編集に使用してください。references/cli-reference.md の「バッチ自動化」セクションを参照してください。
• config paths：この OS で、設定、認証状態、テンプレート、バックアップ、キャッシュが保存される場所を出力します。0.9.30 以降、ストレージにはプラットフォーム標準の場所が使われるため、~/.pbir/ に保存されると決めつけないでください。
• usage：pbir usage "Report.Report"（またはワークスペース／公開済みレポート）は、az login トークンを使用して、Power BI サービスからビュー数、閲覧者数、ページ数、読み込み時間を取得します。--model を指定すると、より詳細な情報を得られるワークスペース使用状況メトリックモデルが追加されます（Contributor 以上が必要で、非表示のモデルが生成されます）。文書化されていないサービスのテレメトリに依存します。

グローバルフラグ

トップレベルのフラグはサブコマンドより前に指定します。例：pbir -q new report ...。pbir new report -q ... ではありません。

-q / --quiet: suppress animations, tips, spinners (agent-friendly)
--output-format text|json: structured stdout for commands that support it
--error-format text|json: structured stderr where supported
--debug: enable tracebacks and timing
--rawdog: skip EVERY validation check (umbrella for --skip all)
--skip <category>: skip validation categories (repeatable, comma-separated): structure, schema, schema-version, fields, enums, qa, roles, layout, theme

pbir は変更時に暗黙的に検証を行います。--skip／--rawdog を指定すると、たとえばモデルにまだ存在しないフィールドを使ったビジュアルを作成するために pbir --skip fields set ... を実行するなど、意図的なケースに限って検証を緩和できます。これらはグローバルフラグなので、サブコマンドより前に指定してください。根本的な問題を解決することを優先し、--rawdog の使用は避けてください。

--json や -F json などのコマンド固有の出力フラグや、-f/--force などの変更フラグは、該当するサブコマンドの後に指定します。pbir <command> --help で確認してください。これらはグローバルフラグではありません。

よくある間違い

• ロール名は大文字と小文字を区別しませんが、機能の一覧にある名前を使用する必要があります。 pbir add visual --list または pbir visuals bind --list-roles を使って、対象のビジュアルタイプのロール識別子（例：Values、Category、Y、Series）を確認してください。
• pbir cat はフィルターやブックマークに対応していません。 代わりに pbir filters list --json または pbir bookmarks json を使用してください。
• pbir publish は位置引数を使用し、--workspace は使用しません。 正しい例：pbir publish "Report.Report" "Workspace.Workspace/Report.Report" -f。
• pbir filters list に -v フラグはありません。 詳細な出力には --json を使用してください。
• PBIX に変換してから PBIR フォルダーを公開しないでください。 PBIX に変換する場合は、.pbix ファイルを直接公開してください。PBIR を公開する場合は、変換を完全に省略してください。
• pbir pages rename が名前を変更するのはフォルダーだけです。ページ ID や表示名は変更しません。単一のページフォルダー名を変更するには --to を使用してください。
• DMV クエリはサービス接続モデルに対して実行できません。 シンレポート（byConnection）では、pbir model -q が実行するのは EVALUATE DAX のみです。INFO.TABLES() などの DMV はサービスから 400 を返し、スキーマは TMDL から取得されます。スキーマを調べるには pbir model -d を使用してください。シックレポート（byPath）は Desktop で開くと、代わりにローカルエンジンに対してクエリを実行し、実際のスキーマが使用されます。
• pbir desktop refresh は PBIX ファイルでは動作しません。 Desktop がディスクから再読み込みするのは PBIP/PBIR 定義のみです。PBIX インスタンスで対応しているのは pbir desktop screenshot だけです。
• 使い慣れていないコマンドを使用する前に、必ず pbir <command> --help を実行してください。正確な構文を確認できます。
• 書き込みが有効でも、レンダラーに反映されないことがあります。 モダンビジュアルではインスタンスセレクターが使用されます。現在の pbir では、既知のオブジェクトが正しく処理されるため、プレーンパスを優先してください。古いビルドで値が読み込まれても Power BI に無視される場合は、pbir cat と比較し、.id(default). を明示的に使用してください。
• ネイティブテーブルの値には、垂直方向の配置プロパティがありません。 values.verticalAlignment を作らないでください。画像の高さや行のパディングを減らすには pbir visuals table-density を使用するか、アクセシビリティと保守性のトレードオフが許容できる場合に限り、影響を受けるすべてのセルを SVG にしてください。

ユーザーとのやり取り

ビジュアルの表現、フィールドのマッピング、テーマとローカル設定の適用範囲、または Deneb とコア機能のどちらを使うかに影響する選択肢は、明確にしてください。元に戻せない visuals clear-formatting を実行する前に確認し、複数バッチの作業では更新や公開の頻度について合意してください。意図が本当に不明確な場合は references/vague-prompts.md を使用してください。

検証

変更を加えるコマンドは、書き込み内容を自動で検証します。まとまった変更を加えた後、完了前に pbir validate "Report.Report" を実行してください。これにより、細かなコマンドを実行するたびにレポート全体を再スキャンすることなく、壊れたフィールド参照、無効な JSON、スキーマ違反、構造上の問題を検出できます。

(no flags): structure + schema validation
--fields: also validate fields exist in model with correct types (Column/Measure)
--qa: also run quality-assurance rules (overlap/overflow, hidden visuals, visual filters, field counts, layout and role-cardinality heuristics)
--semantic: also check visual type ids + objects/visualContainerObjects names against the core visual catalog
--all: structure + schema + fields + QA + semantic
--strict: every non-advisory warning becomes a failure (core-catalog advisories stay warnings)
--json / --tree: output format
--allow-download-schemas: download missing schemas on the fly

変更時には、同じチェックが暗黙的に実行されます。特定のカテゴリを意図的に省略するには、サブコマンドの前にグローバルフラグを指定します。--skip <category>（structure, schema, schema-version, fields, enums, qa, roles, layout, theme。繰り返し指定でき、カンマ区切りです）または --rawdog（すべて省略）を使用します。省略するよりも、原因を修正することを優先してください。

--semantic は、CLI に同梱され、固定されたコアのビジュアルカタログを利用します。認識できない visualType、objects、visualContainerObjects の名前を参考情報として警告します（未掲載のプロパティについては情報レベルです）。--strict を指定すると、これらの参考情報は警告のままにし、それ以外のすべての問題で失敗します。NaN または Infinity を含むファイルは、無効な JSON として拒否されます。メジャーのみの棒グラフと縦棒グラフは有効で、描画不能として報告されなくなりました。カタログはプレビュー版で、製品の更新に追いついていない場合があるため、未知でも妥当と思われる名前やカスタムビジュアルが有効なこともあります。セマンティックチェックの結果は、手早い作成時の確認として扱い、必須の合格基準とはしないでください。

スキーマバージョンエラー：pbir schema fetch --yes を実行してから、pbir schema upgrade "Report.Report" を実行して修正してください。

pbir validate が検証するのは構造であり、描画結果ではありません。Power BI Desktop でレポートを開いている場合は、検証のたびにブリッジループに従ってください。pbir desktop refresh、pbir desktop screenshot の順に実行し、その後 PNG を確認します。描画結果を確認せずに、変更が完了したと報告しないでください。

参照ファイル

references/cli-reference.md: full syntax for any command with all flags
references/exploration.md: exploring an unfamiliar report systematically
references/desktop-integration.md: driving Power BI Desktop; canvas refresh, page screenshots, auto-refresh, local model queries, troubleshooting
references/manual-roundtrip-review.md: safe pull-down and semantic comparison of user edits; New Card and table-width lessons
references/rendered-dashboard-loop.md: short validate/query/render batches; publish cadence and renderer-sensitive patterns
references/create-new-report.md: building a report from scratch
references/layout.md: choosing a visual type for the question, then sizing and placing it on the canvas
references/add-new-visual.md: adding visuals, layout patterns, bulk creation
references/add-image.md: registering image resources, page and visual backgrounds, image visuals
references/visual-groups.md: visual groups (create, add/remove members, ungroup)
references/visual-presets.md: style presets (minimal, bold, clean, emphasis, presentation)
references/fields-and-bindings.md: field binding, Column vs Measure types, swapping fields, rebinding
references/te-cli-tandem.md: coordinated semantic-model and report changes with te + pbir; renames, moves, additions, removals, validation order
references/format-visuals.md: formatting workflow, property discovery, glob patterns, --where predicates
references/conditional-formatting.md: CF types, measure-based CF, copy/remove/update/convert
references/reference-lines.md: reference-line entries on chart axes; pbir visuals reference-line and styling via pbir set
references/error-bars.md: error bars and bullet markers on chart visuals; pbir visuals error-bars and styling via pbir set
references/modifying-theme.md: theme inspection, colors, text classes, fonts
references/apply-theme.md: applying/copying/saving theme templates
references/converting-reports.md: format conversion, thick/thin split, merge, rebind
references/thin-report-measures.md: extension measures for CF, conditional rendering
references/visual-calculations.md: visual calculations (RUNNINGSUM, RANK, etc.)
references/filters.md: filter types (Categorical, TopN, Advanced, RelativeDate), management, pane styling
references/bookmarks.md: bookmark management, copying, button references
references/audit-report.md: report quality audit checklist
references/bpa.md: Best Practice Analyzer; running rules, applying safe fixes, managing the rule set
references/vague-prompts.md: handling underspecified prompts; targeted questions, sensible defaults
references/property-catalogue.md: offline property snapshot; universal containers and discovery commands
references/visualTypes/*.md: per-visual-type design rules, CLI commands, and best practices
examples/visuals/default/*.json: read-only examples of minimal visual structures with theme defaults
examples/visuals/formatted/*.json: read-only examples of formatting, CF, filters, and advanced patterns; reproduce them with CLI commands, never by copying JSON into a report

関連スキル

• pbi-report-design：レポートのデザインに関するベストプラクティスとガイドラインを確認します
• pbip-format：PBIP の構造を理解するために使用します。pbir によるレポート変更を回避する目的では使用しないでください
• create-pbi-report：新しいレポートを作成する手順を確認します