microsoft/variable-library-cli

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

1. To find the workspace details (including its ID) from a workspace name: list all workspaces, then use JMESPath filtering.
2. 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.
3. 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.
4. Variable Library definition requests must omit the format field entirely. Do not send format: null.
5. 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.
6. 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.)
7. 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.
8. 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 |