Creating and using aliases in the Amazon CLI - Amazon Command Line Interface
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.

Creating and using aliases in the Amazon CLI

Aliases are shortcuts you can create in the Amazon Command Line Interface (Amazon CLI) to shorten commands or scripts that you frequently use. You create aliases in the alias file located in your configuration folder.

Prerequisites

To use alias commands, you need to complete the following:

Step 1: Creating the alias file

To create the alias file, you can use your file navigation and a text editor, or use your preferred terminal by using the step-by-step procedure. To quickly create your alias file, use the following command block.

Linux and macOS
$ mkdir -p ~/.aws/cli $ echo '[toplevel]' > ~/.aws/cli/alias
Windows
C:\> md %USERPROFILE%\.aws\cli C:\> echo [toplevel] > %USERPROFILE%/.aws/cli/alias
To create the alias file
  1. Create a folder named cli in your Amazon CLI configuration folder. By default the configuration folder is ~/.aws/ on Linux or macOS and %USERPROFILE%\.aws\ on Windows. You can create this through your file navigation or by using the following command.

    Linux and macOS
    $ mkdir -p ~/.aws/cli
    Windows
    C:\> md %USERPROFILE%\.aws\cli

    The resulting cli folder default path is ~/.aws/cli/ on Linux or macOS and %USERPROFILE%\.aws\cli on Windows.

  2. In the cli folder, create a text file named alias with no extension and add [toplevel] to the first line. You can create this file through your preferred text editor or use the following command.

    Linux and macOS
    $ echo '[toplevel]' > ~/.aws/cli/alias
    Windows
    C:\> echo [toplevel] > %USERPROFILE%/.aws/cli/alias

Step 2: Creating an alias

You can create an alias using basic commands or bash scripting.

Creating a basic command alias

You can create your alias by adding a command using the following syntax in the alias file you created in the previous step.

Syntax

aliasname = command [--options]

The aliasname is what you call your alias. The command is the command you want to call, which can include other aliases. You can include options or parameters in your alias, or add them when calling your alias.

The following example creates an alias named aws whoami using the aws sts get-caller-identity command. Since this alias calls an existing Amazon CLI command, you can write the command without the aws prefix.

whoami = sts get-caller-identity

The following example takes the previous whoami example and adds the Account filter and text output options.

whoami2 = sts get-caller-identity --query Account --output text

Creating a sub-command alias

Note

The sub-command alias feature requires a minimum Amazon CLI version of 1.11.24 or 2.0.0

You can create an alias for sub-commands by adding a command using the following syntax in the alias file you created in the previous step.

Syntax

[command commandGroup] aliasname = command [--options]

The commandGroup is the command namespace, e.g. The command aws ec2 describe-regions is under the ec2 command group. The aliasname is what you call your alias. The command is the command you want to call, which can include other aliases. You can include options or parameters in your alias, or add them when calling your alias.

The following example creates an alias named aws ec2 regions using the aws ec2 describe-regions command. Since this alias calls an existing Amazon CLI command under the ec2 command namespace, you can write the command without the aws ec2 prefix.

[command ec2] regions = describe-regions --query Regions[].RegionName

To create aliases from commands outside of the command namespace, prefix the full command with an exclamation mark. The following example creates an alias named aws ec2 instance-profiles using the aws iam list-instance-profiles command.

[command ec2] instance-profiles = !aws iam list-instance-profiles
Note

Aliases only use existing command namespaces and you cannot create new ones. e.g. You can't create an alias with the [command johnsmith] section as the johnsmith command namespace does not already exist.

Creating a bash scripting alias

Warning

To use Amazon CLI alias bash scripts, you must use a bash-compatible terminal

You can create an alias using bash scripts for more advanced processes using the following syntax.

Syntax

aliasname = !f() { script content }; f

The aliasname is what you call your alias and script content is the script you want to run when you call the alias.

The following example uses opendns to output your current IP address. Since you can use aliases in other aliases, the following myip alias is useful to allow or revoke access for your IP address from within other aliases.

myip = !f() { dig +short myip.opendns.com @resolver1.opendns.com }; f

The following script example calls the previous aws myip alias to authorize your IP address for an Amazon EC2 security group ingress.

authorize-my-ip = !f() { ip=$(aws myip) aws ec2 authorize-security-group-ingress --group-id ${1} --cidr $ip/32 --protocol tcp --port 22 }; f

When you call aliases that use bash scripting, the variables are always passed in the order that you entered them. In bash scripting, the variable names are not taken into consideration, only the order they appear. In the following textalert alias example, the variable for the --message option is first and --phone-number option is second.

textalert = !f() { aws sns publish --message "${1}" --phone-number ${2} }; f

Step 3: Calling an alias

To run the alias you created in your alias file use the following syntax. You can add additional options when you call your alias.

Syntax

$ aws aliasname

The following example uses the aws whoami command alias.

$ aws whoami { "UserId": "A12BCD34E5FGHI6JKLM", "Account": "1234567890987", "Arn": "arn:aws:iam::1234567890987:user/userName" }

The following example uses the aws whoami alias with additional options to only return the Account number in text output.

$ aws whoami --query Account --output text 1234567890987

The following example uses the aws ec2 regions sub-command alias.

$ aws ec2 regions [ "ap-south-1", "eu-north-1", "eu-west-3", "eu-west-2", ...

Calling an alias using bash scripting variables

When you call aliases that use bash scripting, variables are passed in the order they are entered. In bash scripting, the name of the variables are not taken into consideration, only the order they appear. For example, in the following textalert alias, the variable for the option --message is first and --phone-number is second.

textalert = !f() { aws sns publish --message "${1}" --phone-number ${2} }; f

When you call the textalert alias, you need to pass variables in the same order as they are run in the alias. In the following example we use the variables $message and $phone. The $message variable is passed as ${1} for the --message option and the $phone variable is passed as ${2} for the --phone-number option. This results in successfully calling the textalert alias to send a message.

$ aws textalert $message $phone { "MessageId": "1ab2cd3e4-fg56-7h89-i01j-2klmn34567" }

In the following example, the order is switched when calling the alias to $phone and $message. The $phone variable is passed as ${1} for the --message option and the $message variable is passed as ${2} for the --phone-number option. Since the variables are out of order, the alias passes the variables incorrectly. This causes an error because the contents of $message do not match the phone number formatting requirements for the --phone-number option.

$ aws textalert $phone $message usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters] To see help text, you can run: aws help aws <command> help aws <command> <subcommand> help Unknown options: text

Alias repository examples

The Amazon CLI alias repository on GitHub contains Amazon CLI alias examples created by the Amazon CLI developer team and community. You can use the entire alias file example or take individual aliases for your own use.

Warning

Running the commands in this section deletes your existing alias file. To avoid overwriting your existing alias file, change your download location.

To use aliases from the repository
  1. Install Git. For installation instructions, see Getting Started - Installing Git in the Git Documentation.

  2. Install the jp command. The jp command is used in the tostring alias. For installation instructions, see the JMESPath (jp) README.md on GitHub.

  3. Install the jq command. The jq command is used in the tostring-with-jq alias. For installation instructions, see the JSON processor (jq) on GitHub.

  4. Download the alias file by doing one of the following:

    • Run the following commands that downloads from the repository and copies the alias file to your configuration folder.

      Linux and macOS
      $ git clone https://github.com/awslabs/awscli-aliases.git $ mkdir -p ~/.aws/cli $ cp awscli-aliases/alias ~/.aws/cli/alias
      Windows
      C:\> git clone https://github.com/awslabs/awscli-aliases.git C:\> md %USERPROFILE%\.aws\cli C:\> copy awscli-aliases\alias %USERPROFILE%\.aws\cli
    • Download directly from the repository and save to the cli folder in your Amazon CLI configuration folder. By default the configuration folder is ~/.aws/ on Linux or macOS and %USERPROFILE%\.aws\ on Windows.

  5. To verify the aliases are working, run the following alias.

    $ aws whoami

    This displays the same response as the aws sts get-caller-identity command:

    { "Account": "012345678901", "UserId": "AIUAINBADX2VEG2TC6HD6", "Arn": "arn:aws:iam::012345678901:user/myuser" }

Resources