Must known options of the AWS CLI

Explore the AWS CLI capacities

Must known options of the AWS CLI

So you have installed the AWS CLI on your system. What can you do with it ? Let's do some exploration on some basic usages.

Know how to get help

At a moment or another, you will have the need to get some help. You have the option to crawl the internet, but you can also just use what is at your finger tips.

By typing `aws` command in your favorite shell, you will get the usual usage informations relative to the command:

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

  aws help
  aws <command> help
  aws <command> <subcommand> help
aws: error: the following arguments are required: command

By reading carefully the usage, you may remark, you can access help at  CLI level, command level, and then command / subcommand level.

Without even paying attention, we just got an interesting information: AWS CLI relies not only on commands, but also subcommands. Basically, it helps to reference services at command level, and then actions related to the selected service at subcommand level.

Here is the command structure:

$ aws <command> <subcommand> [options and parameters]

Depending on the command /subcommand used, you will be able to use various types of input values, such as numbers, strings, lists, maps or even JSON structures.

By executing command `aws help`, you will get the following answer:


       aws -

       The  AWS  Command  Line  Interface is a unified tool to manage your AWS

          aws [options] <command> <subcommand> [parameters]

       Use aws command help for information on a  specific  command.  Use  aws
       help  topics  to view a list of available help topics. The synopsis for
       each command shows its parameters and their usage. Optional  parameters
       are shown in square brackets.

       --debug (boolean)

       Turn on debug logging.

       --endpoint-url (string)

       Override command's default URL with the given URL.

       --no-verify-ssl (boolean)

       By  default, the AWS CLI uses SSL when communicating with AWS services.
       For each SSL connection, the AWS CLI will verify SSL certificates. This
       option overrides the default behavior of verifying SSL certificates.

       --no-paginate (boolean)

       Disable automatic pagination.

       --output (string)

       The formatting style for command output.

       o json

       o text

       o table

       --query (string)

       A JMESPath query to use in filtering the response data.

       --profile (string)

       Use a specific profile from your credential file.

       --region (string)

       The region to use. Overrides config/env settings.

       --version (string)

       Display the version of this tool.

       --color (string)

       Turn on/off color output.

       o on

       o off

       o auto

       --no-sign-request (boolean)

       Do  not  sign requests. Credentials will not be loaded if this argument
       is provided.

       --ca-bundle (string)

       The CA certificate bundle to use when verifying SSL certificates. Over-
       rides config/env settings.

       --cli-read-timeout (int)

       The  maximum socket read time in seconds. If the value is set to 0, the
       socket read will be blocking and not timeout.

       --cli-connect-timeout (int)

       The maximum socket connect time in seconds. If the value is set  to  0,
       the socket connect will be blocking and not timeout.

      o ...

Checking at the bottom, you can see you will have access to the full list of services supported by the version of the CLI. But more important, you have all the options of the CLI, and there you can already see some goodness related to the CLI as debug logging, switch of target endpoint, response content filtering, and even configuration of targeted region or used profile.

Let's go through some interesting options available and see what they have to offer !

Debug logging

aws --debug ...

Being able to troubleshoot commands may become critical when you experiment issues with the AWS CLI. The simple debug flag will activate highly verbose debug logs, providing you precious information you need to understand what is ongoing.

Endpoint URL

aws --endpoint-url <string> ...

Whenever you start using AWS services to host an endpoint directly within a private VPC, you have to specify them to use them instead of using the default pubic one.

It may be, especially useful in entreprise when an integration exists for example between the company network and the VPC, meaning that if you want to avoid to go through the internet, you will have to configure and use the VPC Endpoint associated with the service you are targeting.

Output format

The output flag is very handy. It allow to provide answers with multiple formats. It is possible to deal with: json, yaml, text, and table.

On one hand side, the text format is useful to process responses with standard Unix tools as `grep`, `sed` or `awk`. On the other hand, the table format allows to read data in table format.

Output flag value can be pre-configured into the AWS CLI config file. Here is an example:


It is also possible to specify it with an environment variable:

$ export AWS_DEFAULT_OUTPUT="table"

But definitively, you may want to override default configuration with the flag:

$ aws swf list-domains --registration-status REGISTERED --output json

Text format

Using the text format will enable alternative presentation that may fit better with the need to execute requests and get results  that may be much readable:

$ aws iam list-users --output text --query 'Users[*].[UserName,Arn,CreateDate,PasswordLastUsed,UserId]'
Admin         arn:aws:iam::123456789012:user/Admin         2014-10-16T16:03:09+00:00   2016-06-03T18:37:29+00:00   AIDA1111111111EXAMPLE backup-user   arn:aws:iam::123456789012:user/backup-user   2019-09-17T19:30:40+00:00   None                        AIDA2222222222EXAMPLE cli-user      arn:aws:iam::123456789012:user/cli-backup

Table format

Given you want to read something more tabular and more visual to add  results of request into a documentation, you may use the output flag this way:

aws ec2 describe-volumes --query 'Volumes[*].{ID:VolumeId,InstanceId:Attachments[0].InstanceId,AZ:AvailabilityZone,Size:Size}' --output table

and then get the following result:

|                   DescribeVolumes                  | 
|     AZ     |      ID        | InstanceId   | Size  |
|  us-west-2a|  vol-e11a5288  |  i-a071c394  |  30   |
|  us-west-2a|  vol-2e410a47  |  i-4b41a37c  |  8    |

Query specific data

aws --query <string> ...

The query flag will allow to specify a JMESPath query to use in filtering response data. JMESPath is a standard defining a query language for JSON.

You can find full detailed informations here:

Controlling command output from the AWS CLI - AWS Command Line Interface
Control the format of the output from the AWS Command Line Interface (AWS CLI).

Let say you want to describe volumes available in EC2 service, you will have to execute following command:

$ aws ec2 describe-volumes

And you will get this kind of answer, given you configured output to json:

    "Volumes": [
            "AvailabilityZone": "us-west-2a",
            "Attachments": [
                    "AttachTime": "2013-09-17T00:55:03.000Z",
                    "InstanceId": "i-a071c394",
                    "VolumeId": "vol-e11a5288",
                    "State": "attached",
                    "DeleteOnTermination": true,
                    "Device": "/dev/sda1"
            "VolumeType": "standard",
            "VolumeId": "vol-e11a5288",
            "State": "in-use",
            "SnapshotId": "snap-f23ec1c8",
            "CreateTime": "2013-09-17T00:55:03.000Z",
            "Size": 30
            "AvailabilityZone": "us-west-2a",
            "Attachments": [
                    "AttachTime": "2013-09-18T20:26:16.000Z",
                    "InstanceId": "i-4b41a37c",
                    "VolumeId": "vol-2e410a47",
                    "State": "attached",
                    "DeleteOnTermination": true,
                    "Device": "/dev/sda1"
            "VolumeType": "standard",
            "VolumeId": "vol-2e410a47",
            "State": "in-use",
            "SnapshotId": "snap-708e8348",
            "CreateTime": "2013-09-18T20:26:15.000Z",
            "Size": 8

It may be verbose, and not very handy. And this is where the query flag starts to be interesting since it will allow to reduce the result payload to only what you are interested in. For example, you want, the VolumeId, the AvailabilityZone and the Size, you will have to execute the following command:

aws ec2 describe-volumes --query 'Volumes[*].{VolumeId,AvailabilityZone,Size}'

Result will be the following one:

        "AvailabilityZone": "us-west-2a",
        "VolumeId": "vol-e11a5288",
        "Size": 30
        "AvailabilityZone": "us-west-2a",
        "VolumeId": "vol-2e410a47",
        "Size": 8

You can go even further by providing aliases.

aws ec2 describe-volumes --query 'Volumes[*].{ID:VolumeId,AZ:AvailabilityZone,Size:Size}'

providing the following result:

        "AZ": "us-west-2a",
        "ID": "vol-e11a5288",
        "Size": 30
        "AZ": "us-west-2a",
        "ID": "vol-2e410a47",
        "Size": 8

Filter result content

Capabilities are almost limitless given you know how to handle JMESPath query language. It is even possible to filter responses with expressions:

$ aws ec2 describe-volumes \
    --filters "Name=availability-zone,Values=us-west-2a" "Name=status,Values=attached" \
    --query 'Volumes[?Size > `50`].{Id:VolumeId,Size:Size,Type:VolumeType}'

Here we want to get only Volumes having a size greater than 50Gb. The powerful tip is that you don't have to write code to handle this kind of filtering, you just have to leverage the power of the filter flag.

Choose the profile

There are multiple ways to configure profile. It is also possible to configure it as a flag of the command executed, it might be handy in some situations. You basically have to add profile this way:

aws configure --profile <profilename>

Region configuration

As for `profile` option, there are multiple ways to provide `region` value. Region will influence the target endpoint used by the CLI to dialog with the expected region.


Options are multiples as flags of the command line. Most of time, they have alternatives for example as Environment variables. Knowing them will allow you to be more proficient at the tasks you need to deal with on a daily basis. Not using these powerful options may make your work harder, as you would have to fix the needed feature.