logo

AWS - Using the command-line interface (CLI)

The AWS command-line interface (CLI) tool is an important piece of the AWS administrator's toolkit.

The CLI tool is open source software, and is maintained on GitHub (https://github.com/aws/aws-cli). For more detailed documentation, refer to the AWS CLI home page at https://aws.amazon.com/cli.

Installation

Step 1 : The CLI tool requires Python 2.6.5 or greater.

python3 --version

Step 2 : The easiest way to install it is to use the Python package manager, pip:

pip3 install awscli

Upgrade

To upgrade the CLI tool, run the following pip command periodically:

pip3 install --upgrade awscli

Configuration

Authentication between the CLI tool and the AWS API is done via two pieces of information:

  • Access key ID
  • Secret access key

While you can configure the CLI tool with access keys directly, this should be avoided. Instead, you should use profiles to store your credentials. Using profiles gives you a more consistent and manageable centralized location to secure your secret keys.

Default profile

Without any additional configuration or options, your CLI tool commands will use the default profile. To set up the default profile, you can use the following command:

This will prompt you for an access key ID, secret access key, region, and output format.

Named profiles

In addition to the default profile, you can configure other, named profiles. This is useful for switching between users with different levels of access (for example, read-only and administrator) or even between users in different accounts:

aws configure --profile <profile-name>

Environment variables

You can also configure the CLI via the use of environment variables:

export AWS_PROFILE=<profile-name>

While you should prefer to use profiles over setting your access ID and secret keys directly, sometimes you may have to do so. If you must set your keys directly, do so via environment variables so that you don't need to pass your keys around or hardcode them:

export AWS_ACCESS_KEY_ID=<ccess-key-id>
export AWS_SECRET_ACCESS_KEY=<secret-access-key>

Usage

All CLI tool commands are service-based. By using service commands and subcommands, you can make calls directly to the AWS API.

Commands

Each command represents an AWS service. While most services have one command associated with them, some services have multiple commands. Run aws help to see all the commands/services that are available

aws help

Subcommands

Each command has a selection of subcommands to perform service-specific actions.

aws iam help

Options

Subcommands take options and start with --. You can view all the options and their purposes by running:

aws <command> <subcommand> help

Output

The CLI tool can be configured to output in JSON, table, or text format. To control the output type, use the --output option.

JSON : JavaScript Object Notation (JSON) (http://json.org/) is a standard machine- and human-readable information interchange format

aws ec2 describe-availability-zones --output json

Table : The table format displays a text/ASCII table of results. This can be useful for generating printable reports:

aws ec2 describe-availability-zones --output table

Text : The text output format only displays the resulting key/value response. No additional formatting or display characters are added:

aws ec2 describe-availability-zones --output text

Querying

The CLI tool supports transforming the response from the API with the --query option. This option takes a JMESPath query as a parameter and returns the query result.

JMESPath is a query language for JSON. For more information, visit http://jmespath.org/.

JMESPath can be used to transform the response that you receive:

aws ec2 describe-availability-zones \
  --output json \
  --query "AvailabilityZones[].ZoneName"

It can also be used to filter the data that is received:

aws ec2 describe-availability-zones \
  --output json \
  --query "AvailabilityZones[?ZoneName == 'us-east-1a'].State"

Generating a CLI skeleton

When performing complex tasks with the CLI tool, it may be easier to pass a JSON object of options. This kind of interaction may signify that you should use one of the AWS software development kits (SDKs).

Input

To generate a sample JSON object that will be accepted, run any command with the --generate-cli-skeleton option:

aws ec2 describe-availability-zones --generate-cli-skeleton

You can then copy, edit, and use this object to define your command options without passing lots of individual options. It works best for commands with arrays of options or a variable number of options.

Output

You can also get a preview of the output of a command by calling the command with the --generate-cli-skeleton output option. This can speed up the process of combining CLI commands as you can see a response without actually calling the API:

aws ec2 describe-availability-zones --generate-cli-skeleton output

Pagination

The results that are returned by the CLI tool are limited to 1,000 resources by default.

The following options allow you to control the number and starting point of the results that are returned to you from the API:

  • --page-size : This limits how many resources will be displayed to you, but does not actually limit the number that's returned. The default number of items (that is, 1,000) will still be processed and returned to you.
  • --max-items : This sets an upper limit on how many items will actually be returned in the response. You may receive fewer items, but you will not receive more than this number.
  • --starting-token : This changes where the response starts. Use this to display subsequent results, beyond the first page:

Autocomplete

You can enable tab completion of commands, subcommands, and options by configuring the completer included with the CLI tool.

On macOS, Linux, and Windows systems with a bash shell, you can load the completer with the following command:

complete -C 'which aws_completer'aws

By default, the aws_completer program is installed in /usr/local/bin. If your tool is installed to a non-standard location, you will need to find it and change the which aws_completer command to the relevant path.

Recommended