Merge pull request #312531 from mumian/0302-snapshot

Document Bicep CLI snapshot

Author: prmerger-automator[bot]

articles/azure-resource-manager/bicep/bicep-cli.md

@@ -2,7 +2,7 @@
 title: Bicep CLI commands 
 description: Learn about the commands that you can use in the Bicep CLI. These commands include building JSON Azure Resource Manager templates from Bicep.
 ms.topic: reference
-ms.date: 12/02/2025
+ms.date: 03/02/2026
 ms.custom: devx-track-azurecli, devx-track-bicep, devx-track-arm-template
 ---
 
@@ -16,14 +16,14 @@ This guidance shows how to run the commands in the Azure CLI. When running comma
 
 The `build` command converts a Bicep file to a JSON Azure Resource Manager template (ARM template). Typically, you don't need to run this command because it runs automatically when you deploy a Bicep file. Run it manually when you want to see the JSON ARM template that's created from your Bicep file.
 
-Using any of following Bicep features automatically enables language version 2.0 code generation:
+Using any of the following Bicep features automatically enables language version 2.0 code generation:
 
 * [user-defined types](../bicep/user-defined-data-types.md)
 * [user-defined functions](../bicep/user-defined-functions.md)
 * [compile-time imports](../bicep/bicep-import.md)
 * [experimental features](../bicep/bicep-config.md#enable-experimental-features)
 
-The following example converts a Bicep file named _main.bicep_ to an ARM template named _main.json_. The new file is created in the same directory as the Bicep file:
+The following example converts a Bicep file named *main.bicep* to an ARM template named *main.json*. The new file is created in the same directory as the Bicep file:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -39,7 +39,7 @@ az bicep build --file main.bicep
 
 ---
 
-The next example saves _main.json_ to a different directory:
+The next example saves *main.json* to a different directory:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -55,7 +55,7 @@ az bicep build --file main.bicep --outdir c:\jsontemplates
 
 ---
 
-The next example specifies the name and location of the file to be created:
+The following example specifies the name and location of the file to create:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -92,7 +92,7 @@ If your Bicep file includes a module that references an external registry, the `
 > [!NOTE]
 > The `restore` command doesn't refresh the cache. For more information, see [restore](#restore).
 
-To not call restore automatically, use the `--no-restore` switch:
+To prevent automatic restore, use the `--no-restore` switch:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -156,7 +156,7 @@ az bicep decompile --file main.json
 
 ---
 
-This command creates a file named _main.bicep_ in the same directory as _main.json_. If _main.bicep_ exists in the same directory, use the **--force** switch to overwrite the existing Bicep file.
+This command creates a file named _main.bicep_ in the same directory as _main.json_. If _main.bicep_ exists in the same directory, use the `--force` switch to overwrite the existing Bicep file.
 
 For more information about using this command, see [Decompile JSON ARM template to Bicep](decompile.md).
 
@@ -178,11 +178,11 @@ az bicep decompile-params --file azuredeploy.parameters.json --bicep-file ./dir/
 
 ---
 
-This command decompiles an _azuredeploy.parameters.json_ parameters file into an _azuredeploy.parameters.bicepparam_ file. `--bicep-file` specifies the path to the Bicep file (relative to the `.bicepparam` file) that's referenced in the `using` declaration.
+This command decompiles an _azuredeploy.parameters.json_ parameters file into an _azuredeploy.parameters.bicepparam_ file. Use `--bicep-file` to specify the path to the Bicep file (relative to the `.bicepparam` file) that's referenced in the `using` declaration.
 
 ## format
 
-The `format` command formats a Bicep file so that it follows the recommended style conventions. Think of it like a "code formatter" or "prettier" for your Bicep files. It has the same function as the `SHIFT+ALT+F` shortcut in Visual Studio Code.
+The `format` command formats a Bicep file so that it follows the recommended style conventions. Think of it as a code formatter or "prettier" for your Bicep files. It has the same function as the `SHIFT+ALT+F` shortcut in Visual Studio Code.
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -200,7 +200,7 @@ az bicep format --file main.bicep
 
 ## generate-params
 
-The `generate-params` command builds a parameters file from the given Bicep file, updates if there's an existing parameters file.
+The `generate-params` command builds a parameters file from the given Bicep file and updates it if there's an existing parameters file.
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -252,7 +252,7 @@ az bicep install
 
 ---
 
-To install a specific version:
+To install a specific version, use the following command:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -268,9 +268,9 @@ az bicep install --version v0.37.4
 
 ## jsonrpc
 
-The `jsonrpc` command enables running the Bicep CLI with a JSON-RPC interface, allowing for programmatic interaction with structured output and avoiding cold-start delays when compiling multiple files. This setup also supports building libraries to interact with Bicep files programmatically in non-.NET languages.
+The `jsonrpc` command runs the Bicep CLI with a JSON-RPC interface. By using this interface, you can interact programmatically with structured output. You also avoid cold-start delays when compiling multiple files. This setup supports building libraries to interact with Bicep files programmatically in non-.NET languages.
 
-The wire format for sending and receiving input/output is header-delimited, using the following structure, where `\r` and `\n` represent carriage return and line feed characters:
+The wire format for sending and receiving input and output is header-delimited. It uses the following structure, where `\r` and `\n` represent carriage return and line feed characters:
 
 ```
 Content-Length: <length>\r\n\r\n<message>\r\n\r\n
@@ -347,8 +347,8 @@ The following methods are available through the JSON-RPC interface:
     }
     ```
 
-For the available methods & request/response bodies, see [`ICliJsonRpcProtocol.cs`](https://github.com/Azure/bicep/blob/main/src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs).
-For an example establishing a JSONRPC connection and interacting with Bicep files programmatically using Node, see [`jsonrpc.test.ts`](https://github.com/Azure/bicep/blob/main/src/Bicep.Cli.E2eTests/src/local/jsonrpc.test.ts).
+For the available methods and request and response bodies, see [`ICliJsonRpcProtocol.cs`](https://github.com/Azure/bicep/blob/main/src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs).
+For an example establishing a JSONRPC connection and interacting with Bicep files programmatically by using Node, see [`jsonrpc.test.ts`](https://github.com/Azure/bicep/blob/main/src/Bicep.Cli.E2eTests/src/local/jsonrpc.test.ts).
 
 ### Usage for named pipe
 
@@ -368,7 +368,7 @@ N/A
 
 ---
 
-To connect to a named pipe on OSX/Linux:
+To connect to a named pipe on macOS or Linux:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -432,7 +432,7 @@ N/A
 
 ### Usage for stdin and stdout
 
-Use the following syntax and `stdin` and `stdout` for messages to run the JSONRPC interface:
+To run the JSONRPC interface, use the following syntax. Use `stdin` and `stdout` for messages:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -469,7 +469,7 @@ If your Bicep file includes a module that references an external registry, the `
 > [!NOTE]
 > The `restore` command doesn't refresh the cache. For more information, see [restore](#restore).
 
-To not call restore automatically, use the `--no-restore` switch:
+To prevent automatic restore, use the `--no-restore` switch:
 
 # [Bicep CLI](#tab/bicep-cli)
 
@@ -548,7 +548,7 @@ The command returns an array of available versions:
 
 ## publish
 
-The `publish` command adds a module to a registry. The Azure container registry must exist and the account publishing to the registry must have the correct permissions. For more information about setting up a module registry, see [Use private registry for Bicep modules](private-module-registry.md). To publish a module, the account must have the correct profile and permissions to access the registry. You can configure the profile and credential precedence for authenticating to the registry in the [Bicep config file](./bicep-config-modules.md#configure-profiles-and-credentials).
+The `publish` command adds a module to a registry. The Azure container registry must exist, and the account publishing to the registry must have the correct permissions. For more information about setting up a module registry, see [Use private registry for Bicep modules](private-module-registry.md). To publish a module, the account must have the correct profile and permissions to access the registry. You can configure the profile and credential precedence for authenticating to the registry in the [Bicep config file](./bicep-config-modules.md#configure-profiles-and-credentials).
 
 After publishing the file to the registry, you can [reference it in a module](modules.md#file-in-registry).
 
@@ -590,11 +590,11 @@ az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bic
 The `publish` command doesn't recognize aliases specified in a [_bicepconfig.json_ file](bicep-config-modules.md). Provide the full module path.
 
 > [!WARNING]
-> Publishing to the same target overwrites the old module. We recommend that you increment the version when updating.
+> Publishing to the same target overwrites the old module. Increment the version when updating.
 
 ## restore
 
-When your Bicep file uses modules that are published to a registry, the `restore` command gets copies of all the required modules from the registry. It stores those copies in a local cache. A Bicep file can only be built when the external files are available in the local cache. Normally, running restore isn't necessary as it's automatically triggered by the build process.
+When your Bicep file uses modules that you publish to a registry, the `restore` command gets copies of all the required modules from the registry. It stores those copies in a local cache. A Bicep file can only be built when the external files are available in the local cache. Normally, running restore isn't necessary as it's automatically triggered by the build process.
 
 To restore external modules to the local cache, the account must have the correct profile and permissions to access the registry. You can configure the [profile and credential precedence](./bicep-config-modules.md#configure-profiles-and-credentials) for authenticating to the registry in the Bicep config file.
 
@@ -616,7 +616,7 @@ az bicep restore --file <bicep-file> [--force]
 
 ---
 
-The Bicep file you provide is the file you wish to deploy. It must contain a module that links to a registry. For example, you can restore the following file:
+The Bicep file you provide is the file you want to deploy. It must contain a module that links to a registry. For example, you can restore the following file:
 
 ```bicep
 module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
@@ -627,7 +627,7 @@ module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
 }
 ```
 
-The local cache is found in:
+You find the local cache in:
 
 * On Windows
 
@@ -649,6 +649,123 @@ The local cache is found in:
 
 The `restore` command doesn't refresh the cache if a module is already cached. To refresh the cache, you can either delete the module path from the cache or use the `--force` switch with the `restore` command.
 
+## snapshot
+
+By using Bicep CLI v0.41.2 or newer, you can use the `snapshot` command to create a normalized, deterministic representation of a Bicep deployment from a `.bicepparam` file. You can compare this snapshot with later snapshots to understand what changes a refactor would cause, without deploying anything to Azure. This command is particularly useful for:
+
+* **Visual Diffs**: Seeing exactly how a refactor (like moving code into a module) changes the underlying resource definitions.
+* **Complex Expressions**: Understanding what a complex string or variable actually evaluates to before deployment.
+* **CI/CD Validation**: Automatically catching unintended changes in infrastructure logic during pull requests.
+
+### Create a snapshot
+
+This command generates a `.snapshot.json` file. This file is "normalized," meaning it removes noise like module boundaries so you can focus on the resources themselves.
+
+#### [Bicep CLI](#tab/bicep-cli)
+
+```bicepcli
+bicep snapshot --mode overwrite <bicep-param-file>
+```
+
+#### [Azure CLI](#tab/azure-cli)
+
+`az bicep snapshot` doesn't exist. You must run `bicep snapshot` directly.
+
+---
+
+The following JSON file shows a snapshot example:
+
+```json
+{
+  "predictedResources": [
+    {
+      "id": "[format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]",
+      "type": "Microsoft.Storage/storageAccounts",
+      "name": "stmyappstorage001",
+      "apiVersion": "2025-01-01",
+      "location": "eastus",
+      "sku": {
+        "name": "Standard_LRS"
+      },
+      "kind": "StorageV2"
+    }
+  ],
+  "diagnostics": []
+}
+```
+
+### Validate changes
+
+After creating a snapshot, run the command in validate mode. It compares your current Bicep code against the saved snapshot and shows a visual diff, much like the [what-if](./deploy-what-if.md) command but entirely local.
+
+#### [Bicep CLI](#tab/bicep-cli)
+
+```bicepcli
+bicep snapshot --mode validate <bicep-param-file>
+```
+
+#### [Azure CLI](#tab/azure-cli)
+
+`az bicep snapshot` doesn't exist. You must run `bicep snapshot` directly.
+
+---
+
+A sample output looks like:
+
+```
+PS C:\bicep> bicep snapshot --mode validate main.bicepparam
+Snapshot validation failed. Expected no changes, but found the following:
+
+Scope: <unknown>
+
+  ~ [format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]
+    ~ apiVersion: "2025-01-01" => "2025-06-01"
+    ~ sku.name:   "Standard_LRS" => "Standard_GRS"
+```
+
+"Snapshot validation failed" indicates differences between the two snapshots.
+
+Snapshot and What-if have these differences:
+
+| Feature | `bicep snapshot` | `az deployment group what-if` |
+| :--- | :--- | :--- |
+| **Execution** | **Local only** (Offline) | **Cloud-based** (Online) |
+| **Comparison** | Compares code vs. a saved file | Compares code vs. live Azure state |
+| **Speed** | Extremely fast | Slower (requires API calls) |
+| **Use Case** | Refactoring and logic testing | Final pre-deployment check |
+
+### Provide context
+
+When running bicep snapshot, the CLI performs a local evaluation of your code. Since it doesn't talk to Azure, it cannot "ask" the cloud for your Subscription ID or the current Resource Group name.
+
+If your code uses environment functions (like `subscription().id`), the snapshot will fail or return placeholders unless you provide specific context via CLI arguments.
+
+To simulate a real deployment environment, you can pass the following flags:
+
+| Argument | Purpose | Example Value |
+| :--- | :--- | :--- |
+| `--subscription-id` | Replaces the value returned by `subscription().subscriptionId` | `00000000-1111-2222-3333-444444444444` |
+| `--resource-group` | Replaces the value returned by `resourceGroup().name` | `my-production-rg` |
+| `--location` | Sets the default location for `deployment().location` | `westeurope` |
+| `--tenant-id` | Replaces the value returned by `tenant().tenantId` | `72f988bf-86f1-41af-91ab-2d7cd011db47` |
+| `--management-group` | Replaces the value returned by `managementGroup().name` | `my-corp-mg` |
+
+#### [Bicep CLI](#tab/bicep-cli)
+
+```bicepcli
+bicep snapshot main.bicepparam \
+  --subscription-id 00000000-0000-0000-0000-000000000000 \
+  --resource-group my-temp-rg \
+  --location eastus \
+  --mode overwrite
+```
+
+#### [Azure CLI](#tab/azure-cli)
+
+`az bicep snapshot` doesn't exist. You must run `bicep snapshot` directly.
+
+---
+
 ## upgrade
 
 The `upgrade` command updates your installed version with the latest version. This command is only available through the Azure CLI.
@@ -675,7 +792,7 @@ The `version` command returns your installed version:
 bicep --version
 ```
 
-If the Bicep CLI hasn't been installed, you'll see an error message stating that the Bicep CLI wasn't found.
+If you didn't install the Bicep CLI, you see an error message stating that the Bicep CLI wasn't found.
 
 # [Azure CLI](#tab/azure-cli)
 

articles/azure-resource-manager/bicep/deploy-what-if.md

@@ -2,7 +2,7 @@
 title: 'Bicep What-If: Preview Changes Before Deployment'
 description: Determine what changes will happen to your resources before deploying a Bicep file.
 ms.topic: article
-ms.date: 01/07/2026
+ms.date: 03/03/2026
 ms.custom:
   - devx-track-bicep, devx-track-azurecli, devx-track-azurepowershell
   - ai-gen-docs-bap
@@ -15,6 +15,8 @@ ms.custom:
 
 Before deploying a Bicep file, you can preview the changes that will happen. Azure Resource Manager provides the what-if operation to let you see how resources will change if you deploy the Bicep file. The what-if operation doesn't make any changes to existing resources. Instead, it predicts the changes if the specified Bicep file is deployed.
 
+Similar to what-if, the [`bicep snapshot`](./bicep-cli.md#snapshot) command performs local-only testing by generating and comparing a normalized JSON representation of your infrastructure to catch unintended logic changes without requiring an Azure connection. For a comparison, see [Comparison snapshot vs what-if](./bicep-cli.md#validate-changes).
+
 You can use the what-if operation with [Visual Studio Code](./deploy-visual-studio-code.md#deployment-pane), Azure PowerShell, Azure CLI, or REST API operations. What-if is supported for resource group, subscription, management group, and tenant level deployments.
 
 During What-If operations, the evaluation and expansion of `templateLink` aren't supported. As a result, any resources deployed using template links within nested deployments, including template spec references, won't be visible in the What-If operation results.
@@ -125,7 +127,7 @@ For REST API, use:
 
 You can use the what-if operation through the Azure SDKs.
 
-- For Python, use [what-if](/python/api/azure-mgmt-resource/azure.mgmt.resource.resources.v2019_10_01.operations.deploymentsoperations#what-if-resource-group-name--deployment-name--properties--location-none--custom-headers-none--raw-false--polling-true----operation-config-).
+- For Python, use [what-if](/python/api/azure-mgmt-resource-deployments/azure.mgmt.resource.deployments.models.whatifchange).
 - For Java, use [DeploymentWhatIf Class](/java/api/com.azure.resourcemanager.resources.models.deploymentwhatif).
 - For .NET, use [DeploymentWhatIf Class](/dotnet/api/microsoft.azure.management.resourcemanager.models.deploymentwhatif).