author
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()
NAME
aws -
DESCRIPTION
The AWS Command Line Interface is a unified tool to manage your AWS
services.
SYNOPSIS
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.
OPTIONS
--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.
AVAILABLE SERVICES
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:
[default]
output=text
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.
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.
Conclusion
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.