julianobarbosa/power-bi-pages

Power BI Pages Skill

Manage pages in PBIR reports. Pages are folders inside definition/pages/ containing a page.json file and a visuals/ directory. No Power BI Desktop connection is needed.

Listing and Inspecting Pages

# List all pages with display names, order, and visibility
pbi report list-pages

# Get full details of a specific page
pbi report get-page page_abc123

get-page returns:

• name, display_name, ordinal (sort order)
• width, height (canvas size in pixels)
• display_option (e.g. "FitToPage")
• visual_count -- how many visuals on the page
• is_hidden -- whether the page is hidden in the navigation pane
• page_type -- "Default" or "Drillthrough"
• filter_config -- page-level filter configuration (if any)
• visual_interactions -- custom visual interaction rules (if any)
• page_binding -- drillthrough parameter definition (if drillthrough page)

Adding Pages

# Add with display name (folder name auto-generated)
pbi report add-page --display-name "Executive Overview"

# Custom folder name and canvas size
pbi report add-page --display-name "Details" --name detail_page \
    --width 1920 --height 1080

Default canvas size is 1280x720 (standard 16:9). Common alternatives:

• 1920x1080 -- Full HD
• 1280x960 -- 4:3
• Custom dimensions for mobile or dashboard layouts

Deleting Pages

# Delete a page and all its visuals
pbi report delete-page page_abc123

This removes the entire page folder including all visual subdirectories.

Page Background

# Set a solid background colour
pbi report set-background page_abc123 --color "#F5F5F5"

Page Visibility

Control whether a page appears in the report navigation pane:

# Hide a page (useful for drillthrough or tooltip pages)
pbi report set-visibility page_abc123 --hidden

# Show a hidden page
pbi report set-visibility page_abc123 --visible

Bookmarks

Bookmarks capture page-level state (filters, visibility, scroll position). They live in definition/bookmarks/:

# List all bookmarks in the report
pbi bookmarks list

# Get details of a specific bookmark
pbi bookmarks get "My Bookmark"

# Add a new bookmark
pbi bookmarks add "Executive View"

# Delete a bookmark
pbi bookmarks delete "Old Bookmark"

# Toggle bookmark visibility
pbi bookmarks set-visibility "Draft View" --hidden

Drillthrough Pages

Drillthrough pages have a pageBinding field in page.json that defines the drillthrough parameter. When you call get-page on a drillthrough page, the page_binding field returns the full binding definition including parameter name, bound filter, and field expression. Regular pages return null.

To create a drillthrough page, add a page and then configure it as drillthrough in Power BI Desktop (PBIR drillthrough configuration is not yet supported via CLI -- the CLI can read and report on drillthrough configuration).

Workflow: Set Up Report Pages

# 1. Add pages in order
pbi report add-page --display-name "Overview" --name overview
pbi report add-page --display-name "Sales Detail" --name sales_detail
pbi report add-page --display-name "Regional Drillthrough" --name region_drill

# 2. Hide the drillthrough page from navigation
pbi report set-visibility region_drill --hidden

# 3. Set backgrounds
pbi report set-background overview --color "#FAFAFA"

# 4. Verify the setup
pbi report list-pages

Path Resolution

Page commands inherit the report path from the parent pbi report group:

1. Explicit: pbi report --path ./MyReport.Report list-pages
2. Auto-detect: walks up from CWD looking for *.Report/definition/
3. From .pbip: finds sibling .Report folder from .pbip file

Suppressing Auto-Sync (--no-sync)

By default, every write command automatically syncs Power BI Desktop. When setting up multiple pages in sequence, Desktop reloads after each one.

Use --no-sync on the report command group to batch all page changes, then call pbi report reload once at the end:

# Suppress sync while setting up pages
pbi report --no-sync add-page --display-name "Overview" --name overview
pbi report --no-sync add-page --display-name "Details" --name details
pbi report --no-sync set-background overview --color "#F2F2F2"
pbi report --no-sync set-background details --color "#F2F2F2"

# Single reload when all page setup is done
pbi report reload

JSON Output

pbi --json report list-pages
pbi --json report get-page page_abc123
pbi --json bookmarks list

---

Gotchas

• delete-page is irreversible and removes the entire folder including visuals: No trash, no undo. If the page has unique visuals not duplicated elsewhere, they're gone. Always pbi report export-tmdl or git-commit before deleting.
• set-visibility --hidden does not hide a page from a published report URL: Anyone with the deep link /reports/{id}/{pageId} still loads it. For sensitive draft pages, also restrict the workspace role — visibility is a UX flag, not a security boundary.
• Drillthrough pages with pageBinding shown by get-page cannot yet be created by the CLI: You can read/list them but must configure the binding in Desktop. Round-tripping through Desktop sometimes reformats unrelated page settings — diff before commit.
• add-page ordinals are auto-assigned from the next-highest value, not appended at the end visually: If a previous page was deleted, the new ordinal can collide with what users perceive as the order. Use pbi report list-pages to confirm visible order.
• Bookmarks capture visual state by visual ID, not by name: Renaming a visual after a bookmark is saved leaves the bookmark pointing at a stale ID — the bookmark loads but the renamed visual ignores it. Rebuild bookmarks after any rename.
• Default page size 1280x720 looks fine in Desktop and broken on mobile: Desktop renders FitToPage by default; Service on phone uses the phone layout if defined, else clips. Always define a phone layout or set canvas to 1080-wide max for mobile-likely reports.