Dataflows CLI

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Automation and integrations
MIT
Low risk
Has scripts

From the author

Manages Fabric Dataflow Gen2 items, including creation, M editing, connections, output destinations, getDefinition and updateDefinition inspection, executeQuery, refresh history, and Gen1-to-Gen2 save-as upgrades via saveAsNativeArtifact. Use for Dataflow items or Power Query M definitions. For pipeline JSON use pipeline-migration; for Spark or Warehouse transformations use their own skills.

— the description by Microsoft

AutoGineer summary

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

The dataflows-cli skill provides a structured interface for interacting with Fabric Dataflow Gen2 items. It operates as a mode-based dispatcher, requiring users to select between authoring, consumption, or upgrade modes. The skill handles complex tasks such as M language definition updates, connection management, output destination configuration, and the migration of legacy Gen1 dataflows to Gen2.1. It emphasizes safe, intentional operations by requiring users to read specific reference documentation before executing state-changing API calls.

What it does

Creates and updates Fabric Dataflow Gen2 items and their definitions.
Manages connections, credentials, and output destinations for dataflows.
Previews Power Query M definitions using executeQuery to validate logic before persistence.
Facilitates the upgrade of Gen1 dataflows to Gen2.1 via save-as operations.
Retrieves refresh history and inspects existing dataflow definitions.
Provides a framework for executing and testing ad-hoc M queries.

When to use it

When you need to programmatically create or modify Fabric Dataflow Gen2 items.
When performing maintenance on Power Query M definitions or data connections.
When migrating legacy Gen1 dataflows to the Gen2.1 architecture.
When you need to audit refresh history or validate dataflow configurations.
When testing M query logic against live data sources before saving changes.

Advantages

Enforces a structured, mode-based workflow to prevent accidental mutations.
Provides granular control over Dataflow Gen2 definitions and metadata.
Supports complex lifecycle tasks like Gen1-to-Gen2 upgrades.
Integrates directly with Fabric REST APIs for automated data pipeline management.

Usage examples

“Show me the refresh history and parameters of the SalesIngest dataflow.”: The agent enters consumption mode, reads the consumption reference, and retrieves the requested refresh history and parameters for the specified dataflow.
“Preview this M query, then save it into the SalesIngest dataflow definition.”: The agent enters authoring mode, previews the M query to validate it, and then executes the updateDefinition call to persist the changes.
“Is my Gen1 dataflow ready to upgrade to Gen2.1?”: The agent enters upgrade mode, performs a readiness assessment, and reports on the risk and requirements for upgrading the specified Gen1 dataflow.

Install

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

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

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

Documentation by Microsoft

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

CRITICAL NOTES
To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering
Skill disambiguation: use dataflows-cli for every Fabric Dataflow Gen2 item and Power Query M concern. Synapse / ADF pipeline and dataset JSON translation is pipeline-migration; Spark notebook transformations are spark-cli; T-SQL transformations are sqldw-cli.

Fabric Dataflow Gen2 -- CLI Skill

This one skill owns Fabric Dataflow Gen2 items: connections, Power Query M, output destinations, saved definitions, refresh history, and Gen1 upgrades.

It is a mode dispatcher and contains NO procedures. Pick the mode that matches the request from the table below, then read the matching references/<mode>.md file end to end with your file-reading tool BEFORE issuing a single command. That file holds the endpoints, payload shapes, templates and gotchas; acting without it produces wrong payloads and wrong results.

Read it once per session. A file you have already read stays in context, so do not re-read it on a later turn; open the deeper files under references/<mode>/ only when a row in that file's reference table matches what you still need, and open only that row's file.

Mode selection

Mode	Use when the request ...	Example triggers	Read this first
`authoring`	creates or changes a dataflow: connections, credentials, M edits previewed before save, output destinations, updateDefinition	executeQuery preview, updateDefinition, connection setup, supportedConnectionTypes, credentialType, add output destination	references/authoring.md
`consumption`	reads a saved dataflow: definition, parameters, refresh history, or runs a saved/ad-hoc read-only M query and parses Arrow	getDefinition, executeQuery saved query, ad-hoc query, Arrow IPC, refresh history	references/consumption.md
`upgrade`	upgrades a Gen1 dataflow to Gen2.1 via save-as and rebind, or assesses upgrade readiness/risk	Gen1 Gen2 readiness, saveAsNativeArtifact, clone Gen1 dataflow, upgrade risk assessment	references/upgrade.md

Mode boundary rule

consumption is read-only. A preview run that exists to validate M before updateDefinition, and any capability lookup (supportedConnectionTypes, credentialType), belong to authoring even though they issue the same executeQuery call -- classify by intent, not by endpoint.

If a request genuinely spans modes, handle them one at a time and read each reference before you start that part. If the mode is ambiguous after reading this table, ask one short clarifying question instead of guessing.

Terminal write -- the step you must not skip

Reading the reference and planning the change is NOT completing the task. Each mutating mode ends with one state-changing call. If you did not issue it, nothing was persisted -- say so explicitly rather than reporting success.

Mode	Terminal write
`authoring`	`POST /v1/workspaces/{ws}/dataflows/{id}/updateDefinition` to persist the M, connections and output destinations; a NEW dataflow needs `POST /v1/workspaces/{ws}/items` (or `/dataflows`) first. `executeQuery` is a preview and writes nothing. If the user asked for a refresh, also `POST .../jobs/instances?jobType=Refresh`.
`consumption`	none -- this mode is read-only
`upgrade`	`saveAsNativeArtifact` to create the Gen2.1 artefact, then rebind. A readiness report alone does not upgrade anything.

Before you report the task done, confirm the terminal call returned success and, where the reference documents a readback, read the artefact back to prove the change landed.

`upgrade` generation boundary -- HARD STOP (mandatory)

Save-as runs only from Gen1 to Gen2.1. For an execution request whose source is Gen2, or whose source generation is not established, state that no public save-as or in-place upgrade endpoint is available and stop before any API call. This does not block a read-only readiness scan whose purpose is to discover and classify Gen1 candidates.

Do not read "choose the closest endpoint and proceed" as approval to export a definition and create a copy, do not switch to authoring to do it instead, and do not mutate anything. Ask the user to clarify the intended outcome and to approve explicitly.

`consumption` reporting

consumption has no terminal write, so its deliverable is the answer itself. When that mode runs executeQuery, name the operation you called and state the QueryName you sent, verbatim, next to the results, plus whether it was a saved shared member or a non-persisted ad-hoc customMashupDocument. Rows alone do not tell the user which call produced them.

This applies to consumption only. In authoring, executeQuery is an intermediate preview step -- do not add reporting turns around it; go on to the terminal write.

Shared essentials (all modes)

Resolve the workspace and item first; every mode depends on it.

Task	Reference	Notes
Finding Workspaces and Items in Fabric	COMMON-CLI.md	Mandatory -- read before resolving any workspace or item id
Fabric Topology & Key Concepts	COMMON-CORE.md	Item types, workspaces, capacities
Environment URLs	COMMON-CORE.md	Sovereign / non-public cloud hosts
Authentication & Token Acquisition	COMMON-CORE.md	Wrong audience = 401; read before any auth issue
Authentication Recipes	COMMON-CLI.md	`az login` flows and token acquisition
Core Control-Plane REST APIs	COMMON-CORE.md	Pagination, LRO polling, rate limiting
Gotchas & Troubleshooting	COMMON-CLI.md	`az rest` audience, shell escaping, token expiry

Rules

MUST

Select exactly one mode from the table above before doing anything else.
Read references/<mode>.md end to end, as your FIRST tool call, before the first command of that mode. Read it ONCE, in a single full read: do not re-open it, do not grep it again, and do not page through it. You already have it.
Resolve workspace and item ids by listing and filtering, never by guessing a GUID.
Announce a mode switch explicitly when the request crosses a boundary.
Treat the reference as instructions, never as the deliverable. After reading it, RUN the documented commands against the live workspace and report the real results. Quoting what the reference says instead of executing it does not answer the request.
When a question about what Fabric supports IS the deliverable -- supported connection types, a connector's parameters, available credential types -- answer it from the endpoint the reference names rather than from the reference's own list, and name that endpoint in your answer. Whichever mode you are in: the reader cannot tell a live value from a quoted one unless you say where it came from. This is wording in the final answer, not an extra step.
Produce every artefact the user asked for, under the name they used. Running the right API calls is not a substitute for the requested report: if the request names a deliverable, emit it, and keep its heading even when the finding is "none" or "not applicable".

PREFER

The narrowest mode that satisfies the request.
Reading exactly ONE mode reference. Load a second only when the request genuinely spans modes, and say so before you do.
Reporting the mode you chose in your first response so the user can correct you.

AVOID

Acting from this dispatcher alone -- it intentionally omits the operational detail.
Answering with a summary of the reference instead of executing it.
Re-reading or re-grepping a reference you already loaded; it costs turns and tokens.
Mutating anything while in a read-only mode.
Loading a different skill for work this skill already owns (see CRITICAL NOTES 3).

Examples

User request	Mode	Reference to read
"Show me the refresh history and parameters of the SalesIngest dataflow."	`consumption`	references/consumption.md
"Preview this M query, then save it into the SalesIngest dataflow definition."	`authoring`	references/authoring.md
"Is my Gen1 dataflow ready to upgrade to Gen2.1?"	`upgrade`	references/upgrade.md

Files

ATTRIBUTION.mdAdded by AutoGineer871 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md9.5 KiB
apm.yml445 B
references/authoring.md55.3 KiB
references/authoring/authoring-cli-quickref.md23.4 KiB
references/authoring/authoring-script-templates.md79.7 KiB
references/authoring/charts/bar_chart.pyScript3.9 KiB
references/authoring/charts/line_chart.pyScript3.5 KiB
references/authoring/connection-management.md39.8 KiB
references/authoring/connectors.md14.7 KiB
references/authoring/m-language.md9.7 KiB
references/authoring/mashup-preview.md28.3 KiB
references/authoring/output-destinations.md39.6 KiB
references/consumption.md28.7 KiB
references/consumption/chart-visualization.md2.6 KiB
references/consumption/charts/bar_chart.pyScript3.9 KiB
references/consumption/charts/line_chart.pyScript3.5 KiB
references/consumption/consumption-cli-quickref.md6.7 KiB
references/consumption/discovery-queries.md7.0 KiB
references/consumption/script-templates.md17.1 KiB
references/upgrade.md21.0 KiB
references/upgrade/risk-assessment-guide.md11.2 KiB
references/upgrade/upgrade-cli-quickref.md8.8 KiB

references/consumption/discovery-queries.md

Discovery Patterns and Queries

Extended discovery patterns beyond the basics in SKILL.md Agentic Exploration. All patterns use az rest with JMESPath queries and jq for JSON processing.

Listing and Filtering Dataflows

List All Dataflows with Full Details

# All dataflows with description and type
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows" \
  --query "value[].{id:id, name:displayName, desc:description, type:type}" -o table

List with Pagination (Handling continuationToken)

# Paginate through all dataflows
URL="$API/workspaces/$WS_ID/dataflows"
while [ -n "$URL" ]; do
  RESPONSE=$(az rest --method get --resource "https://api.fabric.microsoft.com" --url "$URL")
  echo "$RESPONSE" | jq -r '.value[] | [.id, .displayName] | @tsv'
  TOKEN=$(echo "$RESPONSE" | jq -r '.continuationToken // empty')
  if [ -n "$TOKEN" ]; then
    URL="$API/workspaces/$WS_ID/dataflows?continuationToken=$TOKEN"
  else
    URL=""
  fi
done

Cross-Workspace Dataflow Inventory

# Find dataflows across all accessible workspaces
for ws in $(az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces" --query "value[].id" -o tsv); do
  WS_NAME=$(az rest --method get --resource "https://api.fabric.microsoft.com" \
    --url "$API/workspaces/$ws" --query "displayName" -o tsv 2>/dev/null)
  DATAFLOWS=$(az rest --method get --resource "https://api.fabric.microsoft.com" \
    --url "$API/workspaces/$ws/dataflows" --query "value[].displayName" -o tsv 2>/dev/null)
  if [ -n "$DATAFLOWS" ]; then
    echo "=== $WS_NAME ($ws) ==="
    echo "$DATAFLOWS"
  fi
done

Definition Decoding

Decode All Definition Parts

RESPONSE=$(az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/getDefinition")

# Decode each part
for PART_PATH in "mashup.pq" "queryMetadata.json" ".platform"; do
  echo "=== $PART_PATH ==="
  echo "$RESPONSE" | jq -r ".definition.parts[] | select(.path==\"$PART_PATH\") | .payload" | base64 --decode
  echo ""
done

Handle LRO for getDefinition

# getDefinition may return 202 with Location header
HTTP_CODE=$(curl -s -o /tmp/df_def.json -w "%{http_code}" -X POST \
  -H "Authorization: Bearer $(az account get-access-token --resource "https://api.fabric.microsoft.com" --query accessToken -o tsv)" \
  "$API/workspaces/$WS_ID/dataflows/$DF_ID/getDefinition")

if [ "$HTTP_CODE" = "202" ]; then
  LOCATION=$(grep -i "location:" /tmp/df_def_headers.txt | tr -d '\r' | awk '{print $2}')
  echo "LRO started. Polling $LOCATION ..."
  while true; do
    STATUS=$(az rest --method get --resource "https://api.fabric.microsoft.com" \
      --url "$LOCATION" --query "status" -o tsv)
    echo "Status: $STATUS"
    [ "$STATUS" = "Succeeded" ] || [ "$STATUS" = "Failed" ] && break
    sleep 5
  done
  # Get the result
  az rest --method get --resource "https://api.fabric.microsoft.com" \
    --url "${LOCATION}/result"
fi

Extract Query Names from mashup.pq

# Decode mashup.pq and list all shared queries
az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/getDefinition" | \
  jq -r '.definition.parts[] | select(.path=="mashup.pq") | .payload' | \
  base64 --decode | grep -oP '(?<=shared )\w+(?= =)'

Analyze Connections from queryMetadata.json

Inline / literal-source dataflows: queries built from an inline expression (e.g. #table(...), hardcoded literals) have no external data source, so queryMetadata.json contains no connections entries (empty/absent array). Report "this dataflow has no external data source connections (inline source)" rather than implying a binding exists.

# Decode queryMetadata.json and list connections
az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/getDefinition" | \
  jq -r '.definition.parts[] | select(.path=="queryMetadata.json") | .payload' | \
  base64 --decode | jq '.connections // [] | if length == 0 then "No external connections (inline/literal source)" else .[] | {path, kind, connectionId} end'

Identify Load-Enabled vs Helper Queries

# Decode queryMetadata.json and classify queries
az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/getDefinition" | \
  jq -r '.definition.parts[] | select(.path=="queryMetadata.json") | .payload' | \
  base64 --decode | jq '.queriesMetadata | to_entries[] | {
    name: .key,
    loadEnabled: .value.loadEnabled,
    isHidden: .value.isHidden,
    role: (if .value.loadEnabled then "OUTPUT" elif .value.isHidden then "HELPER (hidden)" else "STAGING" end)
  }'

Parameter Discovery

Non-parametric dataflows: the /parameters endpoint returns DataflowNotParametricError (HTTP 4xx) when a dataflow has no Power Query parameters. Handle it gracefully — report "this dataflow has no parameters" rather than surfacing the raw error — and optionally confirm by scanning mashup.pq for IsParameterQuery (see "Find Parameters in mashup.pq" below).

Format Parameters as Report

# Tabular parameter report
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/parameters" | \
  jq -r '.value[] | "Parameter: \(.name)\n  Type:     \(.type)\n  Required: \(.isRequired)\n  Default:  \(.defaultValue // "none")\n  Desc:     \(.description // "none")\n"'

Find Parameters in mashup.pq

# Extract parameter definitions from M code
az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/getDefinition" | \
  jq -r '.definition.parts[] | select(.path=="mashup.pq") | .payload' | \
  base64 --decode | grep "IsParameterQuery"

Job History Analysis

Summarize Recent Job Results

# Count jobs by status
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/jobs/instances" | \
  jq '[.value[] | .status] | group_by(.) | map({status: .[0], count: length})'

Calculate Average Refresh Duration

# Average duration of completed jobs (in seconds)
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/jobs/instances" | \
  jq '[.value[] | select(.status=="Completed" and .endTimeUtc != null) |
    (((.endTimeUtc | fromdateiso8601) - (.startTimeUtc | fromdateiso8601)))] |
    if length > 0 then (add / length | round) else 0 end' | \
  xargs -I{} echo "Average refresh duration: {} seconds"

Extract Failure Reasons

# List all failures with reasons
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/jobs/instances" | \
  jq -r '.value[] | select(.status=="Failed") | "\(.startTimeUtc) | \(.failureReason // "unknown")"'

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.

Needs: Needs Python

Security

What our scanner noticed· Low risk

Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

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/dataflows-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 dataflows-cli.zip