Austin Tolani

Disclaimer: I currently work at Microsoft. Opinions expressed in this post are my own and do not reflect the views of my employer.

The Azure CLI is one of the handful of tools available for programmatically managing Azure resources, the others being Azure Powershell, Terraform, ARM templates and the various Azure management plane SDKs.

While the Azure CLI is primarily used in deployment scripts running on pipeline agents, it also is an effective tool to use on your local machine for more manual and exploratory scenarios. These scenarios could involve anything you would typically do through the Azure Portal, such as viewing resources deployed to a resource group or creating resources for testing.

Using the Azure CLI instead of the Azure Portal has the same appeal as using any CLI tool over a graphical interface. In my mind, the key benefits are the ability to view history of commands, speed, ease of repeating/modifying previously run commands and integration with other command line tools/scripting languages.

Below are a list of 5 tips for using the Azure CLI, distilled from my experience using the tool over the past few years. While there are some tips that apply to all use cases, they mostly apply to using the Azure CLI on your local machine.

Tip #1: Understand and use the different command output formats

The Azure CLI supports several output formats, however the default format (JSON) makes the output of most Azure CLI commands far too verbose and not very readable. Play around with the different output formats to see which you prefer. To change the output format for a command use the -o parameter. For example:

 az appconfig list -o table

For most commands, I find the table format to be preferable as it has the effect of greatly reducing the size of the output and making the content readable, especially for commands that return lists. For commands where I want to inspect the full result, I prefer yamlc. I also find myself using None for commands where I don’t need the output.

Tip #2: Set your own defaults

If you find yourself repeatedly adding a parameter for most or all commands, consider changing the default value used by the Azure CLI. Following from Tip #1, I prefer table as the default output format over JSON. I also like to set a default location so that I don’t need to add the -l parameter to create commands.

Defaults can be set using the az config set command, through a CLI configuration file or environment variables. More details in this doc. Here is an example of how you could set the default output format:

 az config set core.output=table

One caution about changing defaults: be careful of running scripts that assume default behavior. For example, I have found that many scripts will assume that the output of commands is JSON and not use the -o json parameter. This can lead to errors if the script parses the output of commands and assumes the output is JSON.

Tip #3: Enable auto-completion

Auto-completion of parameter inputs greatly improves the speed at which you can write commands. Instead of having to type out the name of a resource group, location or parameter option, you can simply type the first few letters and press Tab to complete the string. If there are multiple possible options, press Tab again to view the options.

Unfortunately, auto-completion is likely not configured out-of-the box for your Azure CLI installation. Assuming you are using a UNIX-style shell such as Bash, zsh or fish, you can download this az.completion file and add the following to your .bash_rc file (or equivalent) to enable auto-completion:

 source /path/to/az.completion

Tip #4: Set up aliases for common workflows

You might find that there are commands that you run frequently that are laborious to type out. For example, running a list command and querying for certain properties. Set up aliases to make running these commands easier. One way you can do this is creating an alias in your shell. For example, the following alias, added to my .zshrc file, lists all Redis instances with a few properties, sorted by provisioning state:

 alias redislist='az redis list --query "sort_by([].{Name:name,ResourceGroup:resourceGroup,State:provisioningState},&State)"'

Another way to create aliases is to create them within the Azure CLI, using the Az CLI alias extension.

Tip #5: Use the --debug flag for troubleshooting

Sometimes the Azure CLI might return an error that is unexpected or not descriptive. I’ve found that in these scenarios, re-running the command with the --debug parameter is useful in root causing the issue. Adding the --debug parameter will enable debugging output, which, while verbose, gives insight into the inner workings of the command, and most importantly, the details of the HTTP requests being invoked as a result of the command.

On a few occasions, inspecting the output of the --debug flag has been a quick and easy way for diagnosing unexpected service behavior.