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

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

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

Creating a bash scripting alias

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.

Resources