How to use the Azure CLI alias extension

The alias extension allows users to define custom commands for the Azure CLI by using existing commands. Aliases help keep your workflow simple by allowing shortcuts. The Jinja2 template engine powers Azure CLI aliases and offers advanced argument processing.

Note

The Alias Extension is in public preview. The features and configuration file format may change.

Install the alias extension

The minimum required Azure CLI version to use the alias extension is 2.0.28. To check your CLI version, run az --version. If you need to update your installation, follow the instructions in Install the Azure CLI.

Install the alias extension with the az extension add command.

az extension add --name alias

Verify the installation of the extension with az extension list. If the alias extension was installed properly, it's listed in the command output.

az extension list --output table --query '[].{Name:name}'

Name
------
alias

Keep the alias extension up-to-date

The alias extension is under active development and new versions are released regularly. New versions aren't installed when you update the CLI. Install the updates for the extension with az extension update.

az extension update --name alias

Manage aliases for the Azure CLI

The alias extension lets you create and manage aliases for other CLI commands. To view all the available commands and parameter details, run the alias command with --help.

az alias --help

Create simple alias commands

One use of aliases is for shortening existing command groups or command names. For example, you can shorten the group command group to rg and the list command to ls.

az alias create --name rg --command group
az alias create --name ls --command list

These newly defined aliases can now be used anywhere that their definition would be.

az rg list
az rg ls
az vm ls

Don't include az as part of the alias command.

Aliases can also be shortcuts for complete commands. The next example lists available resource groups and their locations in table output:

az alias create --name ls-groups --command "group list --query '[].{Name:name, Location:location}' --output table"

Now ls-groups can be run like any other CLI command.

az ls-groups

Create an alias command with arguments

You can also add positional arguments to an alias command by including them as {{ arg_name }} in the alias name. The whitespace inside the braces is required.

az alias create --name "alias_name {{ arg1 }} {{ arg2 }} ..." --command "invoke_including_args"

The next example alias shows how to use positional arguments to get the public IP address for a VM.

az alias create \
    --name "get-vm-ip {{ resourceGroup }} {{ vmName }}" \
    --command "vm list-ip-addresses --resource-group {{ resourceGroup }} --name {{ vmName }}
        --query [0].virtualMachine.network.publicIpAddresses[0].ipAddress"

When running this command, you give values to the positional arguments.

az get-vm-ip MyResourceGroup MyVM

You can also use environment variables in aliased commands, which are evaluated at runtime. The next example adds the create-rg alias, which creates a resource group in eastus and adds an owner tag. This tag is assigned the value of the local environment variable USER.

az alias create \
    --name "create-rg {{ groupName }}" \
    --command "group create --name {{ groupName }} --location eastus --tags owner=\$USER"

To register the environment variables inside the command of the alias, the dollar sign $ must be escaped.

Process arguments using Jinja2 templates

Jinja2 performs the argument substitution in the alias extension. Jinja2 templates allow for manipulating the arguments.

With Jinja2 templates, you can write aliases that take different types of arguments than the underlying command. For example, you can make an alias that takes a storage URL. Then this URL is parsed to pass the account and container names to the storage command.

az alias create \
    --name 'storage-ls {{ url }}' \
    --command "storage blob list
        --account-name {{ url.replace('https://', '').split('.')[0] }}
        --container-name {{ url.replace('https://', '').split('/')[1] }}"

To learn about the Jinja2 template engine, see the Jinja2 documentation.

Alias configuration file

Another way to create and modify aliases is to alter the alias configuration file. Alias command definitions are written into a configuration file, located at $AZURE_CONFIG_DIR/alias. The default value of AZURE_CONFIG_DIR is $HOME/.azure on macOS and Linux, and %USERPROFILE%\.azure on Windows. The alias configuration file is written in the INI configuration file format. The format for alias commands is:

[alias_name]
command = invoked_commands

For aliases that have positional arguments, the format for alias commands is:

[alias_name {{ arg1 }} {{ arg2 }} ...]
command = invoked_commands_including_args

Create an alias command with arguments via the alias configuration file

The next example shows an alias for a command with arguments. This command gets the public IP address for a VM. Aliased commands must all be on a single line, and use all of the arguments in the alias name.

[get-vm-ip {{ resourceGroup }} {{ vmName }}]
command = vm list-ip-addresses --resource-group {{ resourceGroup }} --name {{ vmName }} --query [0].virtualMachine.network.publicIpAddresses[0].ipAddress

Uninstall the alias extension

To uninstall the extension, use the az extension remove command.

az extension remove --name alias

If you uninstalled because a bug or other problem with the extension, file a GitHub issue so that we can provide a fix.