Tips to Use the Azure CLI Successfully

  • 5 minutes

In this module, you learned to choose an environment, install Azure CLI, execute Azure CLI commands interactively, and create a Bash script. Let's take our learning one step further and focus on how to use Azure CLI successfully. This unit teaches you how Azure CLI works behind the command line and gives you tips for troubleshooting.

Tip

This module is an advanced-level course, and this unit takes you deep into Azure CLI. If you're new to command-line programming, focus on the concepts. The details become easier to understand as you gain experience. Don't give up!

Understand Azure CLI API calls

Executing behind the Azure portal's graphical user interface and Azure CLI's command line are API calls. You can expose Azure CLI's API calls by using the --debug parameter. Here's what happens when you create a new resource group:

az group create --location westus2 --name myResourceGroupName --debug

Here's the terminal output from Azure Cloud Shell with some lines omitted for brevity. Notice this important output:

  • Command arguments: It's the scripting language, not Azure CLI, that parses command arguments (parameters). This output property is the first place to look when a command results in an error.
  • azlogging: This path is where your log file is stored.
  • Request headers: These headers are the parameter values passed by the PUT command.
  • Response content: This output is what is returned to the console without the full --debug output.
cli.knack.cli: Command arguments: ['group', 'create', '--location', 'westus2', '--name', 'myResourceGroupName', '--debug']
cli.knack.cli: __init__ debug log:
...
cli.knack.cli: Event: CommandInvoker.OnPreCommandTableCreate []
cli.azure.cli.core: Modules found from index for 'group': ['azure.cli.command_modules.resource']
cli.azure.cli.core: Loading command modules:
...
cli.azure.cli.core: Loaded 53 groups, 233 commands.
cli.azure.cli.core: Found a match in the command table.
cli.azure.cli.core: Raw command  : group create
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/2025-10-08.21-47-27.group_create.5217.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/myResourceGroupName?api-version=2022-09-01'
cli.azure.cli.core.sdk.policies: Request method: 'PUT'
cli.azure.cli.core.sdk.policies: Request headers:
cli.azure.cli.core.sdk.policies:     'Content-Type': 'application/json'
cli.azure.cli.core.sdk.policies:     'Content-Length': '23'
cli.azure.cli.core.sdk.policies:     'Accept': 'application/json'
cli.azure.cli.core.sdk.policies:     'x-ms-client-request-id': 'c79caddc-ed78-11ef-8a83-00155dbc433c'
cli.azure.cli.core.sdk.policies:     'CommandName': 'group create'
cli.azure.cli.core.sdk.policies:     'ParameterSetName': '--location --name --debug'
...
cli.azure.cli.core.sdk.policies: Response content:
...
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroupName",
  "location": "westus2",
  "managedBy": null,
  "name": "myResourceGroupName",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}
cli.knack.cli: Event: Cli.SuccessfulExecute []
cli.knack.cli: Event: Cli.PostExecute [<function AzCliLogging.deinit_cmd_metadata_logging at 0x7f98a6bc7820>]
az_command_data_logger: exit code: 0
...

Key insights from debug output

  • Command parsing: The scripting language (not Azure CLI) parses arguments. Look here first when troubleshooting.
  • Log file location: Find detailed logs at the path shown in azlogging for post-mortem analysis.
  • API details: See the actual REST API call being made, including the HTTP method (PUT, GET, etc.).
  • Exit code: A value of 0 indicates success; non-zero values indicate errors.

Some Azure CLI commands perform multiple actions. Use --debug to see each command Azure CLI is executing. Even more useful, use --debug to troubleshoot why an Azure CLI script is producing unexpected results.

Troubleshooting with --debug

How many times as a developer have you thought, "This task should be so simple! Why isn't my script working?" When you receive unexpected results from Azure CLI commands, the --debug parameter is your friend! Let's work through an example of a company with 100 Azure storage accounts. You need to find those accounts where blob public access is enabled.

# Bash script - INCORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == `true`].id"

When a parameter value isn't formatted correctly for the scripting language that is parsing the value, you receive an invalid jmespath_type value error:

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == ].id', '--debug']
...
cli.azure.cli.core.azclierror: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'
az_command_data_logger: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'

Look at the variable value Bash is passing for allowBlobPublicAccess. In fact, where is the value? Why is it missing?

Remember, it's the environment (also referred to as "scripting language") that parses Azure CLI variable values. Each scripting language, and even versions of the same scripting language, can produce different results. Here's the correct way to pass a boolean parameter value in Bash:

# Bash script - CORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == \`true\`].id" --debug

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == `true`].id', '--debug']
...
[
  "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-rg-00000000/providers/Microsoft.Storage/storageAccounts/msdocssa00000000"
]

Tip

The key difference is escaping the backticks with \true`` so Bash doesn't interpret them as command substitution.

Grasp the important concept of --debug, and you are on your way to using Azure CLI successfully in your environment of choice.

Scripting language syntax differences

As we just finished talking about --debug, the next step is to be aware of what causes most scripting errors. A script written in Bash needs to be modified to execute successfully in PowerShell or cmd.exe if your script contains one of these constructs:

  • Line continuation characters
  • Variables
  • Random identifiers
  • Quotes
  • Programming language constructs

Here are some examples:

Syntax Bash PowerShell cmd.exe
Line continuation characters Backslash (\) Backtick (`) Caret (^)
Variable naming variableName=varValue $variableName="varValue" set variableName=varValue
Number as string \50`` `50` `50`
Boolean as string \true`` `false` 'true'
Random ID let "randomIdentifier=$RANDOM*$RANDOM" $randomIdentifier = (New-Guid).ToString().Substring(0,8) set randomIdentifier=%RANDOM%
Looping until, while, for for, foreach, while, do-while, do-until for
Write to console echo Write-Host (preferred) or echo echo

Common pitfalls

This example table isn't all-inclusive. What's important to understand when receiving an Azure CLI error is to consider first that there might be a syntax problem for your environment. Test this possibility by copying and pasting your script into another scripting language, like Azure Cloud Shell. Use --debug in both environments and note the differences in the command arguments property of the output.

Important

When copying code blocks from Microsoft articles, be aware that most Azure CLI documentation at Microsoft is written for Bash and tested in Azure Cloud Shell.

More ways to get help

Use az find

Take a quick tour of Azure CLI commands by following these examples:

Find the most popular commands related to the word blob:

az find blob

Show the most popular commands for an Azure CLI command group, such as az storage:

az find "az storage"

Show the most popular parameters and subcommands for an Azure CLI command:

az find "az storage account create"

Use --help

If you already know the name of the command you want, the --help argument for that command gets you more detailed information on the command and a list of the available subcommands for a command group. Continuing with our Azure storage examples, here's how you can get a list of the subgroups and commands for managing a storage account's blob service:

az storage account blob-service-properties --help

Tip

Use --help with any command or subcommand to get detailed usage information without leaving the terminal.

A to Z documentation indexes

To find examples for Azure CLI reference commands, use one of several A to Z indexes:

  • Reference index: Provides an A to Z list of all reference groups. Expand the left navigation bar for subgroups.

  • Azure CLI conceptual article list: Provides an A to Z list of quickstarts, how-to guides, tutorials, and learn modules that explain how to use Azure CLI reference commands in real-world scenarios. The article list groups articles by Azure CLI command group, like az account, then az acr, etc. Use Ctrl+F in Windows (Cmd+F in macOS) to quickly jump to the command group of your choice.

  • Azure CLI sample scripts: The index has three tabs:

Use Copilot

Both the Azure portal and Microsoft Edge offer Copilot experiences that return information on Azure CLI reference commands, samples, and published articles. Copilot also provides links to related Stack Overflow questions. When you have a difficult job to be done with multiple scripting steps, Copilot is helpful in compiling multiple sources of information to answer your question.

Note

GitHub Copilot can also help you write Azure CLI scripts directly in your code editor, providing intelligent code completion and suggestions.