Understanding Bicep CLI

Hello Readers,

This article describes the commands you can use in the Bicep CLI. You must have the Bicep CLI installed to run the commands.

This article shows how to run the commands in Azure CLI. If you’re not using Azure CLI, run the commands without az at the start of the command. For example, az bicep version becomes bicep version.

build

The build command converts a Bicep file to an 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 ARM template JSON that is created from your Bicep file.

The following example converts a Bicep file named your_filename_here.bicep to an ARM template named main.json. The new file is created in the same directory as the Bicep file.

az bicep build --file your_filename_here.bicep

The next example saves main.json to a different directory

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

The next example specifies the name and location of the file to create

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

To print the file to stdout, use:

az bicep build --file 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.

To not call restore automatically, use the --no-restore switch:

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

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" has not been restored.

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

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

decompile

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

az bicep decompile --file main.json

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

install

The install the command adds the Bicep CLI to your local environment. For more information, see Install Bicep tools.

To install the latest version, use:

az bicep install

To install a specific version:

az bicep install --version v0.3.255

list-versions

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

az bicep list-versions

The command returns an array of available versions.

[
  "v0.4.1",
  "v0.3.539",
  "v0.3.255",
  "v0.3.126",
  "v0.3.1",
  "v0.2.328",
  "v0.2.317",
  "v0.2.212",
  "v0.2.59",
  "v0.2.14",
  "v0.2.3",
  "v0.1.226-alpha",
  "v0.1.223-alpha",
  "v0.1.37-alpha",
  "v0.1.1-alpha"
]

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.

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

To use the publish command, you must have Bicep CLI version 0.4.1008 or later.

To publish a module to a registry, use:

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

For example:

az bicep publish storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1

The publish command doesn’t recognize aliases that you’ve defined in a bicepconfig.json file. Provide the full module path.

 Warning

Publishing to the same target overwrites the old module. We recommend that you 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. Typically, you don’t need to run restore because it’s called automatically by build.

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

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

az bicep restore <bicep-file>

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:

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

The local cache is found at:

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

upgrade

The upgrade command updates your installed version with the latest version.

az bicep upgrade

version

The version the command returns your installed version.

az bicep version

The command shows the version number.

Bicep CLI version 0.4.1 (e2387595c9)

If you haven’t installed Bicep CLI, you see an error indicating Bicep CLI wasn’t found.