-
Notifications
You must be signed in to change notification settings - Fork 484
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Added documentation for alias command #707
Changes from 4 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -32,15 +32,16 @@ az extension add --name alias | |
Verify the installation of the extension with [az extension list](/cli/azure/extension#az-extension-list). If the alias extension was installed properly, it's listed in the command output. | ||
|
||
```azurecli | ||
az extension list --output table | ||
az extension list --output table --query '[].{Name:name}' | ||
``` | ||
|
||
```output | ||
ExtensionType Name Version | ||
--------------- ------------------------- --------- | ||
whl alias 0.2.0 | ||
Name | ||
------ | ||
alias | ||
``` | ||
|
||
|
||
## Keep the extension up to date | ||
|
||
The alias extension is under active development and new versions are released regularly. New versions are not automatically installed whenever you update the CLI. Install the updates for the extension with [az extension update](/cli/azure/extension#az-extension-update). | ||
|
@@ -49,27 +50,23 @@ The alias extension is under active development and new versions are released re | |
az extension update --name alias | ||
``` | ||
|
||
## Alias commands file format | ||
|
||
Alias command definitions are written into a configuration file, located at `$AZURE_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` 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 general format for alias commands is: | ||
## Manage aliases for the Azure CLI | ||
|
||
``` | ||
[command_name] | ||
command = invoked_commands | ||
The alias extension provides convenient and familiar commands to manage aliases. To view all the available commands and parameter details, invoke the alias command with `--help`. | ||
|
||
```azurecli | ||
az alias --help | ||
``` | ||
|
||
Don't include `az` as part of the command. | ||
|
||
## 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`. | ||
|
||
``` | ||
[rg] | ||
command = group | ||
|
||
[ls] | ||
command = list | ||
```azurecli | ||
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. | ||
|
@@ -80,11 +77,12 @@ az rg ls | |
az vm ls | ||
``` | ||
|
||
Do not include `az` as part of the command. | ||
|
||
Aliases can also be shortcuts for complete commands. The next example lists available resource groups and their locations in table output: | ||
|
||
``` | ||
[ls-groups] | ||
command = group list --query '[].{Name:name, Location:location}' --output table | ||
```azurecli | ||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would include a line around here that lets users know that the value passed to There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Alias would attempt to convert all excessive whitespaces and next line character There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No, that's fine. In this case, can you put the newlines back into the examples they were removed from to make them more readable? The only reason I suggested removing them was that I wasn't sure if there was whitespace-stripping performed by the alias extension before writing to the config file. |
||
|
@@ -93,20 +91,19 @@ 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. My understanding is that Jinja2 treats interior whitespace as significant. All of their documentation uses whitespace inside of brackets. If this is the case, this line should be left in. From experience with documentation, not calling out where whitespace is significant as part of a spec can lead to user confusion and frustration, as whitespace is often not expected to be significant in a tokenizer where there is a clear delineation between alphanumeric and nonalphanumeric tokens. |
||
|
||
``` | ||
[alias_name {{ arg1 }} {{ arg2 }} ...] | ||
command = invoke_including_args | ||
```azurecli | ||
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. | ||
|
||
``` | ||
[get-vm-ip {{ resourceGroup }} {{ vmName }}] | ||
command = vm list-ip-addresses --resource-group {{ resourceGroup }} --name {{ vmName }} --query [0].virtualMachine.network.publicIpAddresses[0].ipAddress | ||
```azurecli | ||
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. | ||
|
@@ -117,24 +114,53 @@ az get-vm-ip MyResourceGroup MyVM | |
|
||
You can also use environment variables in commands invoked by aliases, 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`. | ||
|
||
```azurecli | ||
az alias create --name "create-rg {{ groupName }}" --command "group create --name {{ groupName }} --location eastus --tags owner=\$USER" | ||
``` | ||
[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 | ||
|
||
Argument substitution in the alias extension is performed by [Jinja2](http://jinja.pocoo.org/docs/2.10/), giving you full access to the capabilities of the Jinja2 template engine. Templates allow you to perform actions like data extraction and substitution on strings. | ||
|
||
With Jinja2 templates, you can write aliases which take different types of arguments than the underlying command. For example, you can make an alias which takes a storage URL. Then this URL is parsed to pass the account and container names to the storage command. | ||
|
||
``` | ||
[storage-ls {{ url }}] | ||
command = storage blob list --account-name {{ url.replace('https://', '').split('.')[0] }} --container-name {{ url.replace('https://', '').split('/')[1] }} | ||
```azurecli | ||
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](http://jinja.pocoo.org/docs/2.10/templates/). | ||
|
||
|
||
## Alias configuration file | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Include a newline after an H2. |
||
|
||
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_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` 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: | ||
|
||
```ini | ||
[alias_name] | ||
command = invoked_commands | ||
``` | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Include a second example which shows how to write a command which takes arguments into the configuration file. |
||
For aliases that contain positional arguments, the format for alias commands is: | ||
|
||
```ini | ||
[alias_name {{ arg1 }} {{ arg2 }} ...] | ||
command = invoked_commands_including_args | ||
``` | ||
|
||
|
||
## Create an alias command with arguments via the alias configuration file | ||
|
||
Below is an alias configuration file that contains an example alias command with arguments, which gets the public IP address for a VM. Ensure that the invoked command is in a single line, and contains the same arguments defined in the alias. | ||
|
||
```ini | ||
[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](/cli/azure/extension#az-extension-remove) command. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As convenient as the
alias
command, I think there is value to keep instructions of both add through command and add through config file.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll add this section back.