Variable Library CLI

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Automation and integrations
MIT
No issues found

From the author

Manages Fabric Variable Library items, including definitions, libraryVariables and valueSets overrides. Covers which consumers can reference a variable and with what syntax -- pipelines, notebooks via notebookutils variableLibrary, Dataflow Gen2, Copy Jobs, shortcuts, UDFs and Plan items -- the active value set per workspace or deployment stage, and Git serialization for CI/CD.

— the description by Microsoft

AutoGineer summary

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

The variable-library-cli skill provides a structured interface for managing Microsoft Fabric Variable Library items. It handles the definition of variables, default values, and value set overrides, as well as the operational state of active value sets within workspaces. The skill is organized into three distinct modes—authoring, consumption, and operations—to separate definition management from consumer wiring and workspace deployment state. It is designed to support CI/CD workflows by facilitating Git serialization and ensuring consistent variable resolution across various Fabric consumers like pipelines, notebooks, and Dataflow Gen2.

What it does

Creates and updates Variable Library definitions including variables, types, and defaults.
Manages value set overrides for different deployment stages or environments.
Configures consumer item references to link Variable Library values into pipelines, notebooks, and other Fabric items.
Controls the active value set state for specific workspaces.
Supports Git serialization for CI/CD integration.
Provides guidance on defensive coding practices for variable consumption.

When to use it

When you need to define or modify a central configuration library in Fabric.
When you need to wire a library variable into a pipeline, notebook, or Dataflow Gen2 item.
When you need to switch the active environment configuration (e.g., dev to prod) for a workspace.
When setting up CI/CD pipelines that require automated management of variable definitions.

Advantages

Centralizes configuration management across diverse Fabric consumers.
Enables environment-specific overrides without duplicating logic.
Supports robust CI/CD practices through clear separation of definition and operational planes.
Provides a consistent contract for referencing variables in downstream items.

Usage examples

“Create a Variable Library named AppConfig with a dev and prod value set.”: The agent will use the authoring mode to define the library structure, including variables and the specified value set files, and persist the new item to the workspace.
“Wire the target_path variable into my ingest pipeline.”: The agent will use the consumption mode to provide the correct libraryVariables contract to be added to the pipeline definition.
“Point the prod workspace at the prod value set after deployment.”: The agent will use the operations mode to update the activeValueSetName property for the specified Variable Library item in the production workspace.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/microsoft/variable-library-cli/download

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

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

Documentation by Microsoft

Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry x-ms-fabric-skill: variable-library-cli (az rest: --headers "x-ms-fabric-skill=variable-library-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 a workspace name: list all workspaces, then use JMESPath filtering.
To find the 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.
Variable Library has two planes: definition files in Git, and active value set item state in the workspace. Do not treat the active value set as a Git edit. The definition plane is authoring; the item-state plane is operations.
Variable Library definition requests must omit the format field entirely. Do not send format: null.
Skill disambiguation: use variable-library-cli for every Variable Library concern, including the Variable Library side of a consumer reference. Deep authoring of the consumer item itself belongs elsewhere: pipelines to pipeline-migration, notebooks to spark-cli, Dataflow Gen2 to dataflows-cli, Git lifecycle to git-integration-operations-cli, deployment pipeline mechanics to deployment-pipelines-authoring-cli.
Clarify before creating on an underspecified request. If a "set up / create a Variable Library" request does not name the variables, their types, defaults, and value sets, ask a clarifying question or present structured options before creating anything. Do not fabricate a configuration and silently create the item without confirming intent. (A concrete, fully specified request needs no confirmation.)
When generating consumer code (notebooks, UDFs) that reads a Boolean Variable Library value, coerce it defensively with str(value).lower() == "true". Never use bool(value) on a string: every non-empty string, including "false", is truthy in Python, so bool("false") is always True.
Do not write a value set override whose value equals the variable's default. An override pins the value: once written, later edits to the default no longer reach that value set, so a redundant override silently opts the value set out of inheritance. Omit the override and let the value set inherit. Only override where the value genuinely differs.

Fabric Variable Library -- CLI Skill

This one skill owns Fabric Variable Library items: definitions and value sets, the VL side of consumer references, the active value set item state, and Variable Library CI/CD behavior.

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.

Mode selection

Mode	Use when the request ...	Example triggers	Read this first
`authoring`	creates or changes the library definition: variables, defaults, types, value set override files, `settings.json`	create variable library, add a variable, valueSets, variableOverrides, valueSetsOrder, updateDefinition	references/authoring.md
`consumption`	wires a variable into a consumer item, or explains how a consumer resolves it	libraryVariables, notebookutils variableLibrary, pipeline expression, Dataflow Gen2 / copy job / shortcut / UDF / Plan reference	references/consumption.md
`operations`	reads or switches the active value set, or covers stages, Git serialization and deployment	active value set, activeValueSetName, promote to prod, per-stage values, Git diff, fabric-cicd	references/operations.md

Mode boundary rule

Classify by plane, not by vocabulary. A request that mentions value sets is authoring when it changes the override files and operations when it changes which value set is active in a workspace. Creating valueSets/prod.json is authoring; pointing the prod workspace at it is operations.

consumption covers the Variable Library side of a reference only. Authoring the consumer item's own definition belongs to that item's skill (CRITICAL NOTES 5).

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}/items` with `type: "VariableLibrary"` for a new library, or `POST /v1/workspaces/{ws}/items/{id}/updateDefinition` to persist an edit. Both send base64 definition parts and must omit `format`. Building the JSON locally writes nothing.
`consumption`	the consumer item's own update call, owned by that item's skill. This skill's deliverable is the correct reference contract to place in it.
`operations`	`PATCH /v1/workspaces/{ws}/variableLibraries/{id}` with `{"properties":{"activeValueSetName":"<name>"}}`. This is item state: it does not edit `settings.json`, `variables.json`, or `valueSets/*.json`, and it does not appear in a Git diff.

Before you report the task done, confirm the terminal call returned success and read the artefact back to prove the change landed. For operations, read back with GET /variableLibraries/{id}: the generic /items/{id} omits properties and will not show the active value set.

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
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
Fabric REST with `az rest`	COMMON-CLI.md	Primary access method for this skill
Core Control-Plane REST APIs	COMMON-CORE.md	Pagination, LRO polling, rate limiting
Long-Running Operations (LRO)	COMMON-CLI.md	Create and definition APIs can return 202
VariableLibrary item definition	ITEM-DEFINITIONS-CORE.md	Canonical part paths and field names
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.
Use the canonical part names variables.json, settings.json, and valueSets/<name>.json, with value for defaults and variableOverrides for value set overrides.
Produce every artefact the user asked for, under the name they used, and keep its heading even when the finding is "none".

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.
Generating JSON bodies with Python or jq so base64 payloads are valid UTF-8 and quoting is stable.
Recommending fabric-cicd for full deployment automation rather than hand-rolling it here.

AVOID

Acting from this dispatcher alone -- it intentionally omits the operational detail.
Stringifying value-set overrides. Each variableOverrides[].value must use the variable's NATIVE JSON type; a stringified boolean or number is rejected with InvalidContent (InvalidValueOrTypeMismatch) despite the REST doc listing the field as String.
Using defaultValue, values, or format in Variable Library definitions.
Fabric fab CLI command syntax. It exists, but Variable Library command shapes are not verified here.
Deep-authoring consumer item definitions (CRITICAL NOTES 5).
Re-reading or re-grepping a reference you already loaded; it costs turns and tokens.

Examples

User request	Mode	Reference to read
"Create a Variable Library with a dev and prod value set."	`authoring`	references/authoring.md
"Wire the target_path variable into my ingest pipeline."	`consumption`	references/consumption.md
"Point the prod workspace at the prod value set after deployment."	`operations`	references/operations.md
"Why didn't my Git diff show the value set switch?"	`operations`	references/operations.md
"Add a Boolean flag variable, then read it from a notebook."	`authoring`, then `consumption`	both, one at a time

Files

ATTRIBUTION.mdAdded by AutoGineer885 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md10.7 KiB
apm.yml343 B
references/authoring.md11.0 KiB
references/consumption.md8.8 KiB
references/operations.md4.2 KiB

references/authoring.md

Variable Library -- `authoring` mode

Definition parts, variable types, and create/update by definition.

This reference covers the Variable Library item definition: definition parts, variable types, and create/update by definition. The active value set is item state, not definition, and lives in operations.md. It is grounded in ITEM-DEFINITIONS-CORE.md - VariableLibrary, the Variable Library definition REST article, the Get Variable Library REST API, the Update Variable Library REST API, and Variable Library value sets.

Definition Parts

A Variable Library definition has these serialized parts:

Part	Purpose	Required
`variables.json`	Variable names, types, default `value`, and optional `note`	Yes
`settings.json`	Library settings, especially `valueSetsOrder`	Yes
`valueSets/<name>.json`	Non-default overrides for one value set	Only when using alternate value sets
`.platform`	Common item metadata	Optional

Use the plural path valueSets/. The REST definition article is internally inconsistent in one example that shows valueSet/; the canonical repo doc and the CI/CD Learn article use valueSets/, so use plural and tenant-verify if an API response differs.

variables.json uses value for the default value:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/variables/1.0.0/schema.json",
  "variables": [
    { "name": "target_path", "type": "String", "value": "Files/dev", "note": "Lakehouse folder" },
    { "name": "max_rows", "type": "Integer", "value": 1000 },
    { "name": "enable_debug", "type": "Boolean", "value": true }
  ]
}

settings.json can have an empty or partial valueSetsOrder. Missing valid value set names are appended by the service in alphabetical order on update.

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/settings/1.0.0/schema.json",
  "valueSetsOrder": ["dev", "test", "prod"]
}

A value set file uses variableOverrides, not values:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/valueSet/1.0.0/schema.json",
  "name": "prod",
  "description": "Production overrides",
  "variableOverrides": [
    { "name": "target_path", "value": "Files/prod" },
    { "name": "max_rows", "value": 1000000 }
  ]
}

Include an override only where the value genuinely differs from the variable's default. An override pins the value for that value set: once written, a later change to the default in variables.json no longer reaches it. Writing { "name": "target_path", "value": "Files/dev" } into a dev value set whose default is already Files/dev looks harmless, but it silently opts dev out of inheritance, so the next default change applies everywhere except there. A value set that overrides nothing is valid and should carry an empty variableOverrides array.

Definition Plane and Item-State Plane

Variable Library authoring has two different planes:

Plane	What changes	Serialized to Git	API shape
Definition plane	Variables, default values, value set files, value set order	Yes	`create item`, `getDefinition`, `updateDefinition`
Item-state plane	Which value set is active in one workspace	No	`GET/PATCH /variableLibraries/{id}`

Editing a variable's default value or a value set override is a definition edit. Selecting the active value set is workspace item state. Deployment intentionally does not overwrite the selected active value set in each stage, and deployment pipeline comparison does not mark a simple active value set switch as source difference. This behavior is documented in Variable Library CI/CD and value sets.

Variable Types

The REST definition type table and ITEM-DEFINITIONS-CORE.md list these canonical types:

Type	Value shape
`Boolean`	JSON boolean
`DateTime`	ISO 8601 string
`Number`	JSON number
`Integer`	JSON integer
`String`	JSON string
`ItemReference`	`{ "workspaceId": "<guid>", "itemId": "<guid>" }`

ConnectionReference is a newer advanced type documented in Variable library connection reference. That Learn article shows type: "connectionReference" and value: { "connectionId": "<id>" }. Because it is absent from the REST definition type table, use it only with tenant verification and cite the connection reference article when doing so. Microsoft Learn's Variable types page also lists a Guid type (mapping to pipeline String); it is likewise absent from the REST definition table and common/, so treat it as verify-on-tenant.

In variables.json, a variable's default value uses its native JSON type (true for Boolean, 1000 for Integer). In valueSets/*.json, each variableOverrides[].value uses the same native JSON type as the variable it overrides (Boolean -> true/false, Integer/Number -> a number, String -> a string). Although the REST definition article lists VariableOverride.value as String, the live API rejects a stringified boolean/number override with InvalidContent (InvalidValueOrTypeMismatch) (verified on tenant 2026-07-02). Use native types.

Create and Update by Definition

Follow shared authentication, token, and LRO handling from COMMON-CLI.md. Examples assume WS_ID and VL_ID are already resolved.

Create a VariableLibrary item with definition through the generic item create endpoint. Do not include definition.format.

python3 - <<'PY' > create-variable-library.json
import base64, json
parts = {
    "variables.json": {
        "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/variables/1.0.0/schema.json",
        "variables": [
            {"name": "target_path", "type": "String", "value": "Files/dev"},
            {"name": "enable_debug", "type": "Boolean", "value": True}
        ]
    },
    "settings.json": {
        "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/settings/1.0.0/schema.json",
        "valueSetsOrder": ["dev", "prod"]
    },
    "valueSets/dev.json": {
        "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/valueSet/1.0.0/schema.json",
        "name": "dev",
        # dev matches both variable defaults, so it overrides nothing and keeps inheriting them
        "variableOverrides": []
    },
    "valueSets/prod.json": {
        "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/valueSet/1.0.0/schema.json",
        "name": "prod",
        "variableOverrides": [
            {"name": "target_path", "value": "Files/prod"},
            {"name": "enable_debug", "value": False}
        ]
    }
}
body = {
    "displayName": "AppConfig",
    "type": "VariableLibrary",
    "definition": {
        "parts": [
            {
                "path": path,
                "payload": base64.b64encode(json.dumps(payload, separators=(",", ":")).encode()).decode(),
                "payloadType": "InlineBase64"
            }
            for path, payload in parts.items()
        ]
    }
}
print(json.dumps(body, indent=2))
PY

az rest \
  --method post \
  --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/items" \
  --headers "Content-Type=application/json" \
  --body @create-variable-library.json

To update an existing definition, get the current definition, decode the parts, modify the relevant JSON, re-encode all required parts into update-variable-library-definition.json (same base64-parts structure and > file redirect pattern as the create snippet above), then call updateDefinition:

az rest \
  --method post \
  --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/items/$VL_ID/getDefinition" \
  --body '{}'

az rest \
  --method post \
  --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/items/$VL_ID/updateDefinition" \
  --headers "Content-Type=application/json" \
  --body @update-variable-library-definition.json

Troubleshooting (authoring)

Symptom	Likely cause	Fix
Definition request is rejected with a format-related error	Variable Library does not support `definition.format`	Omit the `format` field entirely, including `null`
Value set overrides are ignored or invalid	Used `values` instead of `variableOverrides`, or file name does not match the value set name	Use `valueSets/<name>.json` with `name` and `variableOverrides`
Create fails: `InvalidContent (InvalidValueOrTypeMismatch)`	A value-set `variableOverrides[].value` was a string for a Boolean/Integer/Number variable	Use the variable's native JSON type in overrides (`false`, `1000000`), not a string. The REST doc's `String` type is misleading (verified on tenant)
Default value is missing after create	Used `defaultValue` instead of `value` in `variables.json`	Use `value` for defaults
`settings.json` validation fails	`valueSetsOrder` includes a name with no matching `valueSets/<name>.json` file	Add the file or remove the name from `valueSetsOrder`

Verified on tenant (2026-07-02)

Definition part path is valueSets/<name>.json (plural), confirmed by reading the stored definition back.
variableOverrides[].value must use the variable's native JSON type; a stringified boolean/number override is rejected with InvalidContent (InvalidValueOrTypeMismatch).
Create-by-definition via POST /workspaces/{ws}/items (type VariableLibrary, no format) returns 202 and completes via LRO.

Still to verify on tenant

ConnectionReference (type: "connectionReference", value: { "connectionId": "<id>" }) and Guid are documented but absent from the REST definition type table. Confirm the shape before automating.
Fabric fab CLI exists, but this skill does not provide Variable Library fab syntax because the command shape is not verified here.

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

No issues found by our static scan· No issues found

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