Rediger

Del via

Bicep CLI commands

This article describes the commands you can use in the Bicep CLI. You can execute these commands by using the Azure CLI or by directly invoking Bicep CLI commands. Each method requires a distinct installation process. For more information about installations, see Azure CLI and Azure PowerShell.

This guidance shows how to run the commands in the Azure CLI. When running commands in the Azure CLI, start them with az. If you're not using the Azure CLI, run the commands without az at the start of each. For example, az bicep build becomes bicep build, and az bicep version becomes bicep --version.

build

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 the following Bicep features automatically enables language version 2.0 code generation:

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 build main.bicep

The next example saves main.json to a different directory:

bicep build main.bicep --outdir c:\jsontemplates

The following example specifies the name and location of the file to create:

bicep build main.bicep --outfile c:\jsontemplates\azuredeploy.json

To print the file to stdout, use:

bicep build main.bicep --stdout

If your Bicep file includes a module that references an external registry, the build command automatically calls restore. The restore command gets the file from the registry and stores it in the local cache.

Note

The restore command doesn't refresh the cache. For more information, see restore.

To prevent automatic restore, use the --no-restore switch:

bicep build --no-restore <bicep-file>

To use the --no-restore switch, you must have Bicep CLI version 0.4.X or later.

The build process with the --no-restore switch fails if one of the external modules isn't already cached:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" hasn't been restored.

When you get this error, either run the build command without the --no-restore switch, or run bicep restore first.

build-params

The build-params command builds a .bicepparam file into a JSON parameters file:

bicep build-params params.bicepparam

This command converts a params.bicepparam parameters file into a params.json JSON parameters file.

decompile

The decompile command converts a JSON ARM template to a Bicep file:

bicep decompile 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.

For more information about using this command, see Decompile JSON ARM template to Bicep.

decompile-params

The decompile-params command decompiles a JSON parameters file to a .bicepparam parameters file.

bicep decompile-params azuredeploy.parameters.json --bicep-file ./dir/main.bicep

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 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 format main.bicep

generate-params

The generate-params command builds a parameters file from the given Bicep file and updates it if there's an existing parameters file.

bicep generate-params main.bicep --output-format bicepparam --include-params all

This command creates a Bicep parameters file named main.bicepparam. The parameters file contains all parameters in the Bicep file, whether configured with default values or not.

bicep generate-params main.bicep --outfile main.parameters.json

This command creates a parameters file named main.parameters.json. The parameters file only contains the parameters without default values configured in the Bicep file.

install

The install command adds the Bicep CLI to your local environment, and it's only available through the Azure CLI. For more information, see Install Bicep tools.

To install the latest version, use:

N/A

To install a specific version, use the following command:

N/A

jsonrpc

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 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
  • <length> is the length of the <message> string, including the trailing \r\n\r\n.
  • <message> is the raw JSON message.

For example:

Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n

The following methods are available through the JSON-RPC interface:

  • bicep/format

    Formats a Bicep file.

    • The request:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bicep/format",
  "params": {
    "path": "/path/to/file.bicep"
  }
}

    • The response:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "diagnostics": [],
    "contents": "param foo string\n\nresource storage 'Microsoft.Storage/storageAccounts@2025-01-01' = {\n  name: 'mystorageaccount'\n  location: 'East US'\n}\n"
  }
}

      On success, "success": true is returned, with contents holding the formatted Bicep source. On failure, "success": false with diagnostics describing the failure.

  • bicep/version

    Returns the version of the Bicep CLI.

    • The request:

      {
  "jsonrpc": "2.0",
  "id": 0,
  "method": "bicep/version",
  "params": {}
}

    • The response:

      {
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "version": "0.24.211"
  }
}

For the available methods and request and response bodies, see ICliJsonRpcProtocol.cs. For an example establishing a JSONRPC connection and interacting with Bicep files programmatically by using Node, see jsonrpc.test.ts.

Usage for named pipe

Use the following syntax to connect to an existing named pipe as a JSONRPC client:

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> is an existing named pipe to connect the JSONRPC client to.

To connect to a named pipe on macOS or Linux:

bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock

To connect to a named pipe on Windows:

bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`

For more examples, see C# and node.js.

Usage for TCP socket

Use the following syntax to connect to an existing TCP socket as a JSONRPC client:

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> is the socket number to which the JSONRPC client connects.

To connect to a TCP socket:

bicep jsonrpc --socket 12345

Usage for stdin and stdout

To run the JSONRPC interface, use the following syntax. Use stdin and stdout for messages:

bicep jsonrpc --stdio

lint

The lint command returns the errors and linter rule violations of a Bicep file.

bicep lint main.bicep

If your Bicep file includes a module that references an external registry, the lint command automatically calls restore. The restore command gets the file from the registry and stores it in the local cache.

Note

The restore command doesn't refresh the cache. For more information, see restore.

To prevent automatic restore, use the --no-restore switch:

bicep lint --no-restore <bicep-file>

The lint process with the --no-restore switch fails if one of the external modules isn't already cached:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

When you get this error, either run the lint command without the --no-restore switch or run bicep restore first.

list-versions

The list-versions command returns all available versions of the Bicep CLI. Use this command to see if you want to upgrade or install a new version. This command is only available through the Azure CLI.

N/A

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

After publishing the file to the registry, you can reference it in a module.

You must have Bicep CLI version 0.14.X or later to use the publish command and the --documentationUri/-d parameter.

To publish a module to a registry, use:

bicep publish <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>

For example:

bicep publish storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

The publish command doesn't recognize aliases specified in a bicepconfig.json file. Provide the full module path.

Warning

Publishing to the same target overwrites the old module. Increment the version when updating.

restore

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 for authenticating to the registry in the Bicep config file.

To use the restore command, you must have Bicep CLI version 0.14.X or later.

To manually restore the external modules for a file, use:

bicep restore <bicep-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:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

You find the local cache in:

  • On Windows

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

  • On Linux

    /home/<username>/.bicep

  • On Mac

    ~/.bicep

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 snapshot --mode overwrite <bicep-param-file>

The following JSON file shows a snapshot example:

{
  "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 command but entirely local.

bicep snapshot --mode validate <bicep-param-file>

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.

Bicep CLI 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 snapshot main.bicepparam \
  --subscription-id 00000000-0000-0000-0000-000000000000 \
  --resource-group my-temp-rg \
  --location eastus \
  --mode overwrite

upgrade

The upgrade command updates your installed version with the latest version. This command is only available through the Azure CLI.

N/A

version

The version command returns your installed version:

bicep --version

If you didn't install the Bicep CLI, you see an error message stating that the Bicep CLI wasn't found.

The command shows the version number:

Bicep CLI version 0.29.45 (57a44c0230)

Next steps

To learn more about deploying a Bicep file, see:

  • Last updated on