Azure CLI Basics: Anatomy of a Command

April 23, 2018

7 minutes read

In my previous post in this series, I covered how to authenticate Azure CLI to one or more Azure Subscriptions and switch between those subscriptions. In this post, we will cover how Azure CLI command lines are structured.

Before we begin, as always, verify that you have logged in and that the correct subscription is selected by running az account list. The currently selected subscription is the one marked True under IsDefault in the output. If the wrong subscription is selected, see my previous post on working with subscription logins in Azure CLI.

Anatomy of an Azure CLI Command

One of the interesting things about Azure CLI that you may have noticed already is that the command az can be following by any one of a number of other key terms that change what you are operating on or what operation the command performs.

Here is an example:

$ az vm list --output table

Let’s take the preceding command line — which we can use to list all the virtual machines in the subscription — and break it down into it parts:

Shell Prompt
| Azure CLI invocation script
| |  Group
| |  |  Command
| |  |  |    Parameter
| |  |  |    |        Argument
| |  |  |    |        |
$ az vm list --output table

Now that we have the parts labelled, let’s look at what each is for….

Shell Prompt

This command line is being run in Bash, so the very first part, $ (dollar), is the prompt, or where you begin entering your command. The prompt differs from system to system and from shell to shell. If you are running Azure CLI inside a PowerShell window, you may have PS> as your prompt instead.

The ‘az’ Command

The az command list actually a script that wraps around a Python invocation of the azure.cli module:

python -m azure.cli "$@"

You can see this for yourself by opening up the script and taking a look. To find the script on your system, type which az at your prompt.

The wrapper sets some variables and then passes to Python the remaining command line you typed — specifically, it is passed to the Azure CLI module (azure.cli).

Groups and Subgroups

The most immediate word after the az command will be the name of a group that will serve as the context in which your command and parameters run, and, as the documentation puts it: “Each group represents a service provided by Azure, and the subgroups divide commands for these services into logical groupings.” ¹

For example, to see the subgroups for the virtual machines group, type az vm --help:

$ az vm --help

Group
    az vm: Provision Linux or Windows virtual machines.

Subgroups:
    availability-set      : Group resources into availability sets.
    boot-diagnostics      : Troubleshoot the startup of an Azure Virtual Machine.
    diagnostics           : Configure the Azure Virtual Machine diagnostics extension.
    disk                  : Manage the managed data disks attached to a VM.
    encryption            : Manage encryption of VM disks.
    extension             : Manage extensions on VMs.
    identity              : Manage service identities of a VM.
    image                 : Information on available virtual machine images.
    nic                   : Manage network interfaces. See also `az network nic`.
    run-command           : Manage run commands on a Virtual Machine.
    secret
    unmanaged-disk        : Manage the unmanaged data disks attached to a VM.
    user                  : Manage user accounts for a VM.

Subcommands

In addition to groups and subgroups themselves, there may be actions that we want to perform on those groups or subgroups. These are the subcommands we referred to earlier. If we scroll down a bit further in our az vm --help output, we see the list of commands:

Commands:
    assign-identity       : (Deprecated, please use 'az vm identity assign').
    capture               : Capture information for a stopped VM.
    convert               : Convert a VM with unmanaged disks to use managed disks.
    create                : Create an Azure Virtual Machine.
    deallocate            : Deallocate a VM.
    delete                : Delete a VM.
    format-secret
    generalize            : Mark a VM as generalized, allowing it to be imaged for multiple
                            deployments.
    get-instance-view     : Get instance information about a VM.
    list                  : List details of Virtual Machines.
    list-ip-addresses     : List IP addresses associated with a VM.
    list-sizes            : List available sizes for VMs.
    list-skus             : Get details for compute-related resource SKUs.
    list-usage            : List available usage resources for VMs.
    list-vm-resize-options: List available resizing options for VMs.
    open-port             : Opens a VM to inbound traffic on specified ports.
    perform-maintenance   : The operation to perform maintenance on a virtual machine.
    redeploy              : Redeploy an existing VM.
    remove-identity       : (Deprecated, please use 'az vm identity remove').
    resize                : Update a VM's size.
    restart               : Restart VMs.
    show                  : Get the details of a VM.
    start                 : Start a stopped VM.
    stop                  : Stop a running VM.
    update                : Update the properties of a VM.
    wait                  : Place the CLI in a waiting state until a condition of the VM is met.

A good way to distinguish between subgroups and subcommands is to think of groups as “things” that we can work with and subcommands as “actions” we can perform on those things. Or, if you’re an English major, think of them as parts of speech: subgroups as “nouns” and subcommands as “verbs.”

Getting Help

This is a good time to pause and state that the help in Azure CLI is extensive. There is help for every command and group. If you commit nothing else to memory, remember all the az sub-groups and commands have help that you can display simply by tacking --help on the end of the command. The more sub-groups you add, the more specific the help becomes.

Try out these examples:

az --help
az vm --help
az vm disk --help
az vm disk attach --help

Remember: You can do this with any set of sub-groups or commands to view detailed help, including arguments and examples.

Switches and Parameters

Parameters

Once you have a command to work with, you can supply all the details for how to run that command with switches and parameters. Loosely speaking, a parameters are the bits of the command line that you precede with one or two hyphens — as in, --resource-group and -g — and that have some sort of argument, or specific details about the parameter — such as in the name of the resource group:

az vm list --resource-group production-rg

Most parameters have shorter equivalents that only take a single hyphen. The --resource-group parameter has a short form: -g. So, our example could be rewritten as follows:

az vm list -g production-rg

In this example “production-rg” is the argument to the resource group parameter. You can think of these as pairs. You can’t have the one without the other — every parameter needs an argument.

What do we do when there isn’t a need for an argument then? For example, what if we just want to tell the command we want verbose output? This brings us to switches….

Switches

A switch is like a parameter, but it does not have any argument — it’s not paired with any other input. If you’ve ever used --verbose at the end of a command line, it’s an example of a switch.

Finding Groups and Commands

With all the help, how do we find the correct command or group? Or maybe we know what we’re looking for, but don’t remember where Azure CLI puts the particular thing we’re trying to do. This is where the find subcommand comes in…

Searching for Commands or Groups

Remember how we said that, if nothing else, you should remember the --help switch? Well, if you remember anything after that, remember the find command:

az find -q $SEARCH_TERM

This does exactly what it looks like: It looks through an index of all the Azure CLI commands and displays matches to whatever you’re looking for.

az find --search-query "vm"

Hopefully we’ve cleared up any questions you had about how Azure CLI command lines are constructed. Once you understand the “anatomy” of a command, it makes using them (and remembering them) much easier.