/power-bi-visuals

name: Power BI Visuals
description: >
  Add, configure, bind data to, and bulk-manage visuals on Power BI PBIR report
  pages using pbi-cli. Invoke this skill whenever the user mentions "add a chart",
  "bar chart", "line chart", "card", "KPI", "gauge", "scatter", "table visual",
  "matrix", "slicer", "combo chart", "bind data", "visual type", "visual layout",
  "resize visuals", "bulk update visuals", "bulk delete", "visual calculations",
  or wants to place, move, bind, or remove any visual on a report page. Also invoke
  when the user asks what visual types are supported or how to connect a visual to
  their data model.
tools: pbi-cli

Power BI Visuals Skill

Create and manage visuals on PBIR report pages. No Power BI Desktop connection is needed -- these commands operate directly on JSON files.

Adding Visuals

# Add by alias (pbi-cli resolves to the PBIR type)
pbi visual add --page page_abc123 --type bar
pbi visual add --page page_abc123 --type card --name "Revenue Card"

# Custom position and size (pixels)
pbi visual add --page page_abc123 --type scatter \
    --x 50 --y 400 --width 600 --height 350

# Named visual for easy reference
pbi visual add --page page_abc123 --type combo --name sales_combo

Each visual is created as a folder with a `visual.json` file inside the page's `visuals/` directory. The template includes the correct schema URL and queryState roles for the chosen type.

Prerequisite: Measures Must Exist in the Semantic Model

`visual bind` writes field references into the visual JSON. It does **not** create measures — it only records that a measure should exist. If the measure is missing from the TMDL, every visual bound to it will show an error in Desktop.

**Before binding any visual to a measure, verify the measure exists:**

# Option A: create it via pbi-cli (requires pbi connect)
pbi connect
pbi measure create "Total Revenue" -e "SUM(Fact_Sales[Total_Revenue])" -t Fact_Sales

# Option B: check existing measures in the TMDL file directly
# Look for `measure '...' =` lines in SemanticModel/definition/tables/*.tmdl

**After adding measures directly to a TMDL file** (without `pbi connect`): close and reopen the `.pbip` file in Power BI Desktop. Desktop only reads TMDL on file open — it does not hot-reload TMDL changes made on disk.

**Checklist before opening Desktop:**

• Every `--field`, `--value`, `--indicator` reference points to a real measure or column in the TMDL
• Table names match exactly (case-sensitive in PBIR): `"Fact_Sales"` ≠ `"fact_sales"`
• Measure names match exactly: `"Total Revenue"` ≠ `"Total_Revenue"`

Binding Data

Visuals start empty. Use `visual bind` with `Table[Column]` notation to connect them to your semantic model. The bind options vary by visual type -- see the type table below.

# Bar chart: category axis + value
pbi visual bind mybar --page p1 \
    --category "Geography[Region]" --value "Sales[Revenue]"

# Card: single field
pbi visual bind mycard --page p1 --field "Sales[Total Revenue]"

# Matrix: rows + values + optional column
pbi visual bind mymatrix --page p1 \
    --row "Product[Category]" --value "Sales[Amount]" --value "Sales[Quantity]"

# Scatter: X, Y, detail, optional size and legend
pbi visual bind myscatter --page p1 \
    --x "Sales[Quantity]" --y "Sales[Revenue]" --detail "Product[Name]"

# Combo chart: category + column series + line series
pbi visual bind mycombo --page p1 \
    --category "Calendar[Month]" --column "Sales[Revenue]" --line "Sales[Margin]"

# KPI: indicator + goal + trend axis
pbi visual bind mykpi --page p1 \
    --indicator "Sales[Revenue]" --goal "Sales[Target]" --trend "Calendar[Date]"

# Gauge: value + max/target
pbi visual bind mygauge --page p1 \
    --value "Sales[Revenue]" --max "Sales[Target]"

Binding uses ROLE_ALIASES to translate friendly names like `--value` into the PBIR role name (e.g. `Y`, `Values`, `Data`). Each field is written as a Column or a Measure reference based on what it actually is in the semantic model, checked in this order:

1. The report's own semantic model on disk (`definition.pbir` -> `byPath` -> `tables/*.tmdl` or `model.bim`) 2. The live model from `pbi connect`, only for fields not found on disk 3. A role default: slicers and table `--column` bind Columns; value, indicator and goal roles bind Measures; category, row and legend bind Columns

The JSON output reports `kind` and `resolved_by` per field, plus a `warnings` entry when a field is missing from the model (usually a typo). Force the wrapper for every field in one call with `--kind column` or `--kind measure`.

Columns bound to a value role get the implicit aggregation Desktop would apply, taken from the column's `summarizeBy` (Sum for numeric columns by default). Text columns count on charts and matrices and stay as plain columns in tables and cards. Category, row, legend and slicer fields are never aggregated. Override with `--aggregation`:

# Average price per region instead of the model's default Sum
pbi visual bind mybar --page p1 \
    --category "Geography[Region]" --value "Sales[Price]" --aggregation average

# Slicer on a dimension column (written as Column)
pbi visual bind myslicer --page p1 --field "Geography[Region]"

# Table mixing columns and measures (each resolved from the model)
pbi visual bind mytable --page p1     --column "Geography[Region]" --column "Product[Name]" --value "Sales[Revenue]"

Inspecting and Updating

# List all visuals on a page
pbi visual list --page page_abc123

# Get full details of one visual
pbi visual get visual_def456 --page page_abc123

# Move, resize, or toggle visibility
pbi visual update vis1 --page p1 --width 600 --height 400
pbi visual update vis1 --page p1 --x 100 --y 200
pbi visual update vis1 --page p1 --hidden
pbi visual update vis1 --page p1 --visible

# Delete a visual
pbi visual delete visual_def456 --page page_abc123

Container Properties

Set border, b