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://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/preview-part-02.md

Report Preview - Part 2

Exact command examples
Status and ambiguity
Preview lifecycle
- Unsaved host changes
Errors and fix/retry

Continuation of preview.md. Open this file directly from the skill reference index.

Exact command examples

Discover hosts and capabilities:

powerbi-report-author preview --list-hosts

Check Desktop status through the selected Desktop host:

powerbi-report-author preview "<folder>" --host desktop --status

Use the returned structured status or error as the source of truth. If the installed host reports unavailable or unsupported behavior, surface that result rather than using the underlying bridge directly.

Attach/open the matching Desktop instance with no lifecycle flag:

powerbi-report-author preview "<folder>" --host desktop

Reload edited PBIR into the matching Desktop instance:

powerbi-report-author preview "<folder>" --host desktop --reload

For TMDL/model changes, follow Semantic-model reload workflow (see preview-part-04.md, section semantic-model-reload-workflow) instead of using plain --reload.

Capture through the matching Desktop instance:

powerbi-report-author preview "<folder>" --host desktop --screenshot "<validation-screenshot-dir>\page.png"

Capture a selected Desktop page:

powerbi-report-author preview "<folder>" --host desktop --screenshot "<validation-screenshot-dir>\page.png" --page "<page-id>"

Capture all Desktop pages:

powerbi-report-author preview "<folder>" --host desktop --screenshot "<validation-screenshot-dir>" --all-pages

Open a visible service preview:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>"

Open a headless service preview for an agent:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless

Reload edited files into the live service instance:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --reload

Reload an existing headless instance:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless --reload

Capture the default service page:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --screenshot "<validation-screenshot-dir>\page.png"

For an existing headless instance:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --headless --screenshot "<validation-screenshot-dir>\page.png"

Capture one selected service page:

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

Capture all service pages:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --screenshot "<validation-screenshot-dir>" --all-pages --scale 2

Do not add --pid to service commands.

Check service preview status:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --status

Close the service preview:

powerbi-report-author preview "<folder>" --host service --group "<workspace-guid>" --dataset "<semantic-model-guid>" --close

Status and ambiguity

Requested operation	Run `--status` first?
Selected-host open/attach	Yes
Selected-host reload	Yes
Selected-host screenshot	No
Selected-host status	No; status is the requested operation

Before open/attach or reload, run --status against the same selected host, report folder, service binding, and instance mode. Interpret the result under Unsaved host changes and the selected host's current capabilities. Use --list-hosts only before a host is selected. Status is a read-only preflight, not a diagnostic follow-up to a failed selected-host operation.

If the user says a matching preview is already running, still run the selected-host status preflight before open/attach or reload.
Once the host and operation are selected, run no help, discovery, or alternative operation before the required status preflight and requested operation. Handle failures under the terminal rule above; never switch hosts or invoke a direct host CLI.
If service context is incomplete, ask only for the missing workspace (--group) and/or semantic-model (--dataset) GUID. Run no command first.
If no suitable host is available, report that fact rather than falling back to a direct host CLI.

Preview lifecycle

Keep the lifecycle explicit:

Load the validated state into the selected host.
Capture every affected page and inspect screenshots plus structured diagnostics.
Iterate by editing, validating, and previewing again.
For the service host only, display a clean result in a visible service preview automatically. Run visible status, then visible open/attach; keep it open. Skip this step for Desktop; its workflow is unchanged.
Accept only after the requested result is approved.
Commit locally only after approval.
Publish remotely only when the user explicitly asks to publish, upload, push, or deploy the current local changes. Never publish or overwrite the remote report with local changes until the user explicitly gives permission. If the request does not ask to publish, or you are unsure, keep the changes local and do not publish.
Discard only on an explicit user request.
Close a headless service validation instance when no further iteration is expected. Do not close the final visible service preview. For a direct preview request, execute only the named operation and add --close only when explicitly requested. Leave Power BI Desktop open.

Service preview renders unpublished local PBIR layout changes against the published semantic model's live data without publishing or persisting those local edits. For an existing instance, run --reload before --screenshot; screenshot capture alone does not re-read edited files. A screenshot request does render before capture when it has to launch a fresh instance.

For authoring verification, run selected-host status, then open/attach or reload, then screenshot as separate commands. If the selected host reports unsaved changes and blocks loading the latest PBIR, a screenshot may document the current host state but cannot validate the new edits; report screenshot validation as blocked.

Apply the current host-specific status contract under Unsaved host changes. Desktop open/attach leaves Desktop running after the command completes, and a separately requested reload updates only the report definition. --reload-with-model updates the report definition and requests model-definition reload, but it does not refresh model data or prove freshness. Screenshot results can be partial. Report every returned capture and failure rather than flattening a partial result into success:

Partial envelope. A partial capture still writes the success envelope with status: "partial" but exits non-zero, so a non-zero exit alongside status: "partial" marks a partial capture, not a total failure; keep and review the captures it returned.
Unknown-page RENDER_FAILED. A per-page RENDER_FAILED whose message says the page id is unknown to the open window means the page exists on disk but not in the live window, usually because it was added after the last reload.
bridgeCode is optional, non-authoritative. Some Desktop builds also set details.bridgeCode inside that failure's error.details rather than at the top of the error object, but its value varies by build — "BRIDGE_ERROR", "PageNotFound", or absent entirely. Never key the diagnosis on a particular bridgeCode value; read it only as a weak confirming detail. The authoritative signal is the RENDER_FAILED code plus the unknown-page id message above.
Distinct from PAGE_NOT_FOUND. PAGE_NOT_FOUND is raised before capture when the requested page is absent from the report definition it resolved; a reload cannot conjure a page the definition does not contain.
Recovery is narrow. That one self-explaining case, and only it, may be recovered, and only when recovery is already authorized — you initiated the capture inside your own edit-then-review loop, or the user asked you to handle the capture's result. The recovery is a new operation sequence run after the partial envelope returns, not a reload or status call chained onto or preceding the original screenshot request: it is the second of the two exceptions under Desktop operation routing, which still forbids fronting a screenshot with --reload or --status. Recover by running the unsaved-changes preflight, reloading, then recapturing only the pages that failed instead of rerunning the whole --all-pages batch — one --page capture per failed page, or the whole batch again only when the user asked for a verified complete set. When the user asked only for the capture and nothing further, do not substitute a reload, a status call or any other operation for it; report the partial, name the pages that failed and why, and stop. Any other per-page failure, and any ok: false failure envelope, stays terminal under the rule above.

Unsaved host changes

A preview host may hold report edits in memory that are not yet represented in the PBIR files on disk. Open/attach, report reload, or report-plus-model reload can replace that host state with the disk definition, so every selected host uses a status preflight before these operations. This is the canonical statement of the safety gate; other files state it by reference rather than restating it.

Which operations it gates. The gate applies to any selected-host open/attach or reload that can re-read PBIR into a live instance. A request to refresh is not authorization to discard unsaved edits. --screenshot is never gated because it captures the host as it stands and replaces no state. Neither is --status itself or --list-hosts.

Current Desktop status exposes unsaved state; current service preview is read-only and does not. When service editing adds the same state, the common rule below applies without changing the authoring workflow.

powerbi-report-author preview "<folder>" --host <desktop|service> [service binding] --status

{"data":{"state":"ready","reports":[{"folder":"...","hostInstanceId":"12345"}],
 "details":{"hasUnsavedChanges":true}}}

Drive this read through powerbi-report-author preview. A host that supports editing reports the selected instance's unsaved state at details.hasUnsavedChanges (under data), resolved from the same report folder and binding the operation will act on. Read it as follows:

false — run the requested reload or bare preview.
Field not provided by a host that currently has no editing capability — use the returned availability state to continue the requested open/attach or reload. This is the current service behavior.
Structured HOST_UNAVAILABLE — run bare preview because no existing host instance can contain unsaved changes. Do not run reload; report the failure and stop.
true, null, a missing or non-boolean field, or any other failed status call from a host whose contract exposes unsaved state — the safety gate failed. Report the failure and stop the requested open/reload. Do not reinterpret the result as false. For standalone preview requests, do not ask whether automatic open/reload should proceed anyway. During mandatory post-edit validation, only explicit boolean true uses the recovery below; missing, invalid, and failed reads remain terminal.

Boolean false permits either operation. Structured HOST_UNAVAILABLE permits only open/attach.

Mandatory post-edit validation recovery. When a selected host reports explicit boolean true and blocks the load required after agent-authored PBIR edits, preserve the disk edits and do not finish the authoring task:

Do not run open/reload automatically, and do not use a stale warm-window screenshot as validation.
Ask the user to resolve the unsaved state manually in the selected host and confirm that the latest PBIR is loaded.
After confirmation, resume directly with screenshots of every affected page and review them. Do not rerun the PBIR edits, schema validation, status, or reload.
If the user does not complete the manual refresh, report schema validation as passed and screenshot validation as blocked.

This recovery applies only to mandatory validation initiated by an authoring workflow. It does not authorize the agent to discard host changes, weaken the gate for a direct open/reload request, or turn a standalone operation into a multi-command workflow.

"Stop" here scopes to the reload, not to the whole task. A blocked reload does not forbid --screenshot: a warm capture changes nothing and stays permitted, though what it captures is the window as it stands, which may be stale relative to disk. Say so when reporting the result. This applies only to a reload that was never issued because the gate blocked it; a reload that ran and returned ok: false is a host failure — report it and do not capture.

This read is a read-only precondition on selected-host operations that re-read PBIR into a live instance, never a replacement for the operation itself and never a license for any other diagnostic. Return to powerbi-report-author preview for the operation itself.

DESKTOP_UNSAVED_CHANGES is declared in the preview error contract but no code path emits it, so never wait for that error to signal unsaved work.

Errors and fix/retry

Error	Meaning	Code-specific correction
`HOST_UNAVAILABLE`	Requested host or matching live instance is unavailable	During the mandatory status preflight, proceed to plain open/attach when the result establishes that no matching Desktop instance exists; for reload, report the failure and stop. Before host selection, run `preview --list-hosts` when the host is unknown. After a selected Desktop operation, report that no match exists. When the message is "Several Power BI Desktop instances have this report open.", several windows hold the same report and `details.candidatePids` lists them: report the candidate pids and ask the user to close the others so exactly one window holds the report, then retry only after they confirm they have done so. Never close or kill a Desktop window yourself
`REPORT_NOT_PUBLISHED`	Required semantic model is unavailable or has no embed URL	Resolve or publish the model prerequisite only when explicitly authorized; never publish local report WIP as a preview side effect
`CAPABILITY_UNSUPPORTED`	Host lacks the requested capability	The capability does not exist on that host; report it rather than substituting another host or operation
`WORKSPACE_REQUIRED`	Service needs workspace context	Ask for the workspace GUID and pass it with `--group`
`INVALID_OPTION`	Required or supported arguments are wrong	For service, supply both `--group` and `--dataset` or correct the flagged option. For Desktop, parser text is not a correction
`AUTH_REQUIRED`	Service authentication is unavailable or expired	Report the authentication requirement
`PAGE_NOT_FOUND`	Requested page is unavailable	Correct the requested `--page` ID, reading the valid IDs from `preview-pages`, or omit it to capture the default page
`REPORT_PATH_INVALID`	Folder cannot resolve to the required report project	Ensure the owning `.pbip` exists before the initial command
`PARAMETER_FORMAT_INVALID`	A supplied option has an invalid format	Fix the flagged value to the `expected` shape — for example `--scale` must be an integer from 1 to 3
`RENDER_FAILED`	Host could not render the request	Nothing in the command shape is at fault; report the host-side failure (a per-page `RENDER_FAILED` inside a partial capture is handled under Preview lifecycle above)

Every row is subject to the terminal rule except the open/attach preflight HOST_UNAVAILABLE case above: apply a supplied correction object to that same operation and retry once; without one, report the failure and stop with no further tool call. Never insert validation or another lifecycle command. The multi-instance HOST_UNAVAILABLE retry is user-mediated: the user changes the environment, not the command, so it is not a retry under the terminal rule. Review successful images with screenshot-review.md (see screenshot-review.md).

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-09

Also distributed in

microsoft/skills-for-fabric

AutoGineer is not affiliated with or endorsed by Microsoft or Microsoft.

Download ZIP

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