Powerbi Report CLI

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Data and AI
MIT
Low risk

From the author

Plan, design, author, preview, publish, and manage Power BI reports across requirements, page design, local PBIR/PBIP edits, validation, screenshots, Fabric upload/download, and rebinding. Use for report lifecycle work; use semantic-model-authoring for model or DAX changes and fabriciq for data questions. Triggers: plan Power BI report, design report page, edit PBIR, preview PBIP, publish report, rebind report

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The powerbi-report-cli skill provides a structured, mode-based framework for managing the entire Power BI report lifecycle. It acts as a dispatcher across four distinct phases: planning (requirements and scope), design (visual and layout strategy), authoring (local PBIR/PBIP file manipulation and validation), and management (Fabric item transport and rebinding). The skill enforces strict boundaries between these modes to ensure quality, requiring explicit approval for new reports and utilizing a dedicated CLI for metadata-driven validation and authoring tasks.

What it does

Guides users through report requirements, scope, and page planning.
Provides design contracts for visual archetypes, layouts, and branding.
Enables local editing, validation, and previewing of PBIR and PBIP files.
Handles report item transport to and from Microsoft Fabric.
Supports re-theming, conditional formatting, and visual configuration.
Enforces a mandatory approval gate for greenfield report development.

When to use it

When planning a new Power BI report from a semantic model.
When you need to define a professional design brief or layout strategy.
When editing local PBIR/PBIP files, including visuals, filters, and themes.
When validating report structure and formatting before deployment.
When publishing or managing report items within a Fabric workspace.

Advantages

Ensures consistent report quality through a structured, multi-mode workflow.
Prevents premature publishing by enforcing a mandatory approval barrier.
Uses a dedicated CLI to eliminate guesswork in PBIR schema and property editing.
Maintains clear separation between design intent and technical implementation.
Provides robust validation tools to catch errors before Fabric deployment.

Usage examples

“Create a new executive report from this semantic model.”: The agent enters planning mode, inspects the model, generates a report spec, and requests user approval before proceeding.
“Design an operational page and choose the right charts.”: The agent enters design mode, produces a design brief with page archetypes and chart recommendations.
“Add a KPI page to this PBIP, validate it, and take screenshots.”: The agent enters authoring mode, modifies the local PBIP files, runs validation, and captures screenshots for review.
“Publish this local PBIP to my Fabric workspace and rebind it.”: The agent enters management mode, performs the upload to Fabric, and completes the rebind operation.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/powerbi-report-cli/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip powerbi-report-cli.zip -d .agents/skills

Documentation by Microsoft

Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry x-ms-fabric-skill: powerbi-report-cli (az rest: --headers "x-ms-fabric-skill=powerbi-report-cli"), including every LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.

CRITICAL NOTES
To find workspace details, including its ID, from a workspace name: list all workspaces, then use JMESPath filtering.
To find item details, including its ID, from a workspace ID, item type, and item name: list all items of that type in that workspace, then use JMESPath filtering.
Use powerbi-report-cli for the report artifact: requirements, design, PBIR/PBIP page and visual edits, preview, and publishing. Semantic model, measure, and DAX work belongs to a semantic-model skill. Natural-language questions about report data belong to fabriciq.

Power BI Reports - CLI Skill

This skill owns the Power BI report lifecycle end to end: requirements and scope, visual design, local PBIR/PBIP authoring and preview, and report-item transport to and from Microsoft Fabric.

It is a mode dispatcher and intentionally contains no detailed procedures. Select the mode that matches the request, then read the matching mode reference end to end before acting. The mode file holds the required workflow, commands, payloads, templates, and failure rules.

Mode Selection

Mode	Use when the request...	Existing route examples	Read first
`planning`	creates a new report/dashboard and needs requirements, model/dependency inspection, scope, a page plan, and approval before implementation	create a report, build a dashboard, create from a semantic model, plan then implement, walk me through creating a report	references/planning.md, then references/planning-part-02.md
`design`	decides what a report should look like: tone, signature, page archetype, chart type, layout, color, typography, theme direction, accessibility, brand application, redesign, or critique	design a Power BI report, make the dashboard professional, choose a chart, apply a brand, redesign the report, create a design brief	references/design.md
`authoring`	reads or edits local PBIR/PBIP files, validates them, previews the report, or captures screenshots	edit PBIR, create/add a report page or visual, format a visual, add filters/slicers/bookmarks/themes, validate PBIR, preview/reload/screenshot in Desktop or service	references/authoring.md
`management`	moves a report definition to or from Fabric or manages the workspace report item	publish/upload/download PBIR or PBIP, list reports, get/update/delete a report, rebind a report	references/management.md

Mode Boundary Rules

Classify by intent, not by which file or tool is already open.
design decides what the report should look like; authoring writes the PBIR that realizes it. Choosing a chart type is design; encoding it into visual.json is authoring.
Restyling or reformatting an existing local report is authoring, even when the request uses design language. Use design when the user wants advice or a design contract rather than a file change.
authoring changes local files and performs preview/validation. It does not publish to Fabric.
management transports definitions and manages Fabric report items. It does not invent or directly author PBIR content.
planning owns the guided requirements-to-approval flow for a new report. A focused edit to an existing report goes directly to authoring.

A greenfield request can span modes in this order:

planning -> design -> authoring -> management

Handle one mode at a time. Announce each switch and read the new mode reference before starting that part. The planning approval gate is a turn boundary: never build or publish until the user explicitly approves the locked spec in a later reply.

GREENFIELD APPROVAL BARRIER — MANDATORY. When a new-report request asks to plan, build, and/or publish but the user has not approved a locked spec in a prior reply, set the current phase to approval_pending and keep planning as the only active mode. In this phase, do not load authoring or management, edit/scaffold PBIR or semantic-model files, generate synthetic data, call Fabric write APIs, or publish. Persist _brief/report-spec.md, ask for explicit approval, and end the turn. The build/publish wording in the original request is desired future scope, not approval to cross this barrier.

Required Deliverable by Mode

Mode	Completion requirement
`planning`	Persist `_brief/report-spec.md` or the user-named equivalent, ask for explicit approval, and stop before implementation.
`design`	Produce the complete `Design Brief:` contract, including `design_identity` and a page archetype/layout contract for every page. Do not edit PBIR or call Fabric APIs.
`authoring`	Persist the requested PBIR/PBIP changes, validate each logical batch, then complete the selected preview and screenshot-review workflow required by the authoring reference. Do not publish.
`management`	Complete the requested Fabric report operation, including LRO polling and documented readback verification.

Rules

MUST

Select the narrowest mode that fully covers the current request.
Read references/<mode>.md end to end before the first command or file edit in that mode. When an already-loaded mode explicitly routes one narrow cross-mode operation to a named topic reference, treat that topic reference as the complete handoff; do not load the target mode's umbrella file unless the work expands beyond that operation.
In planning mode, also read references/planning-part-02.md before producing _brief/report-spec.md; it contains the required canonical design contract and approval checks.
Across a multi-turn task, retain a compact working state containing resolved workspace/item/model IDs, local and downloaded paths, and references already read. Reuse it in later turns unless the user explicitly requests a fresh query or the preceding operation invalidated a value.
Preserve every argument and safety boundary documented by the selected mode.
Announce and perform an explicit mode switch when the request crosses a boundary.
Use the powerbi-report-author CLI metadata and validation surfaces instead of guessing PBIR schemas, roles, formatting properties, selectors, or enum values.
Keep local edits local unless the user explicitly requests publishing.
Resolve Fabric workspace and item IDs by listing and filtering rather than guessing identifiers.
Produce the artifact the user requested; reading or summarizing a reference is not task completion.

PREFER

Infer facts already present in the prompt, semantic model, existing PBIP, or prior approved spec instead of asking again.
Load only the selected mode and its directly relevant topic references.
Reuse reference guidance already loaded in the current task. Open a new reference only when the requested operation or an observed mismatch requires it.
Preserve the user's existing project structure, schemas, host, operation, binding, and delivery target unless the selected mode explicitly requires a change.

AVOID

Acting from this dispatcher without reading the selected mode reference.
Reloading this dispatcher, a mode file, or a topic reference already read in the current task solely because the conversation advanced to a later turn.
Loading a retired sibling skill name; planning, design, authoring, and management are modes of this skill.
Editing PBIR or calling Fabric APIs in planning or design.
Publishing from authoring, or authoring PBIR content from management.
Bypassing the planning approval gate because the original request also asked to build or publish.

Complete Reference Index

Open every relevant reference directly from this index. Files named part-XX continue the named topic.

Authoring

Design

Mode Guides

Examples

User request	Mode
"Create a new executive report from this semantic model."	`planning`
"Design an operational page and choose the right charts."	`design`
"Add a KPI page to this PBIP, validate it, and take screenshots."	`authoring`
"Publish this local PBIP to my Fabric workspace and rebind it."	`management`

Route Compatibility

The merged skill preserves the four previous route surfaces. Treat the following phrases as explicit aliases for the corresponding mode:

Mode	Preserved route phrases
`planning`	create a report; build a report; create a dashboard; create a new report from scratch; create a report from a semantic model or dataset link; build a report for this model; make me a dashboard; plan then implement; walk me through creating a report
`design`	design Power BI report; make dashboard look professional; choose chart type; apply brand to report; redesign report; create design brief; Power BI report design archetype
`authoring`	edit PBIR; create Power BI report page; add visual to PBIP; format report visual; validate Power BI report; preview Power BI report; Power BI Desktop preview status; preview report in service; preview report in browser; screenshot report page; screenshot all report pages; list preview hosts; implement dashboard in PBIP; add dashboard visuals to report; implement an approved PBIP report spec; edit PBIR pages/visuals; edit a Power BI report
`management`	upload PBIR report definition; upload Power BI report; download PBIR definition; publish PBIR definition; publish Power BI report to Fabric; manage Power BI reports; list workspace reports

Files

ATTRIBUTION.mdAdded by AutoGineer881 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md16.1 KiB
apm.yml642 B
references/authoring-part-02.md14.6 KiB
references/authoring-part-03.md16.0 KiB
references/authoring-part-04.md15.9 KiB
references/authoring.md16.8 KiB
references/authoring/authoring-workflows.md11.7 KiB
references/authoring/bookmark.md14.3 KiB
references/authoring/button-part-02.md16.1 KiB
references/authoring/button-part-03.md7.7 KiB
references/authoring/button.md15.7 KiB
references/authoring/card-part-02.md16.1 KiB
references/authoring/card-part-03.md8.6 KiB
references/authoring/card.md6.4 KiB
references/authoring/cartesian-part-02.md17.7 KiB
references/authoring/cartesian-part-03.md12.3 KiB
references/authoring/cartesian-part-04.md15.8 KiB
references/authoring/cartesian.md18.0 KiB
references/authoring/color-strategy.md8.4 KiB
references/authoring/conditional-formatting-part-02.md13.5 KiB
references/authoring/conditional-formatting-part-03.md16.0 KiB
references/authoring/conditional-formatting-part-04.md14.0 KiB
references/authoring/conditional-formatting-part-05.md16.9 KiB
references/authoring/conditional-formatting-part-06.md14.7 KiB
references/authoring/conditional-formatting-part-07.md14.5 KiB
references/authoring/conditional-formatting.md18.2 KiB
references/authoring/custom-visuals.md13.9 KiB
references/authoring/expressions.md11.9 KiB
references/authoring/field-parameters.md5.1 KiB
references/authoring/filter-pane.md5.0 KiB
references/authoring/filters.md9.3 KiB
references/authoring/formatting-overview.md4.8 KiB
references/authoring/formatting-part-02.md3.3 KiB
references/authoring/formatting.md17.0 KiB
references/authoring/image.md12.6 KiB
references/authoring/kpi.md2.5 KiB
references/authoring/map.md13.4 KiB
references/authoring/model-binding.md7.7 KiB
references/authoring/page-formatting.md4.5 KiB
references/authoring/powerbi-desktop.md2.4 KiB
references/authoring/powerbi-report-author-cli-part-02.md3.2 KiB
references/authoring/powerbi-report-author-cli.md17.7 KiB
references/authoring/preview-part-02.md16.9 KiB
references/authoring/preview-part-03.md4.0 KiB
references/authoring/preview-part-04.md2.5 KiB
references/authoring/preview.md16.1 KiB
references/authoring/re-theming-part-02.md16.8 KiB
references/authoring/re-theming-part-03.md4.9 KiB
references/authoring/re-theming.md1.5 KiB
references/authoring/screenshot-review.md5.0 KiB
references/authoring/shape.md13.6 KiB
references/authoring/slicers-part-02.md16.3 KiB
references/authoring/slicers.md15.6 KiB
references/authoring/table.md17.5 KiB
references/authoring/textbox.md5.6 KiB
references/authoring/theming-part-02.md6.7 KiB
references/authoring/theming.md16.4 KiB
references/authoring/version-control.md6.6 KiB
references/design.md17.3 KiB
references/design/accessibility.md11.4 KiB
references/design/anti-patterns.md18.5 KiB
references/design/archetype-composition.md3.4 KiB
references/design/archetypes/analytical-canvas.md17.7 KiB
references/design/archetypes/comparative-benchmark-part-02.md5.7 KiB
references/design/archetypes/comparative-benchmark.md15.8 KiB
references/design/archetypes/executive-summary.md14.7 KiB
references/design/archetypes/narrative-story.md18.1 KiB
references/design/archetypes/operational-monitor.md17.0 KiB
references/design/assets/base.json7.5 KiB
references/design/brownfield.md5.7 KiB
references/design/chart-selection.md9.8 KiB
references/design/color.md10.5 KiB
references/design/design-brief-part-02.md13.7 KiB
references/design/design-brief.md8.8 KiB
references/design/interactivity.md9.2 KiB
references/design/layout.md11.3 KiB
references/design/pre-flight-checklist.md10.8 KiB
references/design/signatures.md12.3 KiB
references/design/tone-catalog.md14.4 KiB
references/design/typography.md9.2 KiB
references/design/visual-cookbook-part-02.md11.0 KiB
references/design/visual-cookbook.md16.7 KiB
references/management-part-02.md17.2 KiB
references/management-part-03.md7.5 KiB
references/management-part-04.md16.7 KiB
references/management.md10.1 KiB
references/planning-part-02.md11.2 KiB
references/planning.md19.5 KiB

references/authoring/powerbi-report-author-cli.md

`powerbi-report-author` CLI Reference

Command catalog
Rendering preview vs PBIR inspection commands
Validation result handling
Preview result handling
- Screenshot options

Use this file when the root command table is not enough. The CLI is the source of truth for visual roles, formatting objects, property names, enum values, selectors, expression/value encodings, and PBIR validation.

Command catalog

Command	Purpose	When to use
`--help` / `<command> --help`	Show syntax and available flags	Before using an unfamiliar non-preview command or before the preview host/operation is selected; never before an explicit Desktop operation
`catalog list`	List all built-in visual types and deprecated entries	Choosing a visual type
`catalog describe <type>`	Roles, formatting keys, cardinality	Before creating/editing a visual
`formatting list-objects <type>`	Valid `objects.*` keys + VCO keys; flags objects needing id selectors	Before applying formatting
`formatting describe-object <type> <object>`	Property names, types, enum values, descriptions; `_selectorHint` when id selector required	Finding exact property names and allowed values
`formatting describe-property <type> <object> <prop>`	Focused single-property lookup	When you already know the object and want one property
`formatting search <type> <regex>`	Regex search across formatting objects + VCOs	When you do not know which object a property belongs to
`formatting list-vcos`	Enumerate shared visualContainerObjects	Auditing chrome/container formatting surface
`formatting effective-properties <type>`	Flattened visual objects + shared VCOs	One-shot snapshot of every formatting surface for a visual
`expr encode --kind <t> <v> [percent]`	Generate correct PBIR value encoding	Writing formatting values
`expr decode '<json>'`	Decode a PBIR expression to plain value	Inspecting existing formatted values
`theme encode --kind <t> <v>`	Generate the plain-JSON value used inside a theme file	Editing theme JSON
`theme shade-color <hex> <percent>`	Apply ThemeDataColor shadeColor adjustment	Previewing tinted/shaded theme colors
`text measure "<label>" [--font <name>] [--size <pt>] [--px] [--bold] [--italic] [--weight <kw>] [--icon] [--hpad <px>] [--margin <frac>] [--font-file <path>]`	Measure a label's rendered width from the installed font's real advance widths (falls back to a labeled per-character approximation when the font is not installed) and recommend a button width	Sizing text-bearing visuals (buttons) so labels don't clip — instead of a flat character-count estimate
`scaffold <output-dir> --name <ReportName> [--model-path ../<Model>.SemanticModel] [--page-name <name>] [--offline] [--force]`	Create a minimal, valid PBIP shell; fetches latest `$schema` versions live from the public `microsoft/json-schemas` mirror (falls back to pinned, or `--offline` to force pinned), then self-validates offline	Creating a brand-new (greenfield) report
`pack <folder> [--mode update\|create] [--display-name <name>] [--description <text>] [--raw]`	Serialize a PBIR report (a `.pbip`, a `.Report` directory, or a directory containing `definition/`) into a Fabric report-definition payload; default output is a `{data:...}` envelope and `--raw` emits the raw body for pipe UX; PBIR-oriented: pack collects only qualifying PBIR parts and performs no format check, so a legacy `.Report` that still has `definition.pbir` packs a partial payload instead of failing, and callers must confirm a modern `definition/` layout before packing	Pack serializes qualifying PBIR parts from a .Report folder into a Fabric report-definition payload for pipe or file-based transport
`unpack <folder> [--input <file>] [--force]`	Reconstruct a PBIR `.Report` folder from a Fabric `getDefinition` response read from stdin or `--input`; no-clobber is the default, and `--force` stages then swaps overwrites; PBIR-only, rejecting PBIR-Legacy with `UNPACK_FORMAT_UNSUPPORTED`	Unpack reconstructs a PBIR .Report folder from a Fabric getDefinition response read from stdin or --input
`validate <path>`	Full validation of a `.pbip` or `.Report` directory	After every batch of PBIR edits
`preview --list-hosts`	List available rendering hosts and their capabilities	When preview availability or capability support is unknown
`preview <folder> --host service --group <id> --dataset <id> --status`	Inspect service preview status without taking a screenshot	Before service open/reload and when the user explicitly requests status
`preview <folder> --host service --group <id> --dataset <id> --screenshot "<validation-screenshot-dir>\<name>.png" [--page <id>] [--scale <1-3>] [--headless]`	Capture the default or selected service page into the workflow-owned validation directory	After validation and reload for rendered-output changes
`preview <folder> --host service --group <id> --dataset <id> --screenshot "<validation-screenshot-dir>" --all-pages [--scale <1-3>] [--headless]`	Capture all service pages into the workflow-owned validation directory	For full-report rendered validation
`preview <folder> --host desktop`	Open/attach the Desktop instance resolved from the report folder; no lifecycle flag	Requires the owning `.pbip`
`preview <folder> --host desktop --status`	Inspect the Desktop instance resolved from the report folder; reports `details.hasUnsavedChanges`	When Desktop instance state is unclear, and as the preflight before any `--reload`, `--reload-with-model`, or bare `preview`
`preview <folder> --host desktop --reload`	Reload the latest PBIR layout into Desktop	After editing the report definition
`preview <folder> --host desktop --reload-with-model`	Load the latest PBIR layout and on-disk semantic-model definition into Desktop; does not process the live model	After validating a local TMDL change; then follow Semantic-model reload workflow (see `preview-part-04.md`, section `semantic-model-reload-workflow`)
`preview <folder> --host desktop --screenshot "<validation-screenshot-dir>\<name>.png" [--page <id>] [--scale <1-3>]`	Capture one Desktop page into the workflow-owned validation directory	After the latest layout is loaded
`preview-visuals <path> [--with-derived]`	Enumerate every visual with stable summary fields + path to JSON	Auditing visuals across a report
`preview-pages <path> [--with-derived]`	Page metadata summary	Quick page overview
`preview-filters <path>`	Enumerate report/page/visual filters	Filter audit
`preview-themes <path> [--with-derived]`	Registered custom theme summary	Theme audit
`doctor`	Environment self-check	First-run setup or troubleshooting

Rendering preview vs PBIR inspection commands

preview is the rendering command. Both hosts support preview, --status, --reload, and screenshot capture; the service host additionally supports --close. Compatible Desktop hosts also support --reload-with-model; the service host reports modelDefinitionReload: false. Desktop screenshot uses --screenshot <path> with optional --page, --all-pages, and --scale. Desktop screenshot is a warm capture and does not reload PBIR. Service uses the same --screenshot <path> flag and supports default-page, --page, --all-pages, and --scale capture.

Despite their shared prefix, preview-visuals, preview-pages, preview-filters, and preview-themes are read-only PBIR metadata inspection commands. They enumerate report definitions on disk; they do not contact Desktop or service and do not produce report screenshots.

When the user has selected a host and requested attach/open, reload, or screenshot, run only the matching host-specific command. Do not precede it with --help, --list-hosts, validation, or another lifecycle operation. The one call that precedes open/attach or reload is selected-host --status; never run it before a screenshot. If status reports details.hasUnsavedChanges: true, do not run open/reload automatically. Structured HOST_UNAVAILABLE additionally permits open/attach, but not reload. Interpret a host that does not currently expose unsaved state according to its availability response. Otherwise report the safety-gate failure and stop without asking whether automatic open/reload should proceed anyway. See preview.md (see preview.md). After the operation runs, a failure without an explicit machine-readable correction object is terminal: make no further tool calls. Error text, hints, usage output, unknown-option responses, and suggestions to run help are not structured corrections. When that object is present, change only its named value and preserve the operation, host, folder, screenshot destination, and all other arguments. This terminal rule overrides all discovery, status, and troubleshooting guidance.

Every Desktop command explicitly contains --host desktop. The public command resolves the Desktop instance from <folder> and does not accept --pid. Desktop screenshot contains --screenshot "<path>"; the output path is the value of --screenshot.

For a screenshot request, every executed command must retain the selected host's exact screenshot syntax and destination. Patch an allowed retry from the original command; do not execute attach, reload, status, close, help, or discovery instead.

The requested host and operation are immutable, including during a corrected retry. Never switch Desktop to service or substitute another lifecycle operation. Preserve the host-specific screenshot destination, supported modifiers, service bindings, and headless mode exactly.

Attach/open/connect/show maps to the plain Desktop command. Do not append --reload. Use --reload only for an explicit report reload or refresh request. Use --reload-with-model only when local TMDL changed and both the report and semantic-model definitions must be loaded.

powerbi-report-author preview --list-hosts

Desktop direct operations:

powerbi-report-author preview "<folder>" --host desktop
powerbi-report-author preview "<folder>" --host desktop --status
powerbi-report-author preview "<folder>" --host desktop --reload
powerbi-report-author preview "<folder>" --host desktop --reload-with-model
powerbi-report-author preview "<folder>" --host desktop --screenshot "<validation-screenshot-dir>\page.png"
powerbi-report-author preview "<folder>" --host desktop --screenshot "<validation-screenshot-dir>\page.png" --page "<page-id>"
powerbi-report-author preview "<folder>" --host desktop --screenshot "<validation-screenshot-dir>" --all-pages

Service operations:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless
powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless --reload
powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless --screenshot "<validation-screenshot-dir>\page.png"
powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless --screenshot "<validation-screenshot-dir>\page.png" --page "<page-id>" --scale 2
powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless --screenshot "<validation-screenshot-dir>" --all-pages --scale 2
powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --close

Service preview renders the local edited PBIR layout against the live service data of a published semantic model identified by --dataset, in the workspace identified by --group; it does not publish or persist local report edits and does not require a report ID. Never infer either tenant-scoped ID. If REPORT_NOT_PUBLISHED indicates that the semantic model is unavailable, resolve or publish that prerequisite through its owning report-management workflow only when explicitly authorized; never publish local report WIP as a preview side effect. Service screenshot supports default-page, selected-page, all-pages, and scale capture. Desktop availability and capabilities depend on the installed CLI, bridge, Desktop build, and matching live instance. A plain Desktop preview is the open/attach operation, but the skill issues it only after the strict status preflight passes with boolean false; it never closes Desktop. A separately requested reload updates report layout only. --reload-with-model updates report layout and requests that Desktop also reload the on-disk semantic-model definition. It does not refresh model data or prove freshness. After it succeeds, follow Semantic-model reload workflow (see preview-part-04.md, section semantic-model-reload-workflow): Calculate for metadata and calculated-object changes, targeted Full for changed/new imported columns and import partitions, or the storage-mode-specific semantic-model workflow for non-Import models. Use the structured preview response as the source of truth and do not bypass the preview command with a direct host command. Always pass --host rather than relying on the command default. Keep --headless consistent between opening and screenshot capture or reload so the CLI preserves the service instance mode. For a screenshot on either host, the requested command itself is the first and only command unless its result supplies a structured correction. Open/attach and either reload form first run the selected-host --status preflight. If the selected host reports unsaved state, proceed only when details.hasUnsavedChanges is boolean false; structured HOST_UNAVAILABLE also permits open/attach, but not either reload form. A corrected retry must keep every non-corrected argument unchanged. For mandatory authoring validation, resolve every screenshot destination through the external workflow-owned lifecycle in preview.md (see preview.md). Use one <validation-screenshot-dir> per report and never use a current-directory-relative or PBIP-local path. See preview.md (see preview.md) for host and argument selection.

Validation result handling

Run powerbi-report-author validate <path-to-.Report-dir> after every logical batch of PBIR edits.

Fix every error before rendered preview.
Review warnings before proceeding. Unknown visual types or theme visual keys usually mean a typo unless the report intentionally uses a custom .pbiviz.
Diagnostics include file paths and JSON paths. Use them to jump directly to the broken node.
For large diagnostics, use --pretty for readable output or --out <file> to write the full result to a file.

Preview result handling

Screenshot options

--screenshot <path> is the capture operation and carries its destination as the flag's value. --page, --all-pages, and --scale are gated on it, not siblings of it. There is no preview screenshot … subcommand; every capture is a preview invocation carrying --screenshot.

--screenshot <path>                 the capture operation; <path> is its destination
├── <file>.png                      destination for a default-page or --page capture
├── <directory>                     destination for an --all-pages capture
├── (page selection)                OPTIONAL — at most one of the two
│   ├── --page <id>                 one page, by page ID or display name
│   └── --all-pages                 every page, one PNG each, into the directory
└── --scale <1-3>                   OPTIONAL — both hosts; host default 2

Omitting page selection captures the default page. Violations come back as structured errors, not free text: a screenshot-only option without --screenshot, an empty --screenshot "" destination, and --page combined with --all-pages each return INVALID_OPTION with a correction object naming the offending parameter; a --scale outside 1-3 returns PARAMETER_FORMAT_INVALID. --screenshot with no value at all is a parser error, INVALID_USAGE, and carries no correction — so it is terminal.

Service preview also requires --group <workspaceId> and --dataset <datasetId> and a signed-in Azure CLI. If either ID is missing, ask for it immediately without searching project files, running --list-hosts, or invoking preview. Service and Desktop both support --page, --all-pages, and --scale. powerbi-report-author preview is the intended interface for every Desktop operation, including reading Desktop's unsaved-changes flag, which --status reports at details.hasUnsavedChanges. It takes no --pid and does not need one: it resolves the instance from the report folder you pass, so several Desktop windows holding different reports are matched correctly on their own. The one shape it cannot resolve is two or more windows holding the same report folder. There it refuses to guess and fails HOST_UNAVAILABLE ("Several Power BI Desktop instances have this report open."), carrying the candidate pids in details.candidatePids — so not even that case needs the bridge to identify the windows. Resolving it is the user's call: show them the candidates and ask them to close the others so exactly one window holds the report. Never close or kill one yourself. No preview or bridge command closes the user's Desktop, and a window you discard may hold unsaved work. Return to preview for the operation itself once exactly one window remains.

The direct bridge fallback is isolated in powerbi-report-author-cli-part-02.md. Do not open it for normal Desktop operations or after a terminal preview failure.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Low risk

Phrasing that asks for actions without confirmation
Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills-for-fabric · skills/powerbi-report-cli · commit f8fac11

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

microsoft/skills-for-fabric

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download powerbi-report-cli.zip