
Updated 4 November 2026: this post originally used bicep validate, which is not a Bicep CLI command, and a -o flag that bicep build rejects. Both are corrected below and the commands were checked against Bicep CLI 0.48.1 and Microsoft Learn. The az deployment group commands were checked against their documentation and help output, not run against a live subscription.
Azure Bicep is a declarative language for deploying Azure resources. This post walks through the commands that take a Bicep file from a local edit to a deployment: linting, building, validating against Azure, previewing changes with what-if, and deploying.
1. Lint the Bicep file
The Bicep CLI has a lint command that checks a file against the linter rules without touching Azure:
bicep lint ./main.bicep
With the Azure CLI, the equivalent is az bicep lint --file ./main.bicep. It exits with 0 when the file is clean.
2. Build to ARM JSON (optional)
bicep build converts a Bicep file to an ARM template. You normally don’t need it, because the Azure CLI compiles Bicep for you when you deploy. Run it when you want to inspect the generated JSON:
bicep build ./main.bicep --outfile ./main.json
The output flag is --outfile (or --outdir for a directory). There is no -o short form: bicep build ./main.bicep -o ./main.json fails with “Unrecognized command or argument ‘-o'” (tested on Bicep 0.48.1).
3. Validate against Azure
There is no bicep validate command. The Bicep CLI’s commands are build, lint, format, restore, publish, snapshot and a few others. To check that Azure Resource Manager would accept the template, use the Azure CLI:
az deployment group validate --resource-group myResourceGroup --template-file ./main.bicep
--template-file accepts a .bicep file directly, so you don’t need the build step first. This needs an Azure login and an existing resource group.
4. Preview changes with what-if
az deployment group what-if --resource-group myResourceGroup --template-file ./main.bicep
The output marks each resource as create, modify, delete, ignore or no change. For scripts, add --no-pretty-print to get a JSON object you can inspect. --result-format ResourceIdOnly trims the output to resource IDs instead of the full payloads.
5. Deploy
az deployment group create --resource-group myResourceGroup --template-file ./main.bicep
--confirm-with-what-if shows the what-if result and asks for confirmation before it deploys.
A pipeline-friendly sequence
# 1. Lint (no Azure needed)
bicep lint ./main.bicep
# 2. Ask Azure whether the template is valid
az deployment group validate -g myResourceGroup -f ./main.bicep
# 3. Preview the changes
az deployment group what-if -g myResourceGroup -f ./main.bicep
# 4. Deploy
az deployment group create -g myResourceGroup -f ./main.bicep
Steps 2 to 4 point at the .bicep file; the Azure CLI compiles it for you.