AWS Command Line Interface: User Guide
AWS Command Line Interface: User Guide
AWS Command Line Interface: User Guide
User Guide
AWS Command Line Interface User Guide
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
AWS Command Line Interface User Guide
Table of Contents
What Is the AWS CLI? ......................................................................................................................... 1
Using the Examples .................................................................................................................... 2
About Amazon Web Services ....................................................................................................... 3
Installing the AWS CLI ........................................................................................................................ 4
AWS CLI version 2 ...................................................................................................................... 4
AWS CLI version 1 ...................................................................................................................... 4
Migrating from AWS CLI version 1 to version 2 .............................................................................. 4
Installing the AWS CLI version 2 .................................................................................................. 4
Installing on Linux .............................................................................................................. 5
Installing on macOS ........................................................................................................... 9
Installing on Windows ....................................................................................................... 13
Installing the AWS CLI version 1 ................................................................................................ 14
Installing the AWS CLI Using the Bundled Installer ............................................................... 15
Installing the AWS CLI Using pip ........................................................................................ 15
Installing the AWS CLI in a Virtual Environment ................................................................... 16
Steps to Take after Installation .......................................................................................... 16
Detailed Instructions for Each Environment ......................................................................... 17
Bundled Installer .............................................................................................................. 17
Linux .............................................................................................................................. 20
macOS ............................................................................................................................ 25
Windows ......................................................................................................................... 28
Virtualenv ........................................................................................................................ 32
Using the AWS CLI version 1 with Earlier Versions of Python .................................................. 33
Configuring the AWS CLI ................................................................................................................... 35
Quickly Configuring the AWS CLI ............................................................................................... 35
Access Key and Secret Access Key ....................................................................................... 35
Region ............................................................................................................................ 36
Output Format ................................................................................................................. 36
Creating Multiple Profiles .......................................................................................................... 37
Configuration Settings and Precedence ....................................................................................... 37
Configuration and Credential File Settings ................................................................................... 38
Where Are Configuration Settings Stored? ........................................................................... 38
Supported config File Settings ......................................................................................... 39
Named Profiles ........................................................................................................................ 48
Using Profiles with the AWS CLI ......................................................................................... 49
Configuring the AWS CLI to use AWS Single Sign-On .................................................................... 50
Configuring a Named Profile to Use AWS SSO ..................................................................... 50
Using an AWS SSO Enabled Named Profile .......................................................................... 53
Environment Variables .............................................................................................................. 55
Command Line Options ............................................................................................................ 58
Sourcing Credentials with an External Process .............................................................................. 60
Getting Credentials from EC2 Instance Metadata .......................................................................... 61
Using an HTTP Proxy ................................................................................................................ 62
Authenticating to a Proxy .................................................................................................. 62
Using a Proxy on Amazon EC2 Instances ............................................................................. 62
Using an IAM Role in the AWS CLI .............................................................................................. 63
Configuring and Using a Role ............................................................................................ 64
Using MFA ....................................................................................................................... 65
Cross-Account Roles and External ID ................................................................................... 66
Specifying a Role Session Name for Easier Auditing .............................................................. 67
Assume Role with Web Identity .......................................................................................... 67
Clearing Cached Credentials ............................................................................................... 68
Command Completion .............................................................................................................. 68
Identify Your Shell ............................................................................................................ 69
iii
AWS Command Line Interface User Guide
iv
AWS Command Line Interface User Guide
v
AWS Command Line Interface User Guide
• Windows MSI installer version of AWS CLI version 1. The Windows MSI installer for AWS
CLI version 1 includes and uses its own embedded copy of Python, independent of any other
Python version that you might have installed. If you're using an MSI installer-based AWS CLI,
no changes are required.
• AWS CLI version 2. All installers for AWS CLI version 2 include and use an embedded copy
of Python, independent of any other Python version that you might have installed. If you're
using AWS CLI version 2, no changes are required.
For more information, see Using the AWS CLI version 1 with Earlier Versions of Python (p. 33)
in this guide, and the deprecation announcement in this blog post.
The AWS Command Line Interface (AWS CLI) is an open source tool that enables you to interact with
AWS services using commands in your command-line shell.
• Version 2.x – The current, generally available release of the AWS CLI that is intended for use in
production environments. This version does include some "breaking" changes from version 1 that
might require you to change your scripts so that they continue to operate as you expect. For a list
of new features and breaking changes in version 2, see Breaking Changes – Migrating from AWS CLI
version 1 to version 2 (p. 152).
• Version 1.x – The previous version of the AWS CLI that is available for backwards compatiblity.
Information in this guide applies to both versions unless we specifically state that it applies to only one
version or the other.
With minimal configuration, the AWS CLI enables you to start running commands that implement
functionality equivalent to that provided by the browser-based AWS Management Console from the
command prompt in your favorite terminal program:
• Linux shells – Use common shell programs such as bash, zsh, and tcsh to run commands in Linux or
macOS.
• Windows command line – On Windows, run commands at the Windows command prompt or in
PowerShell.
• Remotely – Run commands on Amazon Elastic Compute Cloud (Amazon EC2) instances through a
remote terminal program such as PuTTY or SSH, or with AWS Systems Manager.
All IaaS (infrastructure as a service) AWS administration, management, and access functions in the AWS
Management Console are available in the AWS API and CLI. New AWS IaaS features and services provide
1
AWS Command Line Interface User Guide
Using the Examples
full AWS Management Console functionality through the API and CLI at launch or within 180 days of
launch.
The AWS CLI provides direct access to the public APIs of AWS services. You can explore a service's
capabilities with the AWS CLI, and develop shell scripts to manage your resources. Or, you can take what
you learn to develop programs in other languages by using the AWS SDKs.
In addition to the low-level, API-equivalent commands, several AWS services provide customizations
for the AWS CLI. Customizations can include higher-level commands that simplify using a service with
a complex API. For example, the aws s3 commands provide a familiar syntax for managing files in
Amazon Simple Storage Service (Amazon S3).
aws s3 cp provides a shell-like copy command, and automatically performs a multipart upload to
transfer large files quickly and resiliently.
Performing the same task with the low-level commands (available under aws s3api) would take a lot
more effort.
Depending on your use case, you might want to choose one of the AWS SDKs or the AWS Tools for
PowerShell:
You can view—and fork—the source code for the AWS CLI on GitHub in the aws-cli repository. Join
the community of users on GitHub to provide feedback, request features, and submit your own
contributions!
• Prompt – The command prompt is typically displayed as a dollar sign followed by a space ($ ). For
commands that are Windows specific, C:\> is used as the prompt. Do not include the prompt when
you type commands.
• Directory – When commands must be executed from a specific directory, the directory name is shown
before the prompt symbol.
• User input – Command text that you should enter at the command line is formatted as user input.
• Replaceable text – Variable text, including names of resources that you choose, or IDs generated by
AWS services that you must include in commands, is formatted as replaceable text. In multiple-
2
AWS Command Line Interface User Guide
About Amazon Web Services
line commands or commands where specific keyboard input is required, keyboard commands can also
be shown as replaceable text.
• Output – Output returned by AWS services is shown under user input, and is formatted as computer
output.
For example, the following command includes user input, replaceable text, and output.
$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: ENTER
To use this example, enter aws configure at the command line, and then press Enter. The command
is aws configure. This command is interactive, so the AWS CLI outputs lines of text, prompting you to
enter additional information. Enter each of your access keys in turn, and then press Enter. Then, enter an
AWS Region name in the format shown, press Enter, and then press Enter a final time to skip the output
format setting. The final Enter command is shown as replaceable text because there is no user input for
that line. Otherwise, it would be implied.
The following example shows a simple noninteractive command with output from the service in JSON
format.
To use this example, enter the full text of the command (the highlighted text after the prompt), and
then press Enter. The name of the security group, my-sg, is replaceable. You can use the group name as
shown, but you probably want to use a more descriptive name.
Note
Arguments that must be replaced (such as AWS Access Key ID), and those that should be
replaced (such as group name), are both shown as replaceable text in italics. If an
argument must be replaced, it's noted in the text that describes the example.
The JSON document, including the curly braces, is output. If you configure your CLI to output in text or
table format, the output will be formatted differently. JSON is the default output format.
3
AWS Command Line Interface User Guide
AWS CLI version 2
AWS CLI version 2 is available to install only as a bundled installer. Although you might find it in some
package managers, these are not produced or managed by AWS and are therefore not official and not
supported by AWS. We recommend that you install the AWS CLI from only the official AWS distribution
points, as documented in this guide.
For information about how to install AWS CLI version 2, see Installing the AWS CLI version 2 (p. 4).
For information about how to install AWS CLI version 1, see Installing the AWS CLI version 1 (p. 14).
Topics
• Installing the AWS CLI version 2 on Linux (p. 5)
• Installing the AWS CLI version 2 on macOS (p. 9)
• Installing AWS CLI version 2 on Windows (p. 13)
4
AWS Command Line Interface User Guide
Installing on Linux
Topics
• Prerequisites (p. 5)
• Installing (p. 5)
• Upgrading (p. 6)
• Uninstalling (p. 7)
• Verifying the Integrity and Authenticity of the Downloaded Files (p. 7)
Prerequisites
• The AWS CLI version 2 has no dependencies on other software packages. It has a self-contained,
embedded copy of all dependencies included in the installer. You no longer need to install and
maintain Python to use the AWS CLI.
• You must be able to "unzip" the downloaded package. If your operating system doesn't have a built-in
unzip command, use your favorite package manager to download it or an equivalent.
• We support the AWS CLI version 2 on recent distributions of CentOS, Fedora, Ubuntu, Amazon Linux 1,
and Amazon Linux 2.
Installing
Follow these steps from the command line to install the AWS CLI on Linux. The only difference in the
following commands is the name of the file that you download. Everything else is the same.
Important
Ensure that the paths you install to contain no volume or folder names that contain any spaces
or the installation fails.
We provide the steps in one easy to copy and paste group. See the descriptions of each line in the steps
that follow.
You can verify that integrity and authenticity of the installation file after you download it and before you
extract the files from the package. For more information, see Verifying the Integrity and Authenticity of
the Downloaded Files (p. 7).
1. You can download the file using the curl command. The options on the following example
command cause the downloaded file to be written to the current directory with the local name
awscliv2.zip.
In this example, the -o option specifies the file name that the downloaded package is written to. In
the previous example, the file is written to awscliv2.zip in the current folder.
Alternatively, you can use your browser to download the installer from the following URL: https://
awscli.amazonaws.com/awscli-exe-linux-x86_64.zip
5
AWS Command Line Interface User Guide
Installing on Linux
You can verify the integrity and authenticity of the installation file after you download it. For more
information, see Verifying the Integrity and Authenticity of the Downloaded Files (p. 7) before
you unzip the package.
2. Unzip the installer. The following example command unzips the package to the current folder. If
your Linux distribution doesn't have a built-in unzip command, use your favorite package manager,
or an equivalent, to install it.
$ unzip awscliv2.zip
$ sudo ./aws/install
The installation command is a file named install found in the newly unzipped aws folder. By
default, the files are all installed to /usr/local/aws, and a symlink is created in /usr/local/
bin. The command includes sudo to grant write permissions to those folders. You can install
without sudo if you specify folders that you already have write permissions to.
You can use the following parameters with the install command to specify those folders:
Important
Ensure that the paths you provide to the -i and -b parameters contain no volume name or
folder names that contain any space characters or other white space characters. If there is a
space, the installation fails.
• --install-dir or -i
This option specifies the folder to copy all of the files to. This example installs the files to a folder
named /usr/local/aws-cli. You must have write permissions to /usr/local to create this
folder.
This option specifies that the main aws program in the install folder is symlinked to the file aws
in the specified path. This example creates the symlink /usr/local/bin/aws. You must have
write permissions to the specified folder. Creating a symlink to a folder that is already in your path
eliminates the need to add the install directory to the user's $PATH variable.
$ aws --version
aws-cli/2.0.0 Python/3.7.4 Linux/4.14.133-113.105.amzn2.x86_64 botocore/2.0.0
Upgrading
To upgrade your copy of the AWS CLI version 2, run the same steps that you used to install it, but this
time include the --update or -u option on the install command line. If the installer finds an existing
version of the AWS CLI version 2 in the target installation folder and the --update option isn't used, the
install fails.
6
AWS Command Line Interface User Guide
Installing on Linux
Find the symlink that the installer created. This gives you the path to use with the --bin-dir
parameter.
$ which aws
/usr/local/bin/aws
Use that to find the folder that the symlink points to. This gives you the path to use with the --
install-dir parameter.
$ ls -l /usr/local/bin/aws
lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/aws -> /usr/local/aws-cli/v2/
current/bin/aws
Uninstalling
To uninstall the AWS CLI version 2, run the following commands, substituting the paths you used to
install.
$ which aws
/usr/local/bin/aws
Use that to find the --install-dir folder that the symlink points to.
$ ls -l /usr/local/bin/aws
lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/aws -> /usr/local/aws-cli/v2/
current/bin/aws
Now delete the two symlinks in the --bin-dir folder. If your user account has write permission to these
folders, you don't need to use sudo.
$ sudo rm /usr/local/bin/aws
$ sudo rm /usr/local/bin/aws2_completer
Finally, you can delete the --install-dir folder. Again, if your user account has write permission to
this folder, you don't need to use sudo.
The following example assumes you downloaded the installer package and saved it locally as
awscliv2.zip. If you named it something else, substitute that name in the following steps.
7
AWS Command Line Interface User Guide
Installing on Linux
Steps 1, 2, and 3 are prerequisite steps that you need to perform only once. You should perform steps 4
and 5 every time you download a new copy of the installer package.
1. Download and install the gpg command using your favorite package manager. For more information
about GnuPG, see the GnuPG website.
2. Create a text file and paste in the following text.
mQINBF2Cr7UBEADJZHcgusOJl7ENSyumXh85z0TRV0xJorM2B/JL0kHOyigQluUG
ZMLhENaG0bYatdrKP+3H91lvK050pXwnO/R7fB/FSTouki4ciIx5OuLlnJZIxSzx
PqGl0mkxImLNbGWoi6Lto0LYxqHN2iQtzlwTVmq9733zd3XfcXrZ3+LblHAgEt5G
TfNxEKJ8soPLyWmwDH6HWCnjZ/aIQRBTIQ05uVeEoYxSh6wOai7ss/KveoSNBbYz
gbdzoqI2Y8cgH2nbfgp3DSasaLZEdCSsIsK1u05CinE7k2qZ7KgKAUIcT/cR/grk
C6VwsnDU0OUCideXcQ8WeHutqvgZH1JgKDbznoIzeQHJD238GEu+eKhRHcz8/jeG
94zkcgJOz3KbZGYMiTh277Fvj9zzvZsbMBCedV1BTg3TqgvdX4bdkhf5cH+7NtWO
lrFj6UwAsGukBTAOxC0l/dnSmZhJ7Z1KmEWilro/gOrjtOxqRQutlIqG22TaqoPG
fYVN+en3Zwbt97kcgZDwqbuykNt64oZWc4XKCa3mprEGC3IbJTBFqglXmZ7l9ywG
EEUJYOlb2XrSuPWml39beWdKM8kzr1OjnlOm6+lpTRCBfo0wa9F8YZRhHPAkwKkX
XDeOGpWRj4ohOx0d2GWkyV5xyN14p2tQOCdOODmz80yUTgRpPVQUtOEhXQARAQAB
tCFBV1MgQ0xJIFRlYW0gPGF3cy1jbGlAYW1hem9uLmNvbT6JAlQEEwEIAD4WIQT7
Xbd/1cEYuAURraimMQrMRnJHXAUCXYKvtQIbAwUJB4TOAAULCQgHAgYVCgkICwIE
FgIDAQIeAQIXgAAKCRCmMQrMRnJHXJIXEAChLUIkg80uPUkGjE3jejvQSA1aWuAM
yzy6fdpdlRUz6M6nmsUhOExjVIvibEJpzK5mhuSZ4lb0vJ2ZUPgCv4zs2nBd7BGJ
MxKiWgBReGvTdqZ0SzyYH4PYCJSE732x/Fw9hfnh1dMTXNcrQXzwOmmFNNegG0Ox
au+VnpcR5Kz3smiTrIwZbRudo1ijhCYPQ7t5CMp9kjC6bObvy1hSIg2xNbMAN/Do
ikebAl36uA6Y/Uczjj3GxZW4ZWeFirMidKbtqvUz2y0UFszobjiBSqZZHCreC34B
hw9bFNpuWC/0SrXgohdsc6vK50pDGdV5kM2qo9tMQ/izsAwTh/d/GzZv8H4lV9eO
tEis+EpR497PaxKKh9tJf0N6Q1YLRHof5xePZtOIlS3gfvsH5hXA3HJ9yIxb8T0H
QYmVr3aIUes20i6meI3fuV36VFupwfrTKaL7VXnsrK2fq5cRvyJLNzXucg0WAjPF
RrAGLzY7nP1xeg1a0aeP+pdsqjqlPJom8OCWc1+6DWbg0jsC74WoesAqgBItODMB
rsal1y/q+bPzpsnWjzHV8+1/EtZmSc8ZUGSJOPkfC7hObnfkl18h+1QtKTjZme4d
H17gsBJr+opwJw/Zio2LMjQBOqlm3K1A4zFTh7wBC7He6KPQea1p2XAMgtvATtNe
YLZATHZKTJyiqA==
=vYOk
-----END PGP PUBLIC KEY BLOCK-----
3. Import the AWS CLI public key with the following command, substituting public-key-file-name
with whatever you named the file in step 2.
4. Download the AWS CLI signature file for the package you downloaded. It has the same path and
name as the .zip file it corresponds to, but has the extension .sig. In the following examples, we
save it to the current folder as a file named awscliv2.sig.
8
AWS Command Line Interface User Guide
Installing on macOS
5. Verify the signature, passing both the downloaded .sig and .zip file names as parameters to the
gpg command.
Important
The warning in the output is expected and doesn't indicate a problem. It occurs because
there isn't a chain of trust between your personal PGP key (if you have one) and the AWS
CLI PGP key. For more information, see Web of trust.
• Recommended: Uninstall AWS CLI version 1 and use only AWS CLI version 2.
• Use your operating system's ability to create an alias or sym link with a different name for one
of the two aws commands. For example, you could use symbolic links or alias in Linux
and macOS, or doskey in Windows.
Topics
• Prerequisites (p. 9)
• Installing using the macOS graphical interface (p. 10)
• Installing using the macOS command line (p. 10)
• Confirming the installation (p. 12)
• Upgrading (p. 12)
• Uninstalling (p. 12)
Prerequisites
• The AWS CLI version 2 has no dependencies on other software packages. It has a self-contained,
embedded copy of all dependencies included in the installer. You no longer need to install and
maintain Python to use the AWS CLI.
• We support the AWS CLI version 2 on versions of macOS that are supported by Apple, including High
Sierra (10.13), Mojave (10.14), and Catalina (10.15).
9
AWS Command Line Interface User Guide
Installing on macOS
You can install using either the graphical interface or the command line.
4. You can view debug logs for the installation by pressing CMD+L anywhere in the installer. This opens
up a log pane that enables you to filter and save the log. The log file is also automatically saved to /
var/log/install.log.
5. Follow the steps in the section Confirming the installation (p. 12) below.
If you have sudo permissions, you can install the AWS CLI version 2 for all users on the computer.
We provide the steps in one easy to copy and paste group. See the descriptions of each line in the steps
that follow.
10
AWS Command Line Interface User Guide
Installing on macOS
1. Download the file using the curl command. The options on the following example command cause
the downloaded file to be written to the current directory with the local name .
In this example, the -o option specifies the file name that the downloaded package is written to. In
the previous example, the file is written to AWSCLIV2.pkg in the current folder.
2. Run the standard macOS installer program, specifying the downloaded .pkg file as the source.
You must specify the name of the package to install by using the -pkg parameter, and the drive to
which to install the package by using the -target / parameter. The files are installed to /usr/
local/aws-cli, and a symlink is automatically created in /usr/local/bin. You must include
sudo on the command to grant write permissions to those folders.
3. You can view debug logs after installation is complete. The logs are written to /var/log/
install.log.
4. Follow the steps in the section Confirming the installation (p. 12) below.
To install for only the current user using the macOS command line
If you have sudo permissions, you can install the AWS CLI version 2 for all users on the computer.
1. Download the file using the curl command. The options on the following example command cause
the downloaded file to be written to the current directory with the local name .
In this example, the -o option specifies the file name that the downloaded package is written to. In
the previous example, the file is written to AWSCLIV2.pkg in the current folder.
2. Before you can run the installer, you must create a file that specifies the folder to which the AWS CLI
is installed. This file is an XML formatted file that looks like the following example. Leave all value as
shown, expect you must replace the path /Users/myusername in line 9 with the path to the folder
you want the AWS CLI version 2 installed to. The folder must already exist, or the command fails. This
XML example specifies that the installer is install the AWS CLI in the folder /Users/myusername,
where it creates a folder named aws-cli.
3. Now you can run the standard macOS installer program with the following options:
• Specify the name of the package to install by using the -pkg parameter.
11
AWS Command Line Interface User Guide
Installing on macOS
• To specify a current user only installation, you must set the parameter --target
CurrentUserHomeDirectory.
• Specify the path (relative to the current folder) and name of the XML file that you created in the
previous step in the --applyChoiceChangesXML parameter.
5. You can view debug logs after installation is complete. The logs are written to /var/log/
install.log.
6. Follow the steps in the section Confirming the installation (p. 12) below.
$ which aws
/usr/local/bin/aws
$ aws --version
aws-cli/2.0.0 Python/3.7.4 Darwin/18.7.0 botocore/2.0.0
Upgrading
To upgrade your copy of the AWS CLI version 2, run the same steps that you used to install it in the
previous section. Download and run the package. If it finds that the AWS CLI is already installed, then it
automatically overwrites and upgrades the existing installation.
Uninstalling
To uninstall the AWS CLI version 2, run the following commands, substituting the paths you used to
install.
Find the folder that contains the symlinks to the main program and the completer.
$ which aws
/usr/local/bin/aws
Use that information to find the installation folder that the symlinks point to.
12
AWS Command Line Interface User Guide
Installing on Windows
$ ls -l /usr/local/bin/aws
lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/aws -> /usr/local/aws-cli/aws
Now delete the two symlinks in the first folder. If your user account already has write permission to these
folders, you don't need to use sudo.
$ sudo rm /usr/local/bin/aws
$ sudo rm /usr/local/bin/aws_completer
Finally, you can delete the main installation folder. Use sudo to gain write access to the /usr/local
folder.
Topics
• Prerequisites for Windows (p. 13)
• Installing on Windows (p. 13)
• Upgrading on Windows (p. 14)
• Removing from Windows (p. 14)
Installing on Windows
For Windows users, the MSI installation package offers a familiar and convenient way to install the AWS
CLI version 2 without installing any other prerequisites.
1. Download the AWS CLI MSI installer for Windows (64-bit) at https://awscli.amazonaws.com/
AWSCLIV2.msi
2. Run the downloaded MSI installer and follow the onscreen instructions. By default, the AWS CLI
installs to C:\Program Files\Amazon\AWSCLIV2.
3. To confirm the installation, use the aws --version command at a command prompt (open the
Start menu and search for cmd to start a command prompt).
Don't include the prompt symbol (C:\>, shown above) when you type a command. These are included in
program listings to differentiate commands that you type from output returned by the AWS CLI. The rest
of this guide uses the generic prompt symbol, $ , except in cases where a command is Windows-specific.
13
AWS Command Line Interface User Guide
Installing the AWS CLI version 1
If Windows is unable to find the program, you might need to close and reopen the command prompt to
refresh the path, or add the installation directory to your PATH (p. 31) environment variable manually.
Upgrading on Windows
AWS CLI is updated regularly. Check the Releases page on GitHub to see when the latest version was
released.
To update to the latest version, download the latest version of the MSI installer and run it, as described
previously. It automatically overwrites the previous version.
You can also launch the Programs and Features program from the command line with the following
command.
C:\> appwiz.cpl
We recommend that you AWS CLI version 2 instead. For information about how to install version 2, see
Installing the AWS CLI version 2 (p. 4).
You can install the AWS CLI version 1 using any of the following techniques:
Prerequisites
14
AWS Command Line Interface User Guide
Installing the AWS CLI Using the Bundled Installer
You can find the version number of the most recent CLI at: https://github.com/aws/aws-cli/blob/
master/CHANGELOG.rst.
In this guide, the commands shown assume you have Python v3 installed and the pip commands shown
use the pip3 version.
On Windows, the bundled installer is in the form of an MSI installer (p. 29).
If you already have pip and a supported version of Python, you can install the AWS CLI by using the
following command. If you have Python version 3 installed, we recommend that you use the pip3
command.
The --upgrade option tells pip3 to upgrade any requirements that are already installed. The --user
option tells pip3 to install the program to a subdirectory of your user directory to avoid modifying
libraries used by your operating system.
Use the pip3 list -o command to check which packages are "outdated".
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Linux/4.14.133-113.105.amzn2.x86_64 botocore/1.13
$ pip3 list -o
Package Version Latest Type
---------- -------- -------- -----
awscli 1.16.170 1.16.198 wheel
botocore 1.12.160 1.12.188 wheel
Because the previous command shows that there is a newer version of the AWS CLI available, you can run
pip3 install --upgrade to get the latest version.
15
AWS Command Line Interface User Guide
Installing the AWS CLI in a Virtual Environment
Collecting awscli
Downloading https://files.pythonhosted.org/packages/dc/70/
b32e9534c32fe9331801449e1f7eacba6a1992c2e4af9c82ac9116661d3b/awscli-1.16.198-py2.py3-none-
any.whl (1.7MB)
|████████████████████████████████| 1.7MB 1.6MB/s
Collecting botocore==1.12.188 (from awscli)
Using cached https://files.pythonhosted.org/packages/10/
cb/8dcfb3e035a419f228df7d3a0eea5d52b528bde7ca162f62f3096a930472/botocore-1.12.188-py2.py3-
none-any.whl
Requirement already satisfied, skipping upgrade: docutils>=0.10 in ./venv/lib/python3.7/
site-packages (from awscli) (0.14)
Requirement already satisfied, skipping upgrade: rsa<=3.5.0,>=3.1.2 in ./venv/lib/
python3.7/site-packages (from awscli) (3.4.2)
Requirement already satisfied, skipping upgrade: colorama<=0.3.9,>=0.2.5 in ./venv/lib/
python3.7/site-packages (from awscli) (0.3.9)
Requirement already satisfied, skipping upgrade: PyYAML<=5.1,>=3.10; python_version !=
"2.6" in ./venv/lib/python3.7/site-packages (from awscli) (3.13)
Requirement already satisfied, skipping upgrade: s3transfer<0.3.0,>=0.2.0 in ./venv/lib/
python3.7/site-packages (from awscli) (0.2.0)
Requirement already satisfied, skipping upgrade: jmespath<1.0.0,>=0.7.1 in ./venv/lib/
python3.7/site-packages (from botocore==1.12.188->awscli) (0.9.4)
Requirement already satisfied, skipping upgrade: urllib3<1.26,>=1.20; python_version >=
"3.4" in ./venv/lib/python3.7/site-packages (from botocore==1.12.188->awscli) (1.24.3)
Requirement already satisfied, skipping upgrade: python-dateutil<3.0.0,>=2.1;
python_version >= "2.7" in ./venv/lib/python3.7/site-packages (from botocore==1.12.188-
>awscli) (2.8.0)
Requirement already satisfied, skipping upgrade: pyasn1>=0.1.3 in ./venv/lib/python3.7/
site-packages (from rsa<=3.5.0,>=3.1.2->awscli) (0.4.5)
Requirement already satisfied, skipping upgrade: six>=1.5 in ./venv/lib/python3.7/site-
packages (from python-dateutil<3.0.0,>=2.1; python_version >= "2.7"->botocore==1.12.188-
>awscli) (1.12.0)
Installing collected packages: botocore, awscli
Found existing installation: botocore 1.12.160
Uninstalling botocore-1.12.160:
Successfully uninstalled botocore-1.12.160
Found existing installation: awscli 1.16.170
Uninstalling awscli-1.16.170:
Successfully uninstalled awscli-1.16.170
Successfully installed awscli-1.16.198 botocore-1.12.188
• Linux – Add the AWS CLI version 1 Executable to Your Command Line Path (p. 23)
16
AWS Command Line Interface User Guide
Detailed Instructions for Each Environment
• Windows – Add the AWS CLI version 1 Executable to Your Command Line Path (p. 31)
• macOS – Add the AWS CLI version 1 Executable to Your macOS Command Line Path (p. 28)
Verify that the AWS CLI installed correctly by running aws --version.
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Linux/4.14.133-113.105.amzn2.x86_64 botocore/1.13
You store credential information locally by defining profiles (p. 48) in the AWS CLI configuration
files (p. 38), which are stored by default in your user's home directory. For more information, see
Configuring the AWS CLI (p. 35).
Note
If you are running in an Amazon EC2 instance, credentials can be automatically retrieved
from the instance metadata. For more information, see Getting Credentials from EC2 Instance
Metadata (p. 61).
If you don't have Python and pip, use the procedure for your environment.
17
AWS Command Line Interface User Guide
Bundled Installer
The bundled installer doesn't support installing to paths that contain spaces.
Important
On January 10th, 2020, AWS CLI version 1, which requires a separate installation of Python
to operate, stopped supporting Python versions 2.6 and 3.3. All builds of AWS CLI version 1
released after January 10th, 2020, starting with version 1.17, require Python 2.7, Python 3.4, or
a later version to successfully use the AWS CLI.
This change does not affect the following versions of the AWS CLI:
• Windows MSI installer version of AWS CLI version 1. The Windows MSI installer for AWS
CLI version 1 includes and uses its own embedded copy of Python, independent of any other
Python version that you might have installed. If you're using an MSI installer-based AWS CLI,
no changes are required.
• AWS CLI version 2. All installers for AWS CLI version 2 include and use an embedded copy
of Python, independent of any other Python version that you might have installed. If you're
using AWS CLI version 2, no changes are required.
For more information, see Using the AWS CLI version 1 with Earlier Versions of Python (p. 33)
in this guide, and the deprecation announcement in this blog post.
Sections
• Prerequisites (p. 18)
• Install the AWS CLI version 1 Using the Bundled Installer (p. 18)
• Install the AWS CLI version 1 without Sudo (Linux or macOS) (p. 19)
• Uninstall the AWS CLI version 1 (p. 20)
Prerequisites
• Linux or macOS
• Python 2 version 2.7+ or Python 3 version 3.4+
$ python --version
If your computer doesn't already have Python installed, or you would like to install a different version of
Python, follow the procedure in Install the AWS CLI version 1 on Linux (p. 20).
• https://s3.amazonaws.com/aws-cli/awscli-bundle.zip
The following is a summary of the installation commands explained below that you can cut and paste to
run as a single set of commands.
18
AWS Command Line Interface User Guide
Bundled Installer
Follow these steps from the command line to install the AWS CLI version 1 using the bundled installer.
1. Download the AWS CLI version 1 bundled installer using the following command.
$ unzip awscli-bundle.zip
Note
If you don't have unzip, use your Linux distribution's built-in package manager to install it.
3. Run the install program.
Note
By default, the install script runs under the system default version of Python. If you have
installed an alternative version of Python and want to use that to install the AWS CLI, run
the install script with that version by absolute path to the Python executable, as follows.
The installer installs the AWS CLI at /usr/local/aws and creates the symlink aws at the /usr/local/
bin directory. Using the -b option to create a symlink eliminates the need to specify the install directory
in the user's $PATH variable. This should enable all users to call the AWS CLI by typing aws from any
directory.
$ ./awscli-bundle/install -h
This installs the AWS CLI to the default location (~/.local/lib/aws) and creates a symbolic link
(symlink) at ~/bin/aws. Make sure that ~/bin is in your PATH environment variable for the symlink to
work.
$ echo $PATH | grep ~/bin // See if $PATH contains ~/bin (output will be empty if it
doesn't)
19
AWS Command Line Interface User Guide
Linux
Tip
To ensure that your $PATH settings are retained between sessions, add the export line to your
shell profile (~/.profile, ~/.bash_profile, and so on).
• Windows MSI installer version of AWS CLI version 1. The Windows MSI installer for AWS
CLI version 1 includes and uses its own embedded copy of Python, independent of any other
Python version that you might have installed. If you're using an MSI installer-based AWS CLI,
no changes are required.
• AWS CLI version 2. All installers for AWS CLI version 2 include and use an embedded copy
of Python, independent of any other Python version that you might have installed. If you're
using AWS CLI version 2, no changes are required.
For more information, see Using the AWS CLI version 1 with Earlier Versions of Python (p. 33)
in this guide, and the deprecation announcement in this blog post.
You can install version 1 of the AWS Command Line Interface (AWS CLI) and its dependencies on most
Linux distributions by using pip, a package manager for Python.
Although the awscli package is available in repositories for other package managers such as apt and
yum, these are not produced or managed by AWS and are therefore not official and not supported by
AWS. We recommend that you install the AWS CLI from only the official AWS distribution points, as
documented in this guide.
If you already have pip, follow the instructions in the main installation topic (p. 4). Run pip --
version to see if your version of Linux already includes Python and pip. We recommend that if you
have Python version 3+ installed, you use the pip3 command.
$ pip3 --version
If you don't already have pip installed, check which version of Python is installed.
$ python --version
or
20
AWS Command Line Interface User Guide
Linux
$ python3 --version
If you don't already have Python 2 version 2.7+ or Python 3 version 3.4+, you must first install
Python (p. 24). If you do have Python installed, proceed to installing pip and the AWS CLI.
Sections
• Install pip (p. 21)
• Install the AWS CLI version 1 with pip (p. 22)
• Upgrading to the Latest Version of the AWS CLI version 1 (p. 22)
• Add the AWS CLI version 1 Executable to Your Command Line Path (p. 23)
• Installing Python on Linux (p. 24)
• Install the AWS CLI version 1 on Amazon Linux (p. 24)
Install pip
If you don't already have pip installed, you can install it by using the script that the Python Packaging
Authority provides.
To install pip
1. Use the curl command to download the installation script. The following command uses the -O
(uppercase "O") parameter to specify that the downloaded file is to be stored in the current folder
using the same name it has on the remote host.
$ curl -O https://bootstrap.pypa.io/get-pip.py
2. Run the script with Python to download and install the latest version of pip and other required
support packages.
When you include the --user switch, the script installs pip to the path ~/.local/bin.
3. Ensure the folder that contains pip is part of your PATH variable.
a. Find your shell's profile script in your user folder. If you're not sure which shell you have, run echo
$SHELL.
$ ls -a ~
. .. .bash_logout .bash_profile .bashrc Desktop Documents Downloads
export PATH=~/.local/bin:$PATH
21
AWS Command Line Interface User Guide
Linux
This command inserts the path, ~/.local/bin in this example, at the front of the existing PATH
variable.
c. Reload the profile into your current session to put those changes into effect.
$ source ~/.bash_profile
$ pip3 --version
pip 19.2.3 from ~/.local/lib/python3.7/site-packages (python 3.7)
When you use the --user switch, pip installs the AWS CLI to ~/.local/bin.
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Linux/4.14.133-113.105.amzn2.x86_64 botocore/1.13
If you get an error, see Troubleshooting AWS CLI Errors (p. 145).
Use the pip list -o command to check which packages are "outdated".
$ aws --version
aws-cli/1.16.170 Python/3.7.3 Linux/4.14.123-111.109.amzn2.x86_64 botocore/1.12.160
$ pip3 list -o
Package Version Latest Type
---------- -------- -------- -----
awscli 1.16.170 1.16.198 wheel
botocore 1.12.160 1.12.188 wheel
Because the previous command shows that there is a newer version of the AWS CLI version 1 available,
you can run pip install --upgrade to get the latest version.
22
AWS Command Line Interface User Guide
Linux
You can verify which folder pip installed the AWS CLI in by running the following command.
$ which aws
/home/username/.local/bin/aws
If you omitted the --user switch and so didn't install in user mode, the executable might be in the bin
folder of your Python installation. If you don't know where Python is installed, run this command.
$ which python
/usr/local/bin/python
The output might be the path to a symlink, not to the actual executable. Run ls -al to see where it
points.
$ ls -al /usr/local/bin/python
/usr/local/bin/python -> ~/.local/Python/3.6/bin/python3.6
If this is the same folder you added to the path in step 3 in Install pip (p. 21), you're done. Otherwise,
perform those same steps 3a–3c again, adding this folder to the path.
23
AWS Command Line Interface User Guide
Linux
$ python --version
$ python3 --version
Note
If your Linux distribution came with Python, you might need to install the Python developer
package to get the headers and libraries required to compile extensions, and install the
AWS CLI. Use your package manager to install the developer package (typically named
python-dev or python-devel).
2. If Python 2 version 2.7+ or Python 3 version 3.4+ or later is not installed, install Python with your
distribution's package manager. The command and package name varies:
• On Debian derivatives such as Ubuntu, use apt. Check the apt repository for the versions of
Python available to you. Then, run a command similar to the following, substituting the correct
package name.
• On Red Hat and derivatives, use yum. Check the yum repository for the versions of Python
available to you. Then, run a command similar to the following, substituting the correct package
name.
• On SUSE and derivatives, use zypper. Check the repository for the versions of Python available to
you. Then, run a command similar to the following, substituting the correct package name.
See the documentation for your system's package manager and for Python for more information
about where it is installed and how to use it.
3. Open a command prompt or shell and run the following command to verify that Python installed
correctly.
$ python3 --version
Python 3.7.4
24
AWS Command Line Interface User Guide
macOS
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Linux/4.14.133-113.105.amzn2.x86_64 botocore/1.13
Important
Using sudo to complete a command grants the command full access to your system. We
recommend using that command only when no more secure option exists. For commands like
pip, we recommend that you avoid using sudo by using a Python virtual environment (venv) or
by specifying the --user option to install in the user's folders instead of the system's folders.
If you use the yum package manager, you can install the AWS CLI with the command yum install
aws-cli. You can use the command yum update to get the latest version available in the yum
repository.
Note
The yum repository is not owned or maintained by Amazon and might not contain the latest
version. Instead, we recommend that you use pip to get the latest version.
Prerequisites
Verify that Python and pip are already installed. For more information, see Install the AWS CLI version 1
on Linux (p. 20).
1. Use pip3 install to install the latest version of the AWS CLI version 1. We recommend that if you
have Python version 3+ installed that you use pip3. If you run the command from within a Python
virtual environment (venv), then you don't need to use the --user option.
2. If the folder containing the aws command is not already in your search path, add it to the beginning
of your PATH variable.
$ export PATH=$HOME/.local/bin:$PATH
Add this command to the end of your profile's startup script (for example, ~/.bashrc) to persist the
change between command line sessions.
3. Verify that you're running new version with aws --version.
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Linux/4.14.133-113.105.amzn2.x86_64 botocore/1.13
• Windows MSI installer version of AWS CLI version 1. The Windows MSI installer for AWS
CLI version 1 includes and uses its own embedded copy of Python, independent of any other
25
AWS Command Line Interface User Guide
macOS
Python version that you might have installed. If you're using an MSI installer-based AWS CLI,
no changes are required.
• AWS CLI version 2. All installers for AWS CLI version 2 include and use an embedded copy
of Python, independent of any other Python version that you might have installed. If you're
using AWS CLI version 2, no changes are required.
For more information, see Using the AWS CLI version 1 with Earlier Versions of Python (p. 33)
in this guide, and the deprecation announcement in this blog post.
Important
The bundled installer doesn't support installing to paths that contain spaces.
Sections
• Prerequisites (p. 26)
• Install the AWS CLI version 1 Using the Bundled Installer (p. 26)
• Install the AWS CLI version 1 on macOS Using pip (p. 27)
• Add the AWS CLI version 1 Executable to Your macOS Command Line Path (p. 28)
Prerequisites
• Python 2 version 2.7+ or Python 3 version 3.4+
$ python --version
If your computer doesn't already have Python installed, or if you want to install a different version of
Python, follow the procedure in Install the AWS CLI version 1 on Linux (p. 20).
1. Here are the steps described below in one easy to copy-and-paste group. See the descriptions of
each line in the steps that follow.
Note
If you don't have unzip, use your favorite package manager or an equivalent to install it.
2. Run the install program. This command installs the AWS CLI to /usr/local/aws and creates the
symlink aws in the /usr/local/bin directory. Using the -b option to create a symlink eliminates
the need to specify the install directory in the user's $PATH variable. This should enable all users to
call the AWS CLI by typing aws from any directory.
26
AWS Command Line Interface User Guide
macOS
Note
By default, the install script runs under the system's default version of Python. If you have
installed an alternative version of Python and want to use that to install the AWS CLI, run
the install script and specify that version by including the absolute path to the Python
application, as shown in the following example.
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Darwin/18.7.0 botocore/1.13
If the program isn't found, add it to your command line path (p. 28).
$ ./awscli-bundle/install -h
$ pip3 --version
1. Download and install the latest version of Python from the downloads page of Python.org.
2. Download and run the pip3 installation script provided by the Python Packaging Authority.
$ curl -O https://bootstrap.pypa.io/get-pip.py
$ python3 get-pip.py --user
3. Use your newly installed pip3 to install the AWS CLI. We recommend that if you use Python version
3+, that you use the pip3 command.
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Darwin/18.7.0 botocore/1.13
If the program isn't found, add it to your command line path (p. 28).
27
AWS Command Line Interface User Guide
Windows
Example AWS CLI install location - macOS with Python 3.6 and pip (user mode)
~/Library/Python/3.7/bin
Substitute the version of Python that you have for the version in the example above.
$ which python
/usr/local/bin/python
The output might be the path to a symlink, not the actual program. Run ls -al to see where it points.
$ ls -al /usr/local/bin/python
~/Library/Python/3.7/bin/python3.7
pip installs programs in the same folder that contains the Python application. Add this folder to your
PATH variable.
1. Find your shell's profile script in your user folder. If you're not sure which shell you have, run echo
$SHELL.
$ ls -a ~
. .. .bash_logout .bash_profile .bashrc Desktop Documents Downloads
export PATH=~/.local/bin:$PATH
This command adds a path, ~/.local/bin in this example, to the current PATH variable.
3. Load the updated profile into your current session.
$ source ~/.bash_profile
28
AWS Command Line Interface User Guide
Windows
Important
On January 10th, 2020, AWS CLI version 1, which requires a separate installation of Python
to operate, stopped supporting Python versions 2.6 and 3.3. All builds of AWS CLI version 1
released after January 10th, 2020, starting with version 1.17, require Python 2.7, Python 3.4, or
a later version to successfully use the AWS CLI.
This change does not affect the following versions of the AWS CLI:
• Windows MSI installer version of AWS CLI version 1. The Windows MSI installer for AWS
CLI version 1 includes and uses its own embedded copy of Python, independent of any other
Python version that you might have installed. If you're using an MSI installer-based AWS CLI,
no changes are required.
• AWS CLI version 2. All installers for AWS CLI version 2 include and use an embedded copy
of Python, independent of any other Python version that you might have installed. If you're
using AWS CLI version 2, no changes are required.
For more information, see Using the AWS CLI version 1 with Earlier Versions of Python (p. 33)
in this guide, and the deprecation announcement in this blog post.
Sections
• Install the AWS CLI version 1 Using the MSI Installer (p. 29)
• Install the AWS CLI version 1 Using Python and pip on Windows (p. 30)
• Add the AWS CLI version 1 Executable to Your Command Line Path (p. 31)
When updates are released, you must repeat the installation process to get the latest version of the AWS
CLI version 1.
• Download the AWS CLI MSI installer for Windows (64-bit) from https://s3.amazonaws.com/aws-
cli/AWSCLI64PY3.msi
• Download the AWS CLI MSI installer for Windows (32-bit) from https://s3.amazonaws.com/aws-
cli/AWSCLI32PY3.msi
• Download the AWS CLI combined setup file for Windows from https://s3.amazonaws.com/aws-
cli/AWSCLISetup.exe (includes both the 32-bit and 64-bit MSI installers and will automatically
install the correct version)
Note
The MSI installer for the AWS CLI version 1 doesn't work with Windows Server 2008 (version
6.0.6002). Use pip (p. 30) to install with this version of Windows Server.
2. Run the downloaded MSI installer or the setup file.
3. Follow the onscreen instructions.
By default, the AWS CLI version 1 installs to C:\Program Files\Amazon\AWSCLI (64-bit version)
or C:\Program Files (x86)\Amazon\AWSCLI (32-bit version). To confirm the installation, use the
29
AWS Command Line Interface User Guide
Windows
aws --version command at a command prompt (open the Start menu and search for cmd to start a
command prompt).
Don't include the prompt symbol (C:\>, shown above) when you type a command. These are included in
program listings to differentiate commands that you type from output returned by the CLI. The rest of
this guide uses the generic prompt symbol, $ , except in cases where a command is Windows-specific.
If Windows is unable to find the program, you might need to close and reopen the command prompt to
refresh the path, or add the installation directory to your PATH (p. 31) environment variable manually.
You can also launch the Programs and Features program from the command line with the following
command.
C:\> appwiz.cpl
Install the AWS CLI version 1 Using Python and pip on Windows
The Python Software Foundation provides installers for Windows that include pip.
1. Download the Python Windows x86-64 installer from the downloads page of Python.org.
2. Run the installer.
3. Choose Add Python 3 to PATH.
4. Choose Install Now.
The installer installs Python in your user folder and adds its program folders to your user path.
If you use Python version 3+, we recommend that you use the pip3 command.
30
AWS Command Line Interface User Guide
Windows
If this command returns a response, then you should be ready to run the tool. The where command, by
default, shows where in the system PATH it found the specified program.
You can find where the aws program is installed by running the following command.
If the where command returns the following error, it's not in the system PATH and you can't run it by
simply typing its name.
In that case, run the where command with the /R path parameter to tell it to search all folders, and
then add the path manually. Use the command line or File Explorer to discover where it is installed on
your computer.
The paths that show up depend on your platform and which method you used to install the AWS CLI.
31
AWS Command Line Interface User Guide
Virtualenv
Note
Folder names that include version numbers can vary. The examples above reflect the use of
Python version 3.7. Replace as needed with the version number you are using.
• Windows MSI installer version of AWS CLI version 1. The Windows MSI installer for AWS
CLI version 1 includes and uses its own embedded copy of Python, independent of any other
Python version that you might have installed. If you're using an MSI installer-based AWS CLI,
no changes are required.
• AWS CLI version 2. All installers for AWS CLI version 2 include and use an embedded copy
of Python, independent of any other Python version that you might have installed. If you're
using AWS CLI version 2, no changes are required.
For more information, see Using the AWS CLI version 1 with Earlier Versions of Python (p. 33)
in this guide, and the deprecation announcement in this blog post.
$ virtualenv ~/cli-ve
Alternatively, you can use the -p option to specify a version of Python other than the default.
32
AWS Command Line Interface User Guide
Using the AWS CLI version 1 with Earlier Versions of Python
Linux or macOS
$ source ~/cli-ve/bin/activate
Windows
$ %USERPROFILE%\cli-ve\Scripts\activate
(cli-ve)~$
$ aws --version
aws-cli/1.17.4 Python/3.7.4 Linux/4.14.133-113.105.amzn2.x86_64 botocore/1.13
You can use the deactivate command to exit the virtual environment. Whenever you start a new
session, you must reactivate the environment.
• Windows MSI installer version of the AWS CLI version 1. The Windows MSI installer of
the AWS CLI version 1 installation includes and uses its own embedded copy of Python,
independent of any other Python version that you might have installed. If you're using an MSI
installer-based AWS CLI, no changes are required.
• AWS CLI version 2. The installers for AWS CLI version 2 all include and use an embedded copy
of Python, independent of any other Python version that you might have installed. If you're
using AWS CLI version 2, no changes are required.
33
AWS Command Line Interface User Guide
Using the AWS CLI version 1 with Earlier Versions of Python
For more information, see the deprecation announcement in this blog post.
To use an earlier, unsupported version of Python, such as Python 2.6 or Python 3.3, with the AWS CLI
version 1, you must use a copy of AWS CLI version 1 that was released before January 10th, 2020, and
prevent it from being updated to a later version.
Note
Using an earlier version of the AWS CLI version 1 prevents you from accessing new services or
features that were added to the AWS CLI after the date that your earlier version was initially
released. We recommend that whenever possible, you upgrade your Python version to a
supported version, and use a later version of the AWS CLI version 1.
Pip
You can force pip to download an AWS CLI version 1 version that is compatible with Python 2.6 or
Python 3.3 by using a command that specifies awscli<1.17, similar to the following example.
If you install the AWS CLI version 1 using a pip Requirements file, include a line similar to the following.
awscli<1.17
Download and save a copy of the bundled installer that includes a version of the AWS CLI version 1 that
is compatible with the version of Python that you want to use. You can use the following URL format
to download the file, replacing {VERSION} with the version number that you want to use, as shown.
Version numbers less than 1.17 support the earlier Python releases.
https://s3.amazonaws.com/aws-cli/awscli-bundle-{VERSION}.zip
For example, the following command downloads the AWS CLI version 1.16.312.
From here, you can continue to follow the installation instructions in Install the AWS CLI version 1 Using
the Bundled Installer (Linux or macOS) (p. 17), starting with step 2.
34
AWS Command Line Interface User Guide
Quickly Configuring the AWS CLI
Sections
• Quickly Configuring the AWS CLI (p. 35)
• Creating Multiple Profiles (p. 37)
• Configuration Settings and Precedence (p. 37)
• Configuration and Credential File Settings (p. 38)
• Named Profiles (p. 48)
• Configuring the AWS CLI to use AWS Single Sign-On (p. 50)
• Environment Variables To Configure the AWS CLI (p. 55)
• Command Line Options (p. 58)
• Sourcing Credentials with an External Process (p. 60)
• Getting Credentials from EC2 Instance Metadata (p. 61)
• Using an HTTP Proxy (p. 62)
• Using an IAM Role in the AWS CLI (p. 63)
• Command Completion (p. 68)
$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json
When you enter this command, the AWS CLI prompts you for four pieces of information (access key,
secret access key, AWS Region, and output format). These are described in the following sections. The
AWS CLI stores this information in a profile (a collection of settings) named default. The information
in the default profile is used any time you run an AWS CLI command that doesn't explicitly specify a
profile to use.
35
AWS Command Line Interface User Guide
Region
Access keys consist of an access key ID and secret access key, which are used to sign programmatic
requests that you make to AWS. If you don't have access keys, you can create them from the AWS
Management Console. As a best practice, do not use the AWS account root user access keys for any task
where it's not required. Instead, create a new administrator IAM user with access keys for yourself.
The only time that you can view or download the secret access key is when you create the keys. You
cannot recover them later. However, you can create new access keys at any time. You must also have
permissions to perform the required IAM actions. For more information, see Permissions Required to
Access IAM Resources in the IAM User Guide.
1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Users.
3. Choose the name of the user whose access keys you want to create, and then choose the Security
credentials tab.
4. In the Access keys section, choose Create access key.
5. To view the new access key pair, choose Show. You will not have access to the secret access key again
after this dialog box closes. Your credentials will look something like this:
Keep the keys confidential in order to protect your AWS account and never email them. Do not share
them outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No
one who legitimately represents Amazon will ever ask you for your secret key.
7. After you download the .csv file, choose Close. When you create an access key, the key pair is active
by default, and you can use the pair right away.
Related topics
Region
The Default region name identifies the AWS Region whose servers you want to send your requests
to by default. This is typically the Region closest to you, but it can be any Region. For example, you can
type us-west-2 to use US West (Oregon). This is the Region that all later requests are sent to, unless
you specify otherwise in an individual command.
Note
You must specify an AWS Region when using the AWS CLI, either explicitly or by setting a
default Region. For a list of the available Regions, see Regions and Endpoints. The Region
designators used by the AWS CLI are the same names that you see in AWS Management Console
URLs and service endpoints.
Output Format
The Default output format specifies how the results are formatted. The value can be any of the
values in the following list. If you don't specify an output format, json is used as the default.
36
AWS Command Line Interface User Guide
Creating Multiple Profiles
Then, when you run a command, you can omit the --profile option and use the credentials and
settings stored in the default profile.
$ aws s3 ls
Or you can specify a --profile profilename and use the credentials and settings stored under that
name.
To update any of your settings, simply run aws configure again (with or without the --profile
parameter, depending on which profile you want to update) and enter new values as appropriate. The
next sections contain more information about the files that aws configure creates, additional settings,
and named profiles.
1. Command line options (p. 58) – You can specify --region, --output, and --profile as
parameters on the command line.
2. Environment variables (p. 55) – You can store values in the environment variables:
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. If they are present,
they are used.
3. CLI credentials file (p. 38) – This is one of the files that is updated when you run the command
aws configure. The file is located at ~/.aws/credentials on Linux or macOS, or at C:\Users
37
AWS Command Line Interface User Guide
Configuration and Credential File Settings
\USERNAME\.aws\credentials on Windows. This file can contain the credential details for the
default profile and any named profiles.
4. CLI configuration file (p. 38) – This is another file that is updated when you run the command
aws configure. The file is located at ~/.aws/config on Linux or macOS, or at C:\Users
\USERNAME\.aws\config on Windows. This file contains the configuration settings for the default
profile and any named profiles.
5. Container credentials – You can associate an IAM role with each of your Amazon Elastic Container
Service (Amazon ECS) task definitions. Temporary credentials for that role are then available to that
task's containers. For more information, see IAM Roles for Tasks in the Amazon Elastic Container
Service Developer Guide.
6. Instance profile credentials – You can associate an IAM role with each of your Amazon Elastic
Compute Cloud (Amazon EC2) instances. Temporary credentials for that role are then available to
code running in the instance. The credentials are delivered through the Amazon EC2 metadata service.
For more information, see IAM Roles for Amazon EC2 in the Amazon EC2 User Guide for Linux Instances
and Using Instance Profiles in the IAM User Guide.
• The IAM user, see the section called “Creating IAM Users and Groups” (p. 126) for more information.
• The access key attached to the IAM user, see the section called “Create an Access Key for an IAM
User” (p. 128) for more information.
The files are divided into sections that can be referenced by name. These are called "profiles". Unless
you specify otherwise, the CLI uses the settings found in the profile named default. To use alternate
settings, you can create and reference additional profiles. You can also override an individual setting by
either setting one of the supported environment variables, or by using a command line parameter.
For example, the following commands list the contents of the .aws folder.
Linux or macOS
$ ls ~/.aws
Windows
38
AWS Command Line Interface User Guide
Supported config File Settings
The AWS CLI uses two files to store the sensitive credential information (in ~/.aws/credentials)
separated from the less sensitive configuration options (in ~/.aws/config).
You can specify a non-default location for the config file by setting the AWS_CONFIG_FILE
environment variable to another local path. See Environment Variables To Configure the AWS
CLI (p. 55) for details.
Storing Credentials in the Config File
The AWS CLI can also read credentials from the config file. You can keep all of your profile
settings in a single file. If there are ever credentials in both locations for a profile (say you used
aws configure to update the profile's keys), the keys in the credentials file take precedence.
These files are also used by the various language software development kits (SDKs). If you use
one of the SDKs in addition to the AWS CLI, you might receive additional warnings if credentials
aren't stored in their own file.
The files generated by the CLI for the profile configured in the previous section look like this.
~/.aws/credentials
[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
~/.aws/config
[default]
region=us-west-2
output=json
Note
The preceding examples show the files with a single, default profile. For examples of the files
with multiple named profiles, see Named Profiles (p. 48).
When you use a shared profile that specifies an IAM role, the AWS CLI calls the AWS STS AssumeRole
operation to retrieve temporary credentials. These credentials are then stored (in ~/.aws/cli/cache).
Subsequent AWS CLI commands use the cached temporary credentials until they expire, and at that
point the AWS CLI automatically refreshes the credentials.
The following settings are supported in the config file. The values listed in the specified (or default)
profile are used unless they are overridden by the presence of an environment variable with the same
name, or a command line option with the same name.
You can configure these settings by editing the config file directly with a text editor, or by using the aws
configure set command. Specify the profile that you want to modify with the --profile setting.
For example, the following command sets the region setting in the profile named integ.
You can also retrieve the value for any setting by using the get subcommand.
39
AWS Command Line Interface User Guide
Supported config File Settings
If the output is empty, the setting is not explicitly set and uses the default value.
Global Settings
api_versions
Some AWS services maintain multiple API versions to support backward compatibility. By default,
CLI commands use the latest available API version. You can specify an API version to use for a profile
by including the api_versions setting in the config file.
This is a "nested" setting that is followed by one or more indented lines that each identify one AWS
service and the API version to use. See the documentation for each service to understand which API
versions are available.
The following example shows how to specify an API version for two AWS services. These API versions
are used only for commands that run under the profile that contains these settings.
api_versions =
ec2 = 2015-03-01
cloudfront = 2015-09-017
This setting does not have an environment variable or command line parameter equivalent.
Specifies the AWS access key used as part of the credentials to authenticate the command
request. Although this can be stored in the config file, we recommend that you store this in the
credentials file.
Can be overridden by the AWS_ACCESS_KEY_ID environment variable. You can't specify the access
key ID as a command line option.
aws_access_key_id = 123456789012
Specifies the AWS secret key used as part of the credentials to authenticate the command
request. Although this can be stored in the config file, we recommend that you store this in the
credentials file.
Can be overridden by the AWS_SECRET_ACCESS_KEY environment variable. You can't specify the
secret access key as a command line option.
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token
Specifies an AWS session token. A session token is required only if you manually specify temporary
security credentials. Although this can be stored in the config file, we recommend that you store
this in the credentials file.
Can be overridden by the AWS_SESSION_TOKEN environment variable. You can't specify the session
token as a command line option.
40
AWS Command Line Interface User Guide
Supported config File Settings
aws_session_token = AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT
+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/
IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
ca_bundle
Specifies a CA certificate bundle (a file with the .pem extension) that is used to verify SSL
certificates.
ca_bundle = dev/apps/ca-certs/cabundle-2019mar05.pem
cli_binary_format
This feature is available only with AWS CLI version 2.
The following feature is available only if you use AWS CLI version 2. It isn't available if you
run AWS CLI version 1. For information on how to install version 2, see Installing the AWS
CLI version 2 (p. 4).
Specifies how the AWS CLI version 2 interprets binary input parameters. It can be one of the
following values:
• base64 – This is the default value. An input parameter that is typed as a binary large object (BLOB)
accepts a base64-encoded string. To pass true binary content, put the content in a file and provide
the file's path and name with the fileb:// prefix as the parameter's value. To pass base64-
encoded text contained in a file, provide the file's path and name with the file:// prefix as the
parameter's value.
• raw-in-base64-out – Provides backward compatibility with the AWS CLI version 1 behavior where
binary values must be passed literally.
This entry does not have an equivalent environment variable. You can specify the value on a single
command by using the --cli-binary-format raw-in-base64-out parameter.
cli_binary_format = raw-in-base64-out
If you reference a binary value in a file using the fileb:// prefix notation, the AWS CLI always
expects the file to contain raw binary content and does not attempt to convert the value.
If you reference a binary value in a file using the file:// prefix notation, the AWS CLI handles
the file according to the current cli_binary_format setting. If that setting's value is base64
(the default when not explicitly set), the CLI expects the file to contain base64-encoded text. If that
setting's value is raw-in-base64-out, the CLI expects the file to contain raw binary content.
cli_follow_urlparam
This feature is available only with AWS CLI version 1.
The following feature is available only if you use AWS CLI version 1. It isn't available if you
run AWS CLI version 2.
Specifies whether the CLI attempts to follow URL links in command line parameters that begin with
http:// or https://. When enabled, the retrieved content is used as the parameter value instead
of the URL.
• true – This is the default value. If specified, any string parameters that begin with http://
or https:// are fetched and any downloaded content is used as the parameter value for the
command.
• false – If specified, the CLI does not treat parameter string values that begin with http:// or
https:// differently from other strings.
41
AWS Command Line Interface User Guide
Supported config File Settings
This entry does not have an equivalent environment variable or command line option.
cli_follow_urlparam = false
cli_pager
This feature is available only with AWS CLI version 2.
The following feature is available only if you use AWS CLI version 2. It isn't available if you
run AWS CLI version 1. For information on how to install version 2, see Installing the AWS
CLI version 2 (p. 4).
Specifies the pager program used for output. By default, AWS CLI version 2 returns all output
through your operating system’s default pager program.
cli_pager=less
To disable all use of an external paging program, set the variable to an empty string as shown in the
following example.
cli_pager=
cli_timestamp_format
Specifies the format of timestamp values included in the output. You can specify either of the
following values:
• iso8601 – The default value for the AWS CLI version 2. If specified, the AWS CLI reformats all
timestamps according to ISO 8601.
• wire – The default value for the AWS CLI version 1. If specified, the AWS CLI displays all timestamp
values exactly as received in the HTTP query response.
This entry does not have an equivalent environment variable or command line option.
cli_timestamp_format = iso8601
Specifies an external command that the CLI runs to generate or retrieve authentication credentials
to use for this command. The command must return the credentials in a specific format. For
more information about how to use this setting, see Sourcing Credentials with an External
Process (p. 60).
This entry does not have an equivalent environment variable or command line option.
Used within Amazon EC2 instances or EC2 containers to specify where the AWS CLI can find
credentials to use to assume the role you specified with the role_arn parameter. You cannot
specify both source_profile and credential_source in the same profile.
42
AWS Command Line Interface User Guide
Supported config File Settings
• Ec2InstanceMetadata – Specifies that the AWS CLI is to use the IAM role attached to the EC2
instance profile to get source credentials.
• EcsContainer – Specifies that the AWS CLI is to use the IAM role attached to the ECS container as
source credentials.
credential_source = Ec2InstanceMetadata
duration_seconds
Specifies the maximum duration of the role session, in seconds. The value can range from 900
seconds (15 minutes) up to the maximum session duration setting for the role (which can be a
maximum of 43200). This is an optional parameter and by default, the value is set to 3600 seconds.
external_id (p. 66)
Specifies a unique identifier that is used by third parties to assume a role in their customers'
accounts. This maps to the ExternalId parameter in the AssumeRole operation. This parameter is
needed only if the trust policy for the role specifies a value for ExternalId. For more information,
see How to use an External Gateway When Granting Access to Your AWS Resources to a Third Party
in the IAM User Guide.
mfa_serial (p. 65)
The identification number of an MFA device to use when assuming a role. This is mandatory
only if the trust policy of the role being assumed includes a condition that requires MFA
authentication. The value can be either a serial number for a hardware device (such as
GAHT12345678) or an Amazon Resource Name (ARN) for a virtual MFA device (such as
arn:aws:iam::123456789012:mfa/user).
output (p. 36)
Specifies the default output format for commands requested using this profile. You can specify any
of the following values:
• json (p. 93) – The output is formatted as a JSON string.
• yaml (p. 94) – The output is formatted as a YAML string. (Available in the AWS CLI version 2
only.)
• text (p. 95) – The output is formatted as multiple lines of tab-separated string values. This can
be useful to pass the output to a text processor, like grep, sed, or awk.
• table (p. 97) – The output is formatted as a table using the characters +|- to form the cell
borders. It typically presents the information in a "human-friendly" format that is much easier to
read than the others, but not as programmatically useful.
output = table
parameter_validation
Specifies whether the AWS CLI client attempts to validate parameters before sending them to the
AWS service endpoint.
• true – This is the default value. If specified, the CLI performs local validation of command line
parameters.
• false – If specified, the CLI does not validate command line parameters before sending them to
the AWS service endpoint.
This entry does not have an equivalent environment variable or command line option.
43
AWS Command Line Interface User Guide
Supported config File Settings
parameter_validation = false
Specifies the AWS Region to send requests to for commands requested using this profile.
• You can specify any of the Region codes available for the chosen service as listed in AWS Regions
and Endpoints in the Amazon Web Services General Reference.
• aws_global enables you to specify the global endpoint for services that support a global
endpoint in addition to regional endpoints, such as AWS Security Token Service (AWS STS) and
Amazon Simple Storage Service (Amazon S3).
You can override this value by using the AWS_DEFAULT_REGION environment variable or the --
region command line option.
region = us-west-2
Specifies the Amazon Resource Name (ARN) of an IAM role that you want to use to run the AWS CLI
commands. You must also specify one of the following parameters to identify the credentials that
have permission to assume this role:
• source_profile
• credential_source
role_arn = arn:aws:iam::123456789012:role/role-name
Specifies the name to attach to the role session. This value is provided to the
RoleSessionName parameter when the AWS CLI calls the AssumeRole operation, and
becomes part of the assumed role user ARN: arn:aws:sts::123456789012:assumed-
role/role_name/role_session_name. This is an optional parameter. If you do not provide this
value, a session name is generated automatically. This name appears in AWS CloudTrail logs for
entries associated with this session.
role_session_name = maria_garcia_role
Specifies a named profile with long-term credentials that the AWS CLI can use to assume a role
that you specified with the role_arn parameter. You cannot specify both source_profile and
credential_source in the same profile.
source_profile = production-profile
Specifies the AWS account ID that contains the IAM role with the permission that you want to grant
to the associated AWS SSO user.
This setting does not have an environment variable or command line option.
sso_account_id = 123456789012
44
AWS Command Line Interface User Guide
Supported config File Settings
Specifies the AWS Region that contains the AWS SSO portal host. This is separate from, and can be a
different Region than the default CLI region parameter.
This setting does not have an environment variable or command line option.
aws_sso_region = us_west-2
Specifies the friendly name of the IAM role that defines the user's permissions when using this
profile.
This setting does not have an environment variable or command line option.
sso_role_name = ReadAccess
Specifies the URL that points to the organization's AWS SSO user portal. The AWS CLI uses this URL
to establish a session with the AWS SSO service to authenticate its users.
This setting does not have an environment variable or command line option.
sso_start_url = https://my-sso-portal.awsapps.com/start
sts_regional_endpoints
Specifies how the AWS CLI determines the AWS service endpoint that the AWS CLI client uses to talk
to the AWS Security Token Service (AWS STS).
• The default value for AWS CLI version 1 is legacy.
• The default value for AWS CLI version 2 is regional.
Specifies the path to a file that contains an OAuth 2.0 access token or OpenID Connect ID token that
is provided by an identity provider. The AWS CLI loads the contents of this file and passes it as the
WebIdentityToken argument to the AssumeRoleWithWebIdentity operation.
45
AWS Command Line Interface User Guide
Supported config File Settings
tcp_keepalive
Specifies whether the AWS CLI client uses TCP keep-alive packets.
This entry does not have an equivalent environment variable or command line option.
tcp_keepalive = false
All of these options can be configured by specifying the s3 nested setting in your config file. Each
setting is then indented on its own line.
Note
These settings are entirely optional. You should be able to successfully use the aws s3 transfer
commands without configuring any of these settings. These settings are provided to enable you
to tune for performance or to account for the specific environment where you are running these
aws s3 commands.
addressing_style
Specifies which addressing style to use. This controls whether the bucket name is in the hostname or
is part of the URL. Valid values are: path, virtual, and auto. The default value is auto.
There are two styles of constructing an S3 endpoint. The first is called virtual and includes the
bucket name as part of the hostname. For example: https://bucketname.s3.amazonaws.com.
Alternatively, with the path style, you treat the bucket name as if it is a path in the URI; for example,
https://s3.amazonaws.com/bucketname. The default value in the CLI is to use auto, which
attempts to use the virtual style where it can, but will fall back to path style when required.
For example, if your bucket name is not DNS compatible, the bucket name cannot be part of the
hostname and must be in the path. With auto, the CLI will detect this condition and automatically
switch to path style for you. If you set the addressing style to path, you must then ensure that the
AWS Region you configured in the AWS CLI matches the Region of your bucket.
payload_signing_enabled
Specifies whether to SHA256 sign sigv4 payloads. By default, this is disabled for streaming uploads
(UploadPart and PutObject) when using HTTPS. By default, this is set to false for streaming
uploads (UploadPart and PutObject), but only if a ContentMD5 is present (it is generated by
default) and the endpoint uses HTTPS.
If set to true, S3 requests receive additional content validation in the form of a SHA256 checksum
which is calculated for you and included in the request signature. If set to false, the checksum
isn't calculated. Disabling this can be useful to reduce the performance overhead created by the
checksum calculation.
use_dualstack_endpoint
Use the Amazon S3 dual IPv4 / IPv6 endpoint for all s3 and s3api commands. The default value is
false. This is mutually exclusive with the use_accelerate_endpoint setting.
46
AWS Command Line Interface User Guide
Supported config File Settings
If set to true, the AWS CLI directs all Amazon S3 requests to the dual IPv4 / IPv6 endpoint for the
configured Region.
use_accelerate_endpoint
Use the Amazon S3 Accelerate endpoint for all s3 and s3api commands. The default value is false.
This is mutually exclusive with the use_dualstack_endpoint setting.
If set to true, the AWS CLI directs all Amazon S3 requests to the S3 Accelerate endpoint at
s3-accelerate.amazonaws.com. To use this endpoint, you must enable your bucket to use S3
Accelerate. All requests are sent using the virtual style of bucket addressing: my-bucket.s3-
accelerate.amazonaws.com. Any ListBuckets, CreateBucket, and DeleteBucket
requests aren't sent to the S3 Accelerate endpoint as that endpoint doesn't support those
operations. This behavior can also be set if the --endpoint-url parameter is set to https://s3-
accelerate.amazonaws.com or http://s3-accelerate.amazonaws.com for any s3 or s3api
command.
The following settings apply only to commands in the s3 namespace command set.
max_bandwidth
Specifies the maximum bandwidth that can be consumed for uploading and downloading data to
and from Amazon S3. The default is no limit.
This limits the maximum bandwidth that the S3 commands can use to transfer data to and from
Amazon S3. This value applies to only uploads and downloads; it doesn't apply to copies or deletes.
The value is expressed as bytes per second. The value can be specified as:
• An integer. For example, 1048576 sets the maximum bandwidth usage to 1 megabyte per second.
• An integer followed by a rate suffix. You can specify rate suffixes using: KB/s, MB/s, or GB/s. For
example, 300KB/s, 10MB/s.
In general, we recommend that you first try to lower bandwidth consumption by lowering
max_concurrent_requests. If that doesn't adequately limit bandwidth consumption to the
desired rate, you can use the max_bandwidth setting to further limit bandwidth consumption. This
is because max_concurrent_requests controls how many threads are currently running. If you
instead first lower max_bandwidth but leave a high max_concurrent_requests setting, it can
result in threads having to wait unnecessarily. This can lead to excess resource consumption and
connection timeouts.
max_concurrent_requests
Specifies the maximum number of concurrent requests. The default value is 10.
The aws s3 transfer commands are multithreaded. At any given time, multiple Amazon S3 requests
can be running. For example, when you use the command aws s3 cp localdir s3://bucket/
--recursive to upload files to an S3 bucket, the AWS CLI can upload the files localdir/file1,
localdir/file2, and localdir/file3 in parallel. The setting max_concurrent_requests
specifies the maximum number of transfer operations that can run at the same time.
47
AWS Command Line Interface User Guide
Named Profiles
max_queue_size
Specifies the maximum number of tasks in the task queue. The default value is 1000.
The AWS CLI internally uses a model where it queues up Amazon S3 tasks that are then executed by
consumers whose numbers are limited by max_concurrent_requests. A task generally maps to
a single S3 operation. For example, a task could be a PutObjectTask, or a GetObjectTask, or an
UploadPartTask. The rate at which tasks are added to the queue can be much faster than the rate
at which consumers finish the tasks. To avoid unbounded growth, the task queue size is capped to a
specific size. This setting changes the value of that maximum number.
You generally don't need to change this setting. This setting also corresponds to the number of
tasks that the CLI is aware of that need to be run. This means that by default the CLI can only see
1000 tasks ahead. Increasing this value means that the CLI can more quickly know the total number
of tasks needed, assuming that the queuing rate is quicker than the rate of task completion. The
tradeoff is that a larger max_queue_size requires more memory.
multipart_chunksize
Specifies the chunk size that the AWS CLI uses for multipart transfers of individual files. The default
value is 8 MB, with a minimum of 5 MB.
When a file transfer exceeds the multipart_threshold, the CLI divides the file into chunks of this
size. This value can be specified using the same syntax as multipart_threshold, either as the
number of bytes as an integer, or by using a size and a suffix.
multipart_threshold
Specifies the size threshold the AWS CLI uses for multipart transfers of individual files. The default
value is 8 MB.
When uploading, downloading, or copying a file, the S3 commands switch to multipart operations if
the file exceeds this size. You can specify this value in one of two ways:
• The file size in bytes. For example, 1048576.
• The file size with a size suffix. You can use KB, MB, GB, or TB. For example: 10MB, 1GB.
Note
S3 can impose constraints on valid values that can be used for multipart operations. For
more information, see the S3 Multipart Upload documentation in the Amazon Simple
Storage Service Developer Guide.
These settings are all set under a top-level s3 key in the config file, as shown in the following example
for the development profile.
[profile development]
s3 =
max_concurrent_requests = 20
max_queue_size = 10000
multipart_threshold = 64MB
multipart_chunksize = 16MB
max_bandwidth = 50MB/s
use_accelerate_endpoint = true
addressing_style = path
Named Profiles
A named profile is a collection of settings and credentials that you can apply to a AWS CLI command.
When you specify a profile to run a command, the settings and credentials are used to run that
48
AWS Command Line Interface User Guide
Using Profiles with the AWS CLI
command. You can specify one profile that is the "default", and is used when no profile is explicitly
referenced. Other profiles have names that you can specify as a parameter on the command
line for individual commands. Alternatively, you can specify a profile in an environment variable
(AWS_PROFILE) (p. 55) which essentially overrides the default profile for commands that run in that
session.
The AWS CLI supports using any of multiple named profiles that are stored in the config and
credentials files. You can configure additional profiles by using aws configure with the --profile
option, or by adding entries to the config and credentials files.
The following example shows a credentials file with two profiles. The first [default] is used when
you run a CLI command with no profile. The second is used when you run a CLI command with the --
profile user1 parameter.
[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
[user1]
aws_access_key_id=AKIAI44QH8DHBEXAMPLE
aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Each profile can specify different credentials—perhaps from different IAM users—and can also specify
different AWS Regions and output formats.
[default]
region=us-west-2
output=json
[profile user1]
region=us-east-1
output=text
Important
The credentials file uses a different naming format than the CLI config file for named
profiles. Include the prefix word "profile" only when configuring a named profile in the
config file. Do not use the word profile when creating an entry in the credentials file.
To use a named profile for multiple commands, you can avoid specifying the profile in every command
by setting the AWS_PROFILE environment variable at the command line.
Linux or macOS
$ export AWS_PROFILE=user1
49
AWS Command Line Interface User Guide
Configuring the AWS CLI to use AWS Single Sign-On
Windows
Using set to set an environment variable changes the value used until the end of the current command
prompt session, or until you set the variable to a different value.
Using setx to set an environment variable changes the value in all command shells that you create after
running the command. It does not affect any command shell that is already running at the time you run
the command. Close and restart the command shell to see the effects of the change.
Setting the environment variable changes the default profile until the end of your shell session, or until
you set the variable to a different value. You can make environment variables persistent across future
sessions by putting them in your shell's startup script. For more information, see Environment Variables
To Configure the AWS CLI (p. 55).
Note
If you specify a profile with --profile on an individual command, that overrides the setting
specified in the environment variable for only that command.
If your organization uses AWS Single Sign-On (AWS SSO), your users can sign in to Active Directory, a
built-in AWS SSO directory, or another iDP connected to AWS SSO and get mapped to an AWS Identity
and Access Management (IAM) role that enables you to run AWS CLI commands. Regardless of which iDP
you use, AWS SSO abstracts those distinctions away, and they all work with the AWS CLI as described
below. For example, you can connect Microsoft Azure AD as described in the blog article The Next
Evolution in AWS Single Sign-On
For more information about AWS SSO, see the AWS Single Sign-On User Guide.
This topic describes how to configure the AWS CLI to authenticate the user with AWS SSO to get short-
term credentials to run AWS CLI commands. It includes the following sections:
• Configuring a Named Profile to Use AWS SSO (p. 50) - How to create and configure profiles that
use AWS SSO for authentication and mapping to an IAM role for AWS permissions.
• Using an AWS SSO Enabled Named Profile (p. 53) - how to login to AWS SSO from the CLI and use
the provided AWS temporary credentials to run AWS CLI commands.
50
AWS Command Line Interface User Guide
Configuring a Named Profile to Use AWS SSO
• Manually (p. 52), by editing the .aws/config file that stores the named profiles.
Automatic Configuration
You can add an AWS SSO enabled profile to your AWS CLI by running the following command, providing
your AWS SSO start URL and the AWS Region that hosts the AWS SSO directory.
The AWS CLI attempts to open your default browser and begin the login process for your AWS SSO
account.
SSO authorization page has automatically been opened in your default browser.
Follow the instructions in the browser to complete this authorization request.
If the AWS CLI cannot open the browser, the following message appears with instructions on how to
manually start the login process.
https://my-sso-portal.awsapps.com/verify
AWS SSO uses the code to associate the AWS SSO session with your current AWS CLI session. The AWS
SSO browser page prompts you to sign in with your AWS SSO account credentials. This enables the AWS
CLI (through the permissions associated with your AWS SSO account) to retrieve and display the AWS
accounts and roles that you are authorized to use with AWS SSO.
Next, the AWS CLI displays the AWS accounts available for you to use. If you are authorized to use only
one account, the AWS CLI selects that account for you automatically and skips the prompt. The AWS
accounts that are available for you to use are determined by your user configuration in AWS SSO.
Use the arrow keys to select the account you want to use with this profile. The ">" character on the left
points to the current choice. Press ENTER to make your selection.
Next, the AWS CLI confirms your account choice, and displays the IAM roles that are available to you in
the selected account. If the selected account lists only one role, the AWS CLI selects that role for you
automatically and skips the prompt. The roles that are available for you to use are determined by your
user configuration in AWS SSO.
As before, use the arrow keys to select the IAM role you want to use with this profile. The ">" character
on the left points to the current choice. Press <ENTER> to make your selection.
51
AWS Command Line Interface User Guide
Configuring a Named Profile to Use AWS SSO
Now you can finish the configuration of your profile, by specifying the default output format (p. 43),
the default AWS Region (p. 44) to send commands to, and providing a name for the profile (p. 37)
so you can reference this profile from among all those defined on the local computer. In the following
example, the user enters a default Region, default output format, and the name of the profile. You can
alternatively press <ENTER> to select any default values that are shown between the square brackets.
The suggested profile name is the account ID number followed by an underscore followed by the role
name.
Note
If you specify default as the profile name, this profile becomes the one used whenever you run
an AWS CLI command and do not specify a profile name.
To use this profile, specify the profile name using --profile, as shown:
The previous example entries would result in a named profile in ~/.aws/config that looks like the
following example.
[profile my-dev-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789011
sso_role_name = readOnly
region = us-west-2
output = json
At this point, you have a profile that you can use to request temporary credentials. You must use the
aws sso login command to actually request and retrieve the temporary credentials needed to run
commands. For instructions, see Using an AWS SSO Enabled Named Profile (p. 53).
Note
You can also run an AWS CLI command using the specified profile. If you are not currently
logged in to the AWS SSO portal, it starts the login process for you automatically, just as if you
had manually ran the command aws sso login command.
Manual Configuration
To manually add AWS SSO support to a named profile, you must add the following keys and values to
the profile definition in the file ~/.aws/config (Linux or macOS) or %USERPROFILE%/.aws/config
(Windows).
sso_start_url
The URL that points to the organization's AWS SSO user portal.
sso_start_url = https://my-sso-portal.awsapps.com/start
52
AWS Command Line Interface User Guide
Using an AWS SSO Enabled Named Profile
sso_region
The AWS Region that contains the AWS SSO portal host. This is separate from, and can be a different
region than the default CLI region parameter.
sso_region = us_west-2
sso_account_id
The AWS account ID that contains the IAM role that you want to use with this profile.
sso_account_id = 123456789011
sso_role_name
The name of the IAM role that defines the user's permissions when using this profile.
sso_role_name = ReadAccess
The presence of these keys identify this profile as one that uses AWS SSO to authenticate the user.
You can also include any other keys and values that are valid in the .aws/config file, such as region,
output, or s3. However, you can't include any credential related values, such as role_arn (p. 44) or
aws_secret_access_key (p. 40). If you do, the AWS CLI produces an error.
So a typical AWS SSO profile in .aws/config might look similar to the following example.
[profile my-dev-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789011
sso_role_name = readOnly
region = us-west-2
output = json
At this point, you have a profile that you can use to request temporary credentials. However, you can't
yet run an AWS CLI service command. You must first use the aws sso login command to actually
request and retrieve the temporary credentials needed to run commands. For instructions, see the next
section, Using an AWS SSO Enabled Named Profile (p. 53).
The AWS CLI opens your default browser and verifies your AWS SSO log in.
SSO authorization page has automatically been opened in your default browser.
53
AWS Command Line Interface User Guide
Using an AWS SSO Enabled Named Profile
If you are not currently signed in to your AWS SSO account, you must provide your AWS SSO user name
and password.
If the AWS CLI can't open your browser, it prompts you to open it yourself and enter the specified code.
https://my-sso-portal.awsapps.com/verify
The AWS CLI opens your default browser (or you manually open the browser of your choice) to the
specified page, and enter the provided code. The webpage then prompts you for your AWS SSO
credentials.
Your AWS SSO session credentials are cached and include an expiration timestamp. When the credentials
expire, the AWS CLI requests you to sign in to AWS SSO again.
If your AWS SSO credentials are valid, the AWS CLI uses them to securely retrieve AWS temporary
credentials for the IAM role specified in the profile.
As long as you signed in to AWS SSO and those cached credentials are not expired, the AWS CLI
automatically renews expired AWS temporary credentials when needed. However, if your AWS SSO
credentials expire, you must explicitly renew them by logging in to your AWS SSO account again.
You can create multiple AWS SSO enabled named profiles that each point to a different AWS account
or role. You can also use the aws sso login command on more than one profile at a time. If any of them
share the same AWS SSO user account, you must log in to that AWS SSO user account only once and
then they all share a single set of AWS SSO cached credentials.
█ The following command retrieves temporary credentials for the AWS account and role
54
AWS Command Line Interface User Guide
Environment Variables
█ specified in one named profile. If you are not yet signed in to AWS SSO or your
█ cached credentials have expired, it opens your browser and prompts you for your
█ AWS SSO user name and password. It then retrieves AWS temporary credentials for
█ the IAM role associated with this profile.
$ aws sso login --profile my-first-sso-profile
█ The next command retrieves a different set of temporary credentials for the AWS
█ account and role specified in the second named profile. It does not overwrite or
█ in any way compromise the first profile's credentials. If this profile specifies the
█ same AWS SSO portal, then it uses the SSO credentials that you retrieved in the
█ previoius command. The AWS CLI then retrieves AWS temporary credentials for the
█ IAM role associated with the second profile. You don't have to sign in to
█ AWS SSO again.
$ aws sso login --profile my-second-sso-profile
█ The following command lists the Amazon EC2 instances accessible to the role
█ identified in the first profile.
$ aws ec2 describe-instances --profile my-first-sso-profile
█ The following command lists the Amazon EC2 instances accessible to the role
█ identified in the second profile.
$ aws ec2 describe-instances --profile my-second-sso-profile
If you later want to run commands with one of your AWS SSO enabled profiles, you must again run the
aws sso login command (see the previous section) and specify the profile to use.
Precedence of options
• If you specify an option by using one of the environment variables described in this topic, it overrides
any value loaded from a profile in the configuration file.
• If you specify an option by using a parameter on the CLI command line, it overrides any value from
either the corresponding environment variable or a profile in the configuration file.
AWS_ACCESS_KEY_ID
55
AWS Command Line Interface User Guide
Environment Variables
If defined, this environment variable overrides the value for the profile setting
aws_access_key_id. You can't specify the access key ID by using a command line option.
AWS_CA_BUNDLE
Specifies the path to a certificate bundle to use for HTTPS certificate validation.
If defined, this environment variable overrides the value for the profile setting ca_bundle. You can
override this environment variable by using the --ca-bundle command line parameter.
AWS_CONFIG_FILE
Specifies the location of the file that the AWS CLI uses to store configuration profiles. The default
path is ~/.aws/config).
You can't specify this value in a named profile setting or by using a command line parameter.
AWS_DEFAULT_OUTPUT (p. 36)
If defined, this environment variable overrides the value for the profile setting output. You can
override this environment variable by using the --output command line parameter.
AWS_DEFAULT_REGION (p. 36)
If defined, this environment variable overrides the value for the profile setting region. You can
override this environment variable by using the --region command line parameter.
AWS_PAGER (p. 42)
Specifies the pager program used for output. By default, AWS CLI version 2 returns all output
through your operating system’s default pager program.
To disable all use of an external paging program, set the variable to an empty string.
If defined, this environment variable overrides the value for the profile setting cli_pager.
AWS_PROFILE (p. 48)
Specifies the name of the CLI profile with the credentials and options to use. This can be the name
of a profile stored in a credentials or config file, or the value default to use the default
profile.
If defined, this environment variable overrides the behavior of using the profile named [default]
in the configuration file. You can override this environment variable by using the --profile
command line parameter.
AWS_ROLE_SESSION_NAME (p. 67)
Specifies a name to associate with the role session. This value appears in CloudTrail logs for
commands performed by the user of this profile.
If defined, this environment variable overrides the value for the profile setting
role_session_name. You can't specify a role session name as a command line parameter.
AWS_SECRET_ACCESS_KEY
Specifies the secret key associated with the access key. This is essentially the "password" for the
access key.
If defined, this environment variable overrides the value for the profile setting
aws_secret_access_key. You can't specify the access key ID as a command line option.
56
AWS Command Line Interface User Guide
Environment Variables
AWS_SESSION_TOKEN
Specifies the session token value that is required if you are using temporary security credentials that
you retrieved directly from AWS STS operations. For more information, see the Output section of the
assume-role command in the AWS CLI Command Reference.
If defined, this environment variable overrides the value for the profile setting
aws_session_token. You can't specify the session token as a command line option.
AWS_SHARED_CREDENTIALS_FILE
Specifies the location of the file that the AWS CLI uses to store access keys. The default path is
~/.aws/credentials).
You can't specify this value in a named profile setting or by using a command line parameter.
Note
You can't specify AWS Single Sign-On (AWS SSO) authentication by using environment variables.
Instead, you must use a named profile in the shared configuration file .aws/config. For more
information, see Configuring the AWS CLI to use AWS Single Sign-On (p. 50).
The following example shows how you could configure environment variables for the default user. These
values would override any values found in a named profile, or instance metadata. Once set, you can
override these values by specifying a parameter on the CLI command line, or by changing or removing
the environment variable. For more information about precedence and how the AWS CLI determines
which credentials to use, see Configuration Settings and Precedence (p. 37).
Linux or macOS
$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ export AWS_DEFAULT_REGION=us-west-2
Setting the environment variable changes the value used until the end of your shell session, or until
you set the variable to a different value. You can make the variables persistent across future sessions by
setting them in your shell's startup script.
Using set to set an environment variable changes the value used until the end of the current command
prompt session, or until you set the variable to a different value. Using setx to set an environment
variable changes the value used in both the current command prompt session and all command prompt
sessions that you create after running the command. It does not affect other command shells that are
already running at the time you run the command.
PowerShell
PS C:\> $Env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
PS C:\> $Env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
PS C:\> $Env:AWS_DEFAULT_REGION="us-west-2"
If you set an environment variable at the PowerShell prompt as shown in the previous examples, it
saves the value for only the duration of the current session. To make the environment variable setting
57
AWS Command Line Interface User Guide
Command Line Options
persistent across all PowerShell and Command Prompt sessions, store it by using the System application
in Control Panel. Alternatively, you can set the variable for all future PowerShell sessions by adding
it to your PowerShell profile. See the PowerShell documentation for more information about storing
environment variables or persisting them across sessions.
--profile <string>
Specifies the named profile (p. 48) to use for this command. To set up additional named profiles,
you can use the aws configure command with the --profile option.
--region <string>
Specifies which AWS Region to send this command's AWS request to. For a list of all of the Regions
that you can specify, see AWS Regions and Endpoints in the Amazon Web Services General Reference.
--output <string>
Specifies the output format to use for this command. You can specify any of the following values:
• json (p. 93) – The output is formatted as a JSON string.
• yaml (p. 94) – The output is formatted as a YAML string. (Available in the AWS CLI version 2
only.)
• text (p. 95) – The output is formatted as multiple lines of tab-separated string values. This can
be useful to pass the output to a text processor, like grep, sed, or awk.
• table (p. 97) – The output is formatted as a table using the characters +|- to form the cell
borders. It typically presents the information in a "human-friendly" format that is much easier to
read than the others, but not as programmatically useful.
--endpoint-url <string>
Specifies the URL to send the request to. For most commands, the AWS CLI automatically
determines the URL based on the selected service and the specified AWS Region. However, some
commands require that you specify an account-specific URL. You can also configure some AWS
services to host an endpoint directly within your private VPC, which might then need to be specified.
For a list of the standard service endpoints available in each Region, see AWS Regions and Endpoints
in the Amazon Web Services General Reference.
--debug
A Boolean switch that enables debug logging. This includes additional diagnostic information about
the operation of the command that can be useful when troubleshooting why a command provides
unexpected results.
--no-paginate
Specifies a JMESPath query to use in filtering the response data. For more information, see How to
Filter the Output with the --query Option (p. 98).
58
AWS Command Line Interface User Guide
Command Line Options
--version
A Boolean switch that displays the current version of the AWS CLI program that is running.
--color <string>
Specifies support for color output. Valid values are on, off, and auto. The default value is auto.
--no-sign-request
A Boolean switch that disables signing the HTTP requests to the AWS service endpoint. This prevents
credentials from being loaded.
--ca-bundle <string>
Specifies the certificate authority (CA) certificate bundle to use when verifying SSL certificates.
--cli-read-timeout <integer>
Specifies the maximum socket read time in seconds. If the value is set to zero (0) the socket read
waits indefinitely (is blocking) and doesn't timeout.
--cli-connect-timeout <integer>
Specifies the maximum socket connect time in seconds. If the value is set to zero (0), the socket
connect waits indefinitely (is blocking) and doesn't timeout.
When you provide one or more of these options as command line parameters, they override the
default configuration, any corresponding profile setting, or environment variable setting for that single
command.
Each option that takes an argument requires a space or equals sign (=) separating the argument from
the option name. If the argument value is a string that contains a space, you must use quotation marks
around the argument.
Common uses for command line options include checking your resources in multiple AWS Regions, and
changing the output format for legibility or ease of use when scripting. For example, if you're not sure
which Region your instance is running in, you can run the describe-instances command against each
Region until you find it, as follows.
59
AWS Command Line Interface User Guide
Sourcing Credentials with an External Process
The argument types (for example, string, Boolean) for each command line option are described in detail
in ??? (p. 76).
If you have a method to generate or look up credentials that isn't directly supported by the AWS CLI, you
can configure the CLI to use it by configuring the credential_process setting in the config file.
For example, you might include an entry similar to the following in the config file.
[profile developer]
credential_process = /opt/bin/awscreds-custom --username helen
Syntax
To create this string in a way that is compatible with any operating system, follow these rules:
• If the path or file name contains a space, surround the complete path and file name with double-
quotation marks (" "). The path and file name can consist of only the characters: A-Z a-z 0-9 - _ . space
• If a parameter name or a parameter value contains a space, surround that element with double-
quotation marks (" "). Surround only the name or value, not the pair.
• Do not include any environment variables in the strings. For example, you can't include $HOME or
%USERPROFILE%.
• Do not specify the home folder as ~. You must specify the full path.
The AWS CLI runs the command as specified in the profile and then reads data from STDOUT. The
command you specify must generate JSON output on STDOUT that matches the following syntax.
{
"Version": 1,
"AccessKeyId": "an AWS access key",
"SecretAccessKey": "your AWS secret access key",
60
AWS Command Line Interface User Guide
Getting Credentials from EC2 Instance Metadata
Note
As of this writing, the Version key must be set to 1. This might increment over time as the
structure evolves.
The Expiration key is an ISO8601 formatted timestamp. If the Expiration key is not present in
the tool's output, the CLI assumes that the credentials are long-term credentials that do not refresh.
Otherwise the credentials are considered temporary credentials and are refreshed automatically by
rerunning the credential_process command before they expire.
Note
The AWS CLI does not cache external process credentials the way it does assume-role
credentials. If caching is required, you must implement it in the external process.
The external process can return a non-zero return code to indicate that an error occurred while retrieving
the credentials.
Launch the instance and check to see if the AWS CLI is already installed (it comes preinstalled on Amazon
Linux). If necessary, install the AWS CLI. You must still configure a default AWS Region to avoid having to
specify it in every command.
In a named profile, to specify that you want to use the credentials available in the hosting Amazon EC2
instance profile, use the following line in the configuration file.
credential_source = Ec2InstanceMetadata
The following example shows how to assume the marketingadminrole role by referencing it in an
Amazon EC2 instance profile.
[profile marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
credential_source = Ec2InstanceMetadata
To set the Region and default output format by running aws configure without specifying credentials,
press Enter twice to skip the first two prompts.
$ aws configure
AWS Access Key ID [None]: ENTER
AWS Secret Access Key [None]: ENTER
Default region name [None]: us-west-2
Default output format [None]: json
When an IAM role is attached to the instance, the AWS CLI automatically and securely retrieves the
credentials from the instance metadata. For more information, see Granting Applications That Run on
Amazon EC2 Instances Access to AWS Resources in the IAM User Guide.
61
AWS Command Line Interface User Guide
Using an HTTP Proxy
The following examples show how you can use either the explicit IP address of your proxy or a DNS name
that resolves to the IP address of your proxy. Either can be followed by a colon and the port number to
which queries should be sent.
Linux or macOS
$ export HTTP_PROXY=http://10.15.20.25:1234
$ export HTTP_PROXY=http://proxy.example.com:1234
$ export HTTPS_PROXY=http://10.15.20.25:5678
$ export HTTPS_PROXY=http://proxy.example.com:5678
Windows
Authenticating to a Proxy
The AWS CLI supports HTTP Basic authentication. Specify the user name and password in the proxy URL,
as follows.
Linux or macOS
$ export HTTP_PROXY=http://username:password@proxy.example.com:1234
$ export HTTPS_PROXY=http://username:password@proxy.example.com:5678
Windows
Note
The AWS CLI doesn't support NTLM proxies. If you use an NTLM or Kerberos protocol proxy, you
might be able to connect through an authentication proxy like Cntlm.
62
AWS Command Line Interface User Guide
Using an IAM Role in the AWS CLI
Linux or macOS
$ export NO_PROXY=169.254.169.254
Windows
You can configure the AWS Command Line Interface (AWS CLI) to use an IAM role by defining a profile
for the role in the ~/.aws/config file.
The following example shows a role profile named marketingadmin. If you run commands with --
profile marketingadmin (or specify it with the AWS_PROFILE environment variable (p. 55)),
the CLI uses the credentials defined in a separate profile user1 to assume the role with the Amazon
Resource Name (ARN) arn:aws:iam::123456789012:role/marketingadminrole. You can run any
operations that are allowed by the permissions assigned to that role.
[profile marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
source_profile = user1
You can then specify a source_profile that points to a separate named profile that contains IAM user
credentials with permission to use the role. In the previous example, the marketingadmin profile uses
the credentials in the user1 profile. When you specify that an AWS CLI command is to use the profile
marketingadmin, the CLI automatically looks up the credentials for the linked user1 profile and
uses them to request temporary credentials for the specified IAM role. The CLI uses the sts:AssumeRole
operation in the background to accomplish this. Those temporary credentials are then used to run the
requested CLI command. The specified role must have attached IAM permission policies that allow the
requested CLI command to run.
To run a CLI command from within an Amazon Elastic Compute Cloud (Amazon EC2) instance or an
Amazon Elastic Container Service (Amazon ECS) container, you can use an IAM role attached to the
instance profile or the container. If you specify no profile or set no environment variables, that role
is used directly. This enables you to avoid storing long-lived access keys on your instances. You can
also use those instance or container roles only to get credentials for another role. To do this, you
use credential_source (instead of source_profile) to specify how to find the credentials. The
credential_source attribute supports the following values:
The following example shows the same marketingadminrole role used by referencing an Amazon EC2
instance profile.
[profile marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
credential_source = Ec2InstanceMetadata
63
AWS Command Line Interface User Guide
Configuring and Using a Role
When you invoke a role, you have additional options that you can require, such as the use of multi-factor
authentication and an External ID (used by third-party companies to access their clients' resources). You
can also specify unique role session names that can be more easily audited in AWS CloudTrail logs.
Sections
• Configuring and Using a Role (p. 64)
• Using Multi-Factor Authentication (p. 65)
• Cross-Account Roles and External ID (p. 66)
• Specifying a Role Session Name for Easier Auditing (p. 67)
• Assume Role with Web Identity (p. 67)
• Clearing Cached Credentials (p. 68)
You can create a role in IAM with the permissions that you want users to assume by following the
procedure under Creating a Role to Delegate Permissions to an IAM User in the AWS Identity and Access
Management User Guide. If the role and the source profile's IAM user are in the same account, you can
enter your own account ID when configuring the role's trust relationship.
After creating the role, modify the trust relationship to allow the IAM user (or the users in the AWS
account) to assume it.
The following example shows a trust policy that you could attach to a role. This policy allows the role to
be assumed by any IAM user in the account 123456789012, if the administrator of that account explicitly
grants the sts:assumerole permission to the user.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "sts:AssumeRole"
}
]
}
The trust policy doesn't actually grant permissions. The administrator of the account must delegate the
permission to assume the role to individual users by attaching a policy with the appropriate permissions.
The following example shows a policy that you can attach to an IAM user that allows the user to assume
only the marketingadminrole role. For more information about granting a user access to assume a
role, see Granting a User Permission to Switch Roles in the IAM User Guide.
{
"Version": "2012-10-17",
"Statement": [
{
64
AWS Command Line Interface User Guide
Using MFA
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::123456789012:role/marketingadminrole"
}
]
}
The IAM user doesn't need to have additional permissions to run the CLI commands using the role
profile. Instead, the permissions to run the command come from those attached to the role. You attach
permission policies to the role to specify which actions can be performed against which AWS resources.
For more information about attaching permissions to a role (which works identically to an IAM user), see
Changing Permissions for an IAM User in the IAM User Guide.
Now that you have the role profile, role permissions, role trust relationship, and user permissions
correctly configured, you can use the role at the command line by invoking the --profile option.
For example, the following calls the Amazon S3 ls command using the permissions attached to the
marketingadmin role as defined by the example at the beginning of this topic.
To use the role for several calls, you can set the AWS_DEFAULT_PROFILE environment variable for the
current session from the command line. While that environment variable is defined, you don't have to
specify the --profile option on each command.
Linux or macOS
$ export AWS_PROFILE=marketingadmin
Windows
For more information about configuring IAM users and roles, see Users and Groups and Roles in the IAM
User Guide.
First, you can choose to modify the trust relationship on the IAM role to require MFA. This prevents
anyone from using the role without first authenticating by using MFA. For an example, see the
Condition line in the following example. This policy allows the IAM user named anika to assume the
role the policy is attached to, but only if they authenticate by using MFA.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::123456789012:user/anika" },
"Action": "sts:AssumeRole",
"Condition": { "Bool": { "aws:multifactorAuthPresent": true } }
}
]
65
AWS Command Line Interface User Guide
Cross-Account Roles and External ID
Next, add a line to the role profile that specifies the ARN of the user's MFA device. The following sample
config file entries show two role profiles that both use the access keys for the IAM user anika to
request temporary credentials for the role cli-role. The user anika has permissions to assume the
role, granted by the role's trust policy.
[profile role-without-mfa]
region = us-west-2
role_arn= arn:aws:iam::128716708097:role/cli-role
source_profile=cli-user
[profile role-with-mfa]
region = us-west-2
role_arn= arn:aws:iam::128716708097:role/cli-role
source_profile = cli-user
mfa_serial = arn:aws:iam::128716708097:mfa/cli-user
[profile anika]
region = us-west-2
output = json
The mfa_serial setting can take an ARN, as shown, or the serial number of a hardware MFA token.
The first profile, role-without-mfa, doesn't require MFA. However, because the previous example trust
policy attached to the role requires MFA, any attempt to run a command with this profile fails.
An error occurred (AccessDenied) when calling the AssumeRole operation: Access denied
The second profile entry, role-with-mfa, identifies an MFA device to use. When the user attempts to
run a CLI command with this profile, the CLI prompts the user to enter the one-time password (OTP)
that the MFA device provides. If the MFA authentication succeeds, the command performs the requested
operation. The OTP is not displayed on the screen.
If you use an external ID to provide additional control over who can use a role across accounts, you must
also add the external_id parameter to the role profile. You typically use this only when the other
account is controlled by someone outside your company or organization.
[profile crossaccountrole]
role_arn = arn:aws:iam::234567890123:role/SomeRole
66
AWS Command Line Interface User Guide
Specifying a Role Session Name for Easier Auditing
source_profile = default
mfa_serial = arn:aws:iam::123456789012:mfa/saanvi
external_id = 123456
You can simplify this by specifying unique role session names when users assume a role. You do this by
adding a role_session_name parameter to each named profile in the config file that specifies a role.
The role_session_name value is passed to the AssumeRole operation and becomes part of the ARN
for the role session. It is also included in the AWS CloudTrail logs for all logged operations.
[profile namedsessionrole]
role_arn = arn:aws:iam::234567890123:role/SomeRole
source_profile = default
role_session_name = Session_Maria_Garcia
arn:aws:iam::234567890123:assumed-role/SomeRole/Session_Maria_Garcia
Also, all AWS CloudTrail logs include the role session name in the information captured for each
operation.
To retrieve and use temporary credentials using web identity federation, you can specify the following
configuration values in a shared profile.
Specifies the path to a file which contains an OAuth 2.0 access token or OpenID Connect ID token
that is provided by the identity provider. The AWS CLI loads this file and passes its content as the
WebIdentityToken argument of the AssumeRoleWithWebIdentity operation.
role_session_name (p. 67)
67
AWS Command Line Interface User Guide
Clearing Cached Credentials
The following is an example of the minimal amount of configuration needed to configure an assume role
with web identity profile.
█ In ~/.aws/config
[profile web-identity]
role_arn=arn:aws:iam:123456789012:role/RoleNameToAssume
web_identity_token_file=/path/to/a/token
You can also provide this configuration by using environment variables (p. 55).
AWS_ROLE_ARN
Note
These environment variables currently apply only to the assume role with web identity provider.
They don't apply to the general assume role provider configuration.
If your role's temporary credentials are revoked, they are not renewed automatically, and attempts to use
them fail. However, you can delete the cache to force the AWS CLI to retrieve new credentials.
Linux or macOS
$ rm -r ~/.aws/cli/cache
Windows
Command Completion
On Unix-like systems, the AWS CLI includes a command-completion feature that enables you to use
the Tab key to complete a partially typed command. On most systems, this feature isn't automatically
installed, so you need to configure it manually.
To configure command completion, you must have two pieces of information: the name of the shell
you're using and the location of the aws_completer script.
Amazon Linux
Command completion is automatically configured and enabled by default on Amazon EC2
instances that run Amazon Linux.
68
AWS Command Line Interface User Guide
Identify Your Shell
Sections
• Identify Your Shell (p. 69)
• Locate the AWS Completer (p. 69)
• Add the Completer's Folder to Your Path (p. 70)
• Enable Command Completion (p. 70)
• Test Command Completion (p. 71)
echo $SHELL – Show the shell's program file name. This usually matches the name of the in-use shell,
unless you launched a different shell after logging in.
$ echo $SHELL
/bin/bash
ps – Show the processes running for the current user. One of them is the shell.
$ ps
PID TTY TIME CMD
2148 pts/1 00:00:00 bash
8756 pts/1 00:00:00 ps
Package Manager – Programs such as pip, yum, brew, and apt-get typically install the AWS completer
(or a symlink to it) to a standard path location. In this case, the which command can locate the
completer for you.
If you used pip without the --user command, you might see the following path.
$ which aws_completer
/usr/local/aws/bin/aws_completer
If you used the --user parameter on the pip install command, you can typically find the completer in
the local/bin folder under your $HOME folder.
$ which aws_completer
/home/username/.local/bin/aws_completer
Bundled Installer – If you used the bundled installer per the instructions in the previous section, the
AWS completer is located in the bin subfolder of the installation directory.
$ ls /usr/local/aws/bin
activate
activate.csh
activate.fish
activate_this.py
aws
69
AWS Command Line Interface User Guide
Add the Completer's Folder to Your Path
aws.cmd
aws_completer
...
If all else fails, you can use find to search your entire file system for the AWS completer.
1. Find your shell's profile script in your user folder. If you're not sure which shell you have, run echo
$SHELL.
$ ls -a ~
. .. .bash_logout .bash_profile .bashrc Desktop Documents Downloads
export PATH=/usr/local/aws/bin:$PATH
3. Reload the profile into the current session to put those changes into effect. Replace .bash_profile
with the name of the shell script you discovered in the first section.
$ source ~/.bash_profile
Add the command to ~/.bashrc to run it each time you open a new shell. Your ~/.bash_profile
should source ~/.bashrc to ensure that the command is also run in login shells.
• tcsh – Complete for tcsh takes a word type and pattern to define the completion behavior.
Add the command to ~/.tschrc to run it each time you open a new shell.
• zsh – source bin/aws_zsh_completer.sh.
70
AWS Command Line Interface User Guide
Test Command Completion
% source /usr/local/aws/bin/aws_zsh_completer.sh
The AWS CLI uses bash compatibility autocompletion (bashcompinit) for zsh support. For more
details, see the top of aws_zsh_completer.sh.
Add the command to ~/.zshrc to run it each time you open a new shell.
$ aws sTAB
s3 ses sqs sts swf
s3api sns storagegateway support
71
AWS Command Line Interface User Guide
Getting Help
Topics
• Getting Help with the AWS CLI (p. 72)
• Command Structure in the AWS CLI (p. 76)
• Specifying Parameter Values for the AWS CLI (p. 76)
• Controlling Command Output from the AWS CLI (p. 92)
• Using AWS CLI Pagination Options (p. 104)
• Understanding Return Codes from the AWS CLI (p. 106)
For example, the following command displays help for the general AWS CLI options and the available
top-level commands.
$ aws help
The following command displays the available Amazon Elastic Compute Cloud (Amazon EC2) specific
commands.
The following example displays detailed help for the Amazon EC2 DescribeInstances operation. The
help includes descriptions of its input parameters, available filters, and what is included as output. It also
includes examples showing how to type common variations of the command.
Name
NAME
describe-instances -
Description
72
AWS Command Line Interface User Guide
Getting Help
DESCRIPTION
Describes one or more of your instances.
If you specify one or more instance IDs, Amazon EC2 returns information
for those instances. If you do not specify instance IDs, Amazon EC2
returns information for all relevant instances. If you specify an
instance ID that is not valid, an error is returned. If you specify an
instance that you do not own, it is not included in the returned
results.
...
Synopsis
The basic syntax for using the command and its options. If an option is shown in square brackets, it's
optional, has a default value, or has an alternative option that you can use.
SYNOPSIS
describe-instances
[--dry-run | --no-dry-run]
[--instance-ids <value>]
[--filters <value>]
[--cli-input-json <value>]
[--starting-token <value>]
[--page-size <value>]
[--max-items <value>]
[--generate-cli-skeleton]
For example, describe-instances has a default behavior that describes all instances in the
current account and AWS Region. You can optionally specify a list of instance-ids to describe one
or more instances; dry-run is an optional Boolean flag that doesn't take a value. To use a Boolean
flag, specify either shown value, in this case --dry-run or --no-dry-run. Likewise, --generate-
cli-skeleton doesn't take a value. If there are conditions on an option's use, they are described in
the OPTIONS section, or shown in the examples.
Options
OPTIONS
--dry-run | --no-dry-run (boolean)
Checks whether you have the required permissions for the action,
without actually making the request, and provides an error response.
If you have the required permissions, the error response is DryRun-
Operation . Otherwise, it is UnauthorizedOperation .
--instance-ids (list)
One or more instance IDs.
Examples
Examples showing the usage of the command and its options. If no example is available for a
command or use case that you need, request one using the feedback link on this page, or in the AWS
CLI command reference on the help page for the command.
EXAMPLES
To describe an Amazon EC2 instance
73
AWS Command Line Interface User Guide
Getting Help
Command:
Command:
Command:
Output
Descriptions of each of the fields and data types included in the response from AWS.
For describe-instances, the output is a list of reservation objects, each of which contains several
fields and objects that contain information about the instances associated with it. This information
comes from the API documentation for the reservation data type used by Amazon EC2.
OUTPUT
Reservations -> (list)
One or more reservations.
(structure)
Describes a reservation.
(structure)
Describes a security group.
(structure)
Describes an instance.
74
AWS Command Line Interface User Guide
AWS CLI Documentation
When the AWS CLI renders the output into JSON, it becomes an array of reservation objects, similar
to the following example.
{
"Reservations": [
{
"OwnerId": "012345678901",
"ReservationId": "r-4c58f8a0",
"Groups": [],
"RequesterId": "012345678901",
"Instances": [
{
"Monitoring": {
"State": "disabled"
},
"PublicDnsName": "ec2-52-74-16-12.us-west-2.compute.amazonaws.com",
"State": {
"Code": 16,
"Name": "running"
},
...
Each reservation object contains fields describing the reservation and an array of instance objects,
each with its own fields (for example, PublicDnsName) and objects (for example, State) that
describe it.
Windows users
You can pipe (|) the output of the help command to the more command to view the help file
one page at a time. Press the space bar or PgDn to view more of the document, and q to
quit.
API Documentation
All commands in the AWS CLI correspond to requests made to an AWS service's public API. Each service
with a public API has an API reference that can be found on the service's home page on the AWS
Documentation website. The content for an API reference varies based on how the API is constructed and
which protocol is used. Typically, an API reference contains detailed information about the operations
75
AWS Command Line Interface User Guide
Command Structure
supported by the API, the data sent to and from the service, and any error conditions that the service can
report.
• Actions – Detailed information on each operation and its parameters (including constraints on length
or content, and default values). It lists the errors that can occur for this operation. Each operation
corresponds to a subcommand in the AWS CLI.
• Data Types – Detailed information about structures that a command might require as a parameter, or
return in response to a request.
• Common Parameters – Detailed information about the parameters that are shared by all of action for
the service.
• Common Errors – Detailed information about errors that can be returned by any of the service's
operations.
The name and availability of each section can vary, depending on the service.
Service-specific CLIs
Some services have a separate CLI that dates from before a single AWS CLI was created to work
with all services. These service-specific CLIs have separate documentation that is linked from
the service's documentation page. Documentation for service-specific CLIs does not apply to the
AWS CLI.
Parameters can take various types of input values, such as numbers, strings, lists, maps, and JSON
structures. What is supported is dependent upon the command and subcommand you specify.
You can surround strings that do not contain any space characters with quotation marks or not. However,
you must use quotation marks around strings that include one or more space characters. For more
76
AWS Command Line Interface User Guide
Common Parameter Types
information about using quotation marks around complex parameters, see Using Quotation Marks with
Strings in the AWS CLI (p. 79).
The help for each subcommand describes its function, options, output, and examples. The options
section includes the name and description of each option with the option's parameter type in
parentheses.
String
String parameters can contain alphanumeric characters, symbols, and white space from the ASCII
character set. Strings that contain white space must be surrounded by quotation marks. We recommend
that you don't use symbols or white space other than the standard space character because it can cause
unexpected results.
Some string parameters can accept binary data from a file. See Binary Files (p. 82) for an example.
Timestamp
Timestamps are formatted according to the ISO 8601 standard. These are sometimes referred to as
"DateTime" or "Date" parameters.
(Available in the AWS CLI version 2 only.) By default, the AWS CLI version 2 translates all response
DateTime values to ISO 8601 format.
List
One or more strings separated by spaces. If any of the string items contain a space, you must put
quotation marks around that item.
Boolean – Binary flag that turns an option on or off. For example, ec2 describe-spot-price-
history has a Boolean --dry-run parameter that, when specified, validates the query with the service
without actually running the query.
77
AWS Command Line Interface User Guide
Common Parameter Types
The output indicates whether the command was well formed. This command also includes a --no-dry-
run version of the parameter that you can use to explicitly indicate that the command should be run
normally. Including it isn't necessary because this is the default behavior.
Integer
An unsigned, whole number.
(Available in the AWS CLI version 2 only.) In the AWS CLI version 2, you can pass a binary value as a
base64-encoded string directly on the command line. Also, by default in the AWS CLI version 2, files
referenced with the file:// prefix are treated as base64-encoded text.
You can revert the AWS CLI version 2 to be compatible with AWS CLI version 1 by setting the cli-
binary-format (p. 41) setting:
• If the setting's value is raw-in-base64-out, files referenced using the file:// prefix are treated as
raw unencoded binary.
• If the setting's value is base64 (the default value), files referenced using the file:// prefix are
treated as base64-encoded text.
Files referenced using the fileb:// prefix are always treated as raw unencoded binary, regardless of
the cli_binary_format setting.
Map
A set of key-value pairs specified in JSON or by using the CLI's shorthand syntax (p. 91). The following
JSON example reads an item from an Amazon DynamoDB table named my-table with a map parameter,
--key. The parameter specifies the primary key named id with a number value of 1 in a nested JSON
structure.
{
"Item": {
"name": {
"S": "John"
},
"id": {
"N": "1"
}
78
AWS Command Line Interface User Guide
Quoting Strings
}
}
Use single quotation marks (' ') in Linux, macOS, Unix, or PowerShell. Use double quotation marks (" ") in
the Windows command prompt, as shown in the following examples.
Optionally, you can optionally separate the parameter name from the value with an equals sign (=)
instead of a space. This is typically necessary only if the value of the parameter starts with a hyphen.
One of the common parameter value types is a JSON string. This is complex not only because it includes
spaces, but also requires the double quotation marks (" ")around each element name and value in the
JSON structure. The way you enter JSON-formatted parameters on the command line differs depending
on your operating system.
Linux or macOS
Use single quotation marks (' ') to enclose the JSON data structure, as in the following example. You
don't have to do anything special with the embedded double quotation marks embedded in the
JSON string.
PowerShell
PowerShell requires single quotation marks (' ') to enclose the JSON data structure. Also, because
double quotation marks have a special meaning to PowerShell, you must use a backslash (\) to
escape each double quotation mark (") within the JSON structure, as in the following example.
The Windows command prompt requires double quotation marks (" ") to enclose the JSON data
structure. Also, to prevent the command processor from misinterpreting the double quotation marks
79
AWS Command Line Interface User Guide
Prompting for Parameters
embedded in the JSON, you must also escape (precede with a backslash [ \ ] character) each double
quotation mark (") within the JSON data structure itself, as in the following example.
You can have the AWS CLI version 2 prompt you for parameters when you run a command. On your
command line, include --cli-auto-prompt.
In the preceding example, the first parameter is mandatory, and requires you to provide a value to
continue. The AWS CLI repeats this for each mandatory parameter required by the command that you are
running, one after the other.
After you provide values for all of the mandatory parameters, the AWS CLI displays all of the optional
parameters and enables you to move between them using the up and down arrow keys. The currently
selected row is denoted with a caret (>) in the left margin and have light text on a dark background. The
non-selected rows have dark text on a light background.
Use the up and down arrow keys to select an optional parameter to provide a value for, then press
ENTER. Enter the value for the optional parameter, then press ENTER again. That parameter and value
move to the top of the list, above the remaining selectable rows. Repeat this for each optional parameter
that you want to use. You can skip any that you don't need.
When you're done, select the last line that begins with [DONE] and press ENTER to confirm your choices.
Finally, you're given the option to run the command or to print the final version with all of the provided
parameter values. As before, the caret (>) and highlighted text marks the current selection. You can use
the arrow keys to move the current selection up or down, then press ENTER to select that option.
80
AWS Command Line Interface User Guide
Parameters from Files
If you choose to print the command, you get output similar to the following example, where only the --
user-name and --path parameters were selected and provided with values.
--path: /
aws iam create-user --user-name maria --path /
If you choose instead to run the command, it does not display the command but immediately runs it.
Sometimes it's convenient to load a parameter value from a file instead of trying to type it all as a
command line parameter value, such as when the parameter is a complex JSON string. To specify a file
that contains the value, specify a file URL in the following format.
file://complete/path/to/file
The first two slash '/' characters are part of the specification. If the required path begins with a '/', the
result is three slash characters: file:///folder/file.
The URL provides the path to the file that contains the actual parameter content.
Note
This behavior is disabled automatically for parameters that already expect a URL, such as
parameter that identifies a AWS CloudFormation template URL.
You can also disable this behavior by adding the following line to your CLI configuration file.
cli_follow_urlparam = false
The file paths in the following examples are interpreted to be relative to the current working directory.
Linux or macOS
81
AWS Command Line Interface User Guide
Parameters from Files
Windows
The file:// prefix option supports Unix-style expansions, including "~/", "./", and "../". On Windows,
the "~/" expression expands to your user directory, stored in the %USERPROFILE% environment variable.
For example, on Windows 10 you would typically have a user directory under C:\Users\User Name\.
You must still escape JSON documents that are embedded as the value of another JSON document.
attributes.json
{
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-
west-2:0123456789012:deadletter\", \"maxReceiveCount\":\"5\"}"
}
Binary Files
For commands that take binary data as a parameter, specify that the data is binary content by using the
fileb:// prefix. Commands that accept binary data include:
The following example generates a binary 256-bit AES key using a Linux command line tool, and then
provides it to Amazon S3 to encrypt an uploaded file server-side.
Remote Files
The AWS CLI also supports loading parameters from a file hosted on the internet with an http:// or
https:// URL. The following example references a file stored in an Amazon S3 bucket. This allows you
to access parameter files from any computer, but it does require that the container is publicly accessible.
82
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
The preceding example assumes that the file filename.json contains the following JSON data.
[
{
"DeviceName": "/dev/sdb",
"Ebs": {
"VolumeSize": 20,
"DeleteOnTermination": false,
"VolumeType": "standard"
}
}
]
For another example referencing a file containing more complex JSON-formatted parameters, see
Attaching an IAM Managed Policy to an IAM User (p. 127).
Most of the AWS Command Line Interface (AWS CLI) commands support the ability to accept all of the
parameter input from a file using the --cli-input-json and --cli-input-yaml parameters.
Those same commands helpfully provide the --generate-cli-skeleton parameter to generate a file
in either JSON or YAML format with all of the parameters that you can edit and fill in. Then you can run
the command with the relevant --cli-input-json or --cli-input-yaml parameter and point to
the filled-in file.
Important
Several AWS CLI commands don't map directly to individual AWS API operations, such as the
aws s3 commands. Such commands don't support either the --generate-cli-skeleton or
--cli-input-json and --cli-input-yaml parameters described in this topic. If you don't
know whether a specific command supports these parameters, run the following command,
replacing the service and command names with the ones you're interested in.
The output includes a Synopsis section that shows the parameters that the specified command
supports.
83
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
The --generate-cli-skeleton parameter causes the command not to run, but instead to generate
and display a parameter template that you can customize and use as input on a later command. The
generated template includes all of the parameters that the command supports.
• input – The generated template includes all input parameters formatted as JSON. This is the default
value.
• yaml-input – The generated template includes all input parameters formatted as YAML.
• output – The generated template includes all output parameters formatted as JSON. You can't
currently request the output parameters as YAML.
Because the AWS CLI is essentially a "wrapper" around the service's API, the skeleton file expects you
to reference all parameters by their underlying API parameter names. This is likely different from the
AWS CLI parameter name. For example, an AWS CLI parameter named user-name might map to the
AWS service's API parameter named UserName (notice the altered capitalization and missing dash). We
recommend that you use the --generate-cli-skeleton option to generate the template with the
"correct" parameter names to avoid errors. You can also reference the API Reference Guide for the service
to see the expected parameter names. You can delete any parameters from the template that are not
required and for which you don't want to supply a value.
For example, if you run the following command, it generates the parameter template for the Amazon
Elastic Compute Cloud (Amazon EC2) command run-instances.
JSON
The following example shows how to generate a template formatted in JSON by using the default
value (input) for the --generate-cli-skeleton parameter.
{
"DryRun": true,
"ImageId": "",
"MinCount": 0,
"MaxCount": 0,
"KeyName": "",
"SecurityGroups": [
""
],
"SecurityGroupIds": [
""
],
"UserData": "",
"InstanceType": "",
"Placement": {
"AvailabilityZone": "",
"GroupName": "",
"Tenancy": ""
},
"KernelId": "",
"RamdiskId": "",
"BlockDeviceMappings": [
{
"VirtualName": "",
"DeviceName": "",
"Ebs": {
"SnapshotId": "",
"VolumeSize": 0,
84
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
"DeleteOnTermination": true,
"VolumeType": "",
"Iops": 0,
"Encrypted": true
},
"NoDevice": ""
}
],
"Monitoring": {
"Enabled": true
},
"SubnetId": "",
"DisableApiTermination": true,
"InstanceInitiatedShutdownBehavior": "",
"PrivateIpAddress": "",
"ClientToken": "",
"AdditionalInfo": "",
"NetworkInterfaces": [
{
"NetworkInterfaceId": "",
"DeviceIndex": 0,
"SubnetId": "",
"Description": "",
"PrivateIpAddress": "",
"Groups": [
""
],
"DeleteOnTermination": true,
"PrivateIpAddresses": [
{
"PrivateIpAddress": "",
"Primary": true
}
],
"SecondaryPrivateIpAddressCount": 0,
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "",
"Name": ""
},
"EbsOptimized": true
}
YAML
The following example shows how to generate a template formatted in YAML by using the value
yaml-input for the --generate-cli-skeleton parameter.
85
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
86
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
Tenancy: dedicated █ The tenancy of the instance (if the instance is running in a
VPC). Valid values are: default, dedicated, host.
SpreadDomain: '' █ Reserved for future use.
RamdiskId: '' █ The ID of the RAM disk to select.
SecurityGroupIds: █ The IDs of the security groups.
- ''
SecurityGroups: █ [EC2-Classic, default VPC] The names of the security groups.
- ''
SubnetId: '' █ [EC2-VPC] The ID of the subnet to launch the instance into.
UserData: '' █ The user data to make available to the instance.
AdditionalInfo: '' █ Reserved.
ClientToken: '' █ Unique, case-sensitive identifier you provide to ensure the
idempotency of the request.
DisableApiTermination: true █ If you set this parameter to true, you can't terminate
the instance using the Amazon EC2 console, CLI, or API; otherwise, you can.
DryRun: true █ Checks whether you have the required permissions for the action, without
actually making the request, and provides an error response.
EbsOptimized: true █ Indicates whether the instance is optimized for Amazon EBS I/O.
IamInstanceProfile: █ The IAM instance profile.
Arn: '' █ The Amazon Resource Name (ARN) of the instance profile.
Name: '' █ The name of the instance profile.
InstanceInitiatedShutdownBehavior: stop █ Indicates whether an instance stops or
terminates when you initiate shutdown from the instance (using the operating system
command for system shutdown). Valid values are: stop, terminate.
NetworkInterfaces: █ The network interfaces to associate with the instance.
- AssociatePublicIpAddress: true █ Indicates whether to assign a public IPv4 address
to an instance you launch in a VPC.
DeleteOnTermination: true █ If set to true, the interface is deleted when the
instance is terminated.
Description: '' █ The description of the network interface.
DeviceIndex: 0 █ The position of the network interface in the attachment order.
Groups: █ The IDs of the security groups for the network interface.
- ''
Ipv6AddressCount: 0 █ A number of IPv6 addresses to assign to the network interface.
Ipv6Addresses: █ One or more IPv6 addresses to assign to the network interface.
- Ipv6Address: '' █ The IPv6 address.
NetworkInterfaceId: '' █ The ID of the network interface.
PrivateIpAddress: '' █ The private IPv4 address of the network interface.
PrivateIpAddresses: █ One or more private IPv4 addresses to assign to the network
interface.
- Primary: true █ Indicates whether the private IPv4 address is the primary private
IPv4 address.
PrivateIpAddress: '' █ The private IPv4 addresses.
SecondaryPrivateIpAddressCount: 0 █ The number of secondary private IPv4 addresses.
SubnetId: '' █ The ID of the subnet associated with the network interface.
InterfaceType: '' █ The type of network interface.
PrivateIpAddress: '' █ [EC2-VPC] The primary IPv4 address.
ElasticGpuSpecification: █ An elastic GPU to associate with the instance.
- Type: '' █ [REQUIRED] The type of Elastic Graphics accelerator.
ElasticInferenceAccelerators: █ An elastic inference accelerator to associate with the
instance.
- Type: '' █ [REQUIRED] The type of elastic inference accelerator.
TagSpecifications: █ The tags to apply to the resources during launch.
- ResourceType: network-interface █ The type of resource to tag. Valid values are:
client-vpn-endpoint, customer-gateway, dedicated-host, dhcp-options, elastic-ip,
fleet, fpga-image, host-reservation, image, instance, internet-gateway, launch-
template, natgateway, network-acl, network-interface, reserved-instances, route-table,
security-group, snapshot, spot-instances-request, subnet, traffic-mirror-filter,
traffic-mirror-session, traffic-mirror-target, transit-gateway, transit-gateway-
attachment, transit-gateway-route-table, volume, vpc, vpc-peering-connection, vpn-
connection, vpn-gateway.
Tags: █ The tags to apply to the resource.
- Key: '' █ The key of the tag.
Value: '' █ The value of the tag.
LaunchTemplate: █ The launch template to use to launch the instances.
LaunchTemplateId: '' █ The ID of the launch template.
87
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
1. Run the command with the --generate-cli-skeleton parameter to produce either JSON or
YAML and direct the output to a file to save it.
JSON
YAML
2. Open the parameter skeleton file in your text editor and remove any of the parameters that you
don't need. For example, you might strip the template down to the following. Be sure that the file is
still valid JSON or YAML after you remove the elements you don't need.
JSON
{
"DryRun": true,
"ImageId": "",
"KeyName": "",
"SecurityGroups": [
""
],
"InstanceType": "",
"Monitoring": {
"Enabled": true
88
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
}
}
YAML
DryRun: true
ImageId: ''
KeyName: ''
SecurityGroups:
- ''
InstanceType:
Monitoring:
Enabled: true
In this example, we leave the DryRun parameter set to true to use the Amazon EC2 dry run feature.
This feature lets you safely test the command without actually creating or modifying any resources.
3. Fill in the remaining values with values appropriate for your scenario. In this example, we provide
the instance type, key name, security group, and identifier of the Amazon Machine Image (AMI) to
use. This example assumes the default AWS Region. The AMI ami-dfc39aef is a 64-bit Amazon
Linux image hosted in the us-west-2 Region. If you use a different Region, you must find the
correct AMI ID to use.
JSON
{
"DryRun": true,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
YAML
DryRun: true
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
4. Run the command with the completed parameters by passing the completed template file to either
the --cli-input-json or --cli-input-yaml parameter by using the file:// prefix. The AWS
CLI interprets the path to be relative to your current working directory, so in the following example
that displays only the file name with no path, it looks for the file directly in the current working
directory.
JSON
89
AWS Command Line Interface User Guide
Generating a CLI Skeleton Template
YAML
The dry run error indicates that the JSON or YAML is formed correctly and that the parameter values
are valid. If other issues are reported in the output, fix them and repeat the previous step until the
"Request would have succeeded" message is displayed.
5. Now you can set the DryRun parameter to false to disable dry run.
JSON
{
"DryRun": false,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
YAML
DryRun: false
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
6. Run the command, and run-instances actually launches an EC2 instance and displays the details
generated by the successful launch. The format of the output is controlled by the --output
parameter, separately from the format of your input parameter template.
JSON
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
90
AWS Command Line Interface User Guide
Shorthand Syntax
...
YAML
OwnerId: '123456789012'
ReservationId: 'r-d94a2b1',
Groups":
- ''
Instances:
...
Structure Parameters
The shorthand syntax in the AWS CLI makes it easier for users to input parameters that are flat (non-
nested structures). The format is a comma-separated list of key-value pairs.
Linux or macOS
--option key1=value1,key2=value2,key3=value3
PowerShell
--option "key1=value1,key2=value2,key3=value3"
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
There must be no white space between each comma-separated key-value pair. Here is an example of the
Amazon DynamoDB update-table command with the --provisioned-throughput option specified
in shorthand.
91
AWS Command Line Interface User Guide
Controlling Command Output
The basic format is shown here, where values in the list are separated by a single space.
--option '[value1,value2,value3]'
As previously mentioned, you can specify a list of numbers, a list of strings, or a list of non-nested
structures in shorthand. The following is an example of the stop-instances command for Amazon
Elastic Compute Cloud (Amazon EC2), where the input parameter (list of strings) for the --instance-
ids option is specified in shorthand.
The following example shows the Amazon EC2 create-tags command, which takes a list of non-
nested structures for the --tags option. The --resources option specifies the ID of the instance to
tag.
This is equivalent to the following example, formatted in JSON. The JSON parameter is written over
multiple lines for readability.
Topics
• How to Select the Output Format (p. 93)
92
AWS Command Line Interface User Guide
How to Select the Output Format
As explained in the configuration (p. 35) topic, you can specify the output format in three ways:
• Using the output option in a named profile in the config file – The following example sets the
default output format to text.
[default]
output=text
• Using the AWS_DEFAULT_OUTPUT environment variable – The following output sets the format to
table for the commands in this command line session until the variable is changed or the session
ends. Using this environment variable overrides any value set in the config file.
$ export AWS_DEFAULT_OUTPUT="table"
• Using the --output option on the command line – The following example sets the output of
only this one command to json. Using this option on the command overrides any currently set
environment variable or the value in the config file.
You can customize and filter the results in any format by using the --query parameter. For more
information, see How to Filter the Output with the --query Option (p. 98).
For more advanced filtering that you might not be able to do with --query, you can consider
jq, a command line JSON processor. You can download it and find the official tutorial at http://
stedolan.github.io/jq/.
93
AWS Command Line Interface User Guide
YAML Output Format
{
"Users": [
{
"Path": "/",
"UserName": "Admin",
"UserId": "AIDA1111111111EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/Admin",
"CreateDate": "2014-10-16T16:03:09+00:00",
"PasswordLastUsed": "2016-06-03T18:37:29+00:00"
},
{
"Path": "/backup/",
"UserName": "backup-user",
"UserId": "AIDA2222222222EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/backup/backup-user",
"CreateDate": "2019-09-17T19:30:40+00:00"
},
{
"Path": "/",
"UserName": "cli-user",
"UserId": "AIDA3333333333EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/cli-user",
"CreateDate": "2019-09-17T19:11:39+00:00"
}
]
}
YAML is a good choice for handling the output programmatically with services and tools that emit or
consume YAML-formatted strings, such as AWS CloudFormation with its support for YAML-formatted
templates.
For more advanced filtering that you might not be able to do with --query, you can consider
yq, a command line YAML processor. You can download it and find documentation at http://
mikefarah.github.io/yq/.
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
94
AWS Command Line Interface User Guide
Text Output Format
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
The text output format follows the basic structure shown below. The columns are sorted alphabetically
by the corresponding key names of the underlying JSON object.
The following is an example of text output. Each field is tab separated from the others, with an extra
tab where there is an empty field.
The fourth column is the PasswordLastUsed field, and is empty for the last two entries because those
users never sign in to the AWS Management Console.
Important
We strongly recommend that if you specify text output, you also always use the --
query (p. 98) option to ensure consistent behavior.
This is because the text format alphabetically orders output columns by the key name of the
underlying JSON object returned by the AWS service, and similar resources might not have the
same key names. For example, the JSON representation of a Linux-based Amazon EC2 instance
might have elements that are not present in the JSON representation of a Windows-based
instance, or vice versa. Also, resources might have key-value elements added or removed in
future updates, altering the column ordering. This is where --query augments the functionality
of the text output to provide you with complete control over the output format.
In the following example, the command specifies which elements to display and defines the
ordering of the columns with the list notation [key1, key2, ...]. This gives you full
confidence that the correct key values are always displayed in the expected column. Finally,
notice how the AWS CLI outputs None as the value for keys that don't exist.
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
95
AWS Command Line Interface User Guide
Text Output Format
cli-user arn:aws:iam::123456789012:user/cli-backup
2019-09-17T19:11:39+00:00 None AIDA3333333333EXAMPLE
The following example shows how you can use grep and awk with the text output from the aws ec2
describe-instances command. The first command displays the Availability Zone, current state, and
the instance ID of each instance in text output. The second command processes that output to display
only the instance IDs of all running instances in the us-west-2a Availability Zone.
i-4b41a37c
i-3045b007
i-6fc67758
The following example goes a step further and shows not only how to filter the output, but how to use
that output to automate changing instance types for each stopped instance.
The text output can also be useful in PowerShell. Because the columns in text output are tab
delimited, you can easily split the output into an array by using PowerShell's `t delimiter. The following
command displays the value of the third column (InstanceId) if the first column (AvailabilityZone)
matches the string us-west-2a.
-4b41a37c
i-a071c394
i-3045b007
i-6fc67758
Notice that although the previous example does show how to use the --query parameter to parse the
underlying JSON objects and pull out the desired column, PowerShell has its own ability to handle JSON,
if cross-platform compatibility isn't a concern. Instead of handling the output as text, as most command
shells require, PowerShell lets you use the ConvertFrom-JSON cmdlet to produce a hierarchically
structured object. You can then directly access the member you want from that object.
96
AWS Command Line Interface User Guide
Table Output Format
Tip
If you output text, and filter the output to a single field using the --query parameter, the
output is a single line of tab-separated values. To get each value onto a separate line, you can
put the output field in brackets, as shown in the following examples.
Tab separated, single-line output:
HRDepartment
Developers
SpreadsheetUsers
LocalAdmins
-------------------------------------------------------------------------------------------------------
| ListUsers
|
+------------------------------------------------------------------------------------------------------
+
|| Users
||
|+----------------------------------------------------+---------------------------
+---------------------------+----------+-----------------------+-------------+|
|| Arn | CreateDate |
PasswordLastUsed | Path | UserId | UserName ||
|+----------------------------------------------------+---------------------------
+---------------------------+----------+-----------------------+-------------+|
|| arn:aws:iam::123456789012:user/Admin | 2014-10-16T16:03:09+00:00 |
2016-06-03T18:37:29+00:00 | / | AIDA1111111111EXAMPLE | Admin ||
|| arn:aws:iam::123456789012:user/backup/backup-user | 2019-09-17T19:30:40+00:00 |
| /backup/ | AIDA2222222222EXAMPLE | backup-user ||
|| arn:aws:iam::123456789012:user/cli-user | 2019-09-17T19:11:39+00:00 |
| / | AIDA3333333333EXAMPLE | cli-user ||
+------------------------------------------------------------------------------------------------------
+
You can combine the --query option with the table format to display a set of elements preselected
from the raw output. Notice the output differences between dictionary and list notations: in the first
example, column names are ordered alphabetically, and in the second example, unnamed columns are
97
AWS Command Line Interface User Guide
How to Filter the Output with the --query Option
ordered as defined by the user. For more information about the --query option, see How to Filter the
Output with the --query Option (p. 98).
------------------------------------------------------
| DescribeVolumes |
+------------+----------------+--------------+-------+
| AZ | ID | InstanceId | Size |
+------------+----------------+--------------+-------+
| us-west-2a| vol-e11a5288 | i-a071c394 | 30 |
| us-west-2a| vol-2e410a47 | i-4b41a37c | 8 |
+------------+----------------+--------------+-------+
----------------------------------------------------
| DescribeVolumes |
+--------------+--------------+--------------+-----+
| vol-e11a5288| i-a071c394 | us-west-2a | 30 |
| vol-2e410a47| i-4b41a37c | us-west-2a | 8 |
+--------------+--------------+--------------+-----+
• If you specify --output text, the output is paginated before the --query filter is
applied, and the AWS CLI runs the query once on each page of the output. This can result in
unexpected extra output, especially if your filter specifies an array element using something
like [0], because the output then includes the first matching element on each page. To work
around the extra output that --output text can produce, you can specify --no-paginate.
This causes the filter to apply only to the complete set of results. But it does remove any
pagination, so it might result in long output. You can also use other command line tools such
as head or tail to additionally filter the output to only the values you want.
• If you specify --output json, the output is completely processed as a single, native JSON
structure before the --query filter is applied. The AWS CLI runs the query only once against
the entire JSON structure, producing a filtered JSON result that is then output.
• If you specify --output yaml, the output is completely processed as a single, native JSON
structure before the --query filter is applied. The AWS CLI runs the query only once against
the entire JSON structure, producing a filtered JSON result that is then converted to YAML
and output.
To demonstrate how --query works, we start with the following default JSON output. This describes
two Amazon Elastic Block Store (Amazon EBS) volumes attached to separate Amazon EC2 instances.
98
AWS Command Line Interface User Guide
How to Filter the Output with the --query Option
{
"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
}
]
}
You can choose to display only the first volume from the Volumes list by using the following command
that indexes the first volume in the array.
{
"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",
99
AWS Command Line Interface User Guide
How to Filter the Output with the --query Option
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
The next example uses the wildcard notation [*] to iterate over all of the volumes in the
list, filtering out three elements from each volume: VolumeId, AvailabilityZone, and
Size. The dictionary notation requires that you provide an alias for each JSON key, like this:
{Alias1:JSONKey1,Alias2:JSONKey2}. A dictionary is inherently unordered, so the ordering of the
keys/aliases within a structure might be inconsistent.
[
{
"AZ": "us-west-2a",
"ID": "vol-e11a5288",
"Size": 30
},
{
"AZ": "us-west-2a",
"ID": "vol-2e410a47",
"Size": 8
}
]
Using dictionary notation, you can also chain keys together, like key1.key2[0].key3, to filter
elements deeply nested within the structure. The following example demonstrates this with the
Attachments[0].InstanceId key, aliased to simply InstanceId.
[
{
"InstanceId": "i-a071c394",
"AZ": "us-west-2a",
"ID": "vol-e11a5288",
"Size": 30
},
{
"InstanceId": "i-4b41a37c",
"AZ": "us-west-2a",
"ID": "vol-2e410a47",
"Size": 8
}
]
You can also filter multiple elements using list notation: [key1, key2]. This formats all filtered
attributes into a single ordered list per object, regardless of type.
[
[
"vol-e11a5288",
100
AWS Command Line Interface User Guide
How to Filter the Output with the --query Option
"i-a071c394",
"us-west-2a",
30
],
[
"vol-2e410a47",
"i-4b41a37c",
"us-west-2a",
8
]
]
To filter results by the value of a specific field, use the JMESPath "?" operator. The following example
query outputs only volumes in the us-west-2a Availability Zone.
Note
When specifying a literal value such as "us-west-2" above in a JMESPath query expression,
you must surround the value in backticks (` `) for it to be read properly.
Here are some additional examples that illustrate how you can get only the details you want from the
output of your commands.
The following example lists Amazon EC2 volumes. The service produces a list of all attached volumes
in the us-west-2a Availability Zone. The --query parameter further limits the output to only those
volumes with a Size value that is larger than 50, and shows only the specified fields with user-defined
names.
[
{
"Id": "vol-0be9bb0bf12345678",
"Size": 80,
"Type": "gp2"
}
]
The following example retrieves a list of images that meet several criteria. It then uses the --query
parameter to sort the output by CreationDate, selecting only the most recent. Finally, it displays the
ImageId of that one image.
ami-00ced3122871a4921
The following example uses the --query parameter to find a specific item in a list and then extracts
information from that item. The example lists all of the Availability Zones associated with the
101
AWS Command Line Interface User Guide
How to Filter the Output with the --query Option
specified service endpoint. It extracts the item from the ServiceDetails list that has the specified
ServiceName, then outputs the AvailabilityZones field from that selected item.
[
[
"us-east-1a",
"us-east-1b",
"us-east-1c",
"us-east-1d",
"us-east-1e",
"us-east-1f"
]
]
The --query parameter also enables you to count items in the output. The following example displays
the number of available volumes that are more than 1000 IOPS by using length to count how many are
in a list.
The following example shows how to list all of your snapshots that were created after a specified date,
including only a few of the available fields in the output.
[
{
"id": "snap-0effb42b7a1b2c3d4",
"vid": "vol-0be9bb0bf12345678",
"Size": 8
}
]
The following example lists the five most recent Amazon Machine Images (AMIs) that you created, sorted
from most recent to oldest.
[
{
"id": "ami-0a1b2c3d4e5f60001",
"date": "2018-11-28T17:16:38.000Z"
},
{
"id": "ami-0a1b2c3d4e5f60002",
102
AWS Command Line Interface User Guide
How to Set the Output’s Default Pager Program
"date": "2018-09-15T13:51:22.000Z"
},
{
"id": "ami-0a1b2c3d4e5f60003",
"date": "2018-08-19T10:22:45.000Z"
},
{
"id": "ami-0a1b2c3d4e5f60004",
"date": "2018-05-03T12:04:02.000Z"
},
{
"id": "ami-0a1b2c3d4e5f60005",
"date": "2017-12-13T17:16:38.000Z"
}
This following example shows only the InstanceId for any unhealthy instances in the specified Auto
Scaling group.
Combined with the output formats that are explained in more detail previously in this topic, the --
query option is a powerful tool you can use to customize the content and style of outputs.
For more examples and the full spec of JMESPath, the underlying JSON-processing library, see http://
jmespath.org/specification.html.
AWS CLI version 2 provides the use of a client-side pager program for output. By default, this feature
returns all output through your operating system’s default pager program. Client-side pagination occurs
after any server-side pagination you specify, see Pagination (p. 104).
To disable all use of an external paging program, set the variable to an empty string.
• Using the cli_pager option in the config file - The following example sets the default output
pager to the less program.
[default]
cli_pager=less
The following example sets the default to disable the use of a pager.
[default]
cli_pager=
• Using the AWS_PAGER environment variable - The following example sets the default output pager to
the less program.
103
AWS Command Line Interface User Guide
Pagination
Linux or macOS
$ export AWS_PAGER="less"
Windows
Linux or macOS
$ export AWS_PAGER=""
Windows
Server-side pagination parameters process first and any output is sent to client-side pagination.
Server-side Pagination
For commands that can return a large list of items, the AWS Command Line Interface (AWS CLI) has three
options to control the number of items included in the output when the AWS CLI calls a service's API to
populate the list.
• --page-size
• --max-items
• --starting-token
By default, the AWS CLI uses a page size of 1000 and retrieves all available items. For example, if you run
aws s3api list-objects on an Amazon S3 bucket that contains 3,500 objects, the AWS CLI makes
four calls to Amazon S3, handling the service-specific pagination logic for you in the background and
returning all 3,500 objects in the final output.
104
AWS Command Line Interface User Guide
Client-side Pagination
performs a larger number of service API calls in the background and retrieves a smaller number of items
with each call. This gives the individual calls a better chance of succeeding without a timeout. Changing
the page size doesn't affect the output; it affects only the number of API calls that need to be made to
generate the output.
The specified AWS service might not return items in the same order each time you call. If you specify
different values for --page-size and --max-items, you can get unexpected results with missing or
duplicated items. To prevent this, use the same number for --page-size and --max-items to sync
the AWS CLI pagination with the pagination of the underlying service. You can also retrieve the whole list
and perform any necessary paging operations locally.
Client-side Pagination
AWS CLI version 2 provides the use of a client-side pager program for output. By default, this feature
returns all output through your operating system’s default pager program. Client-side pagination occurs
after any server-side pagination you specify.
105
AWS Command Line Interface User Guide
Return Codes
To disable all use of an external paging program, set the variable to an empty string.
You can specify the output pager in the following two ways:
• Using the cli_pager option in the config file - The following example sets the default output
pager to the less program.
[default]
cli_pager=less
The following example sets the default to disable the use of a pager.
[default]
cli_pager=
• Using the AWS_PAGER environment variable - The following example sets the default output pager to
the less program.
Linux or macOS
$ export AWS_PAGER="less"
Windows
Linux or macOS
$ export AWS_PAGER=""
Windows
Linux/Unix/Mac systems
$ echo $?
Windows PowerShell
106
AWS Command Line Interface User Guide
Return Codes
The following are the return code values that can be returned at the end of running an AWS Command
Line Interface (AWS CLI) command.
Code
Meaning
0 The command completed successfully. There were no errors generated by either the AWS CLI or by
the AWS service to which the request was sent.
• Applicable to all CLI commands – the command entered on the command line couldn't be parsed.
Parsing failures can be caused by, but aren't limited to, missing required subcommands or
arguments, or using unknown commands or arguments.
• Limited to S3 commands. – One or more files marked for transfer were skipped during the
transfer process. However, all other files marked for transfer were successfully transferred. Files
that are skipped during the transfer process include: files that don't exist; files that are character
special devices, block special device, FIFO queues, or sockets; and files that the user doesn't have
read permissions to.
255The command failed. There were errors generated by the AWS CLI or by the AWS service to which
the request was sent.
For more details about a failure, run the command with the --debug switch. This produces a detailed
report of the steps the AWS CLI uses to process the command, and what the result of each step was.
107
AWS Command Line Interface User Guide
DynamoDB
For a complete reference of all the available commands for each service, see the AWS CLI Command
Reference, or use the built-in command line help. For more information, see Getting Help with the AWS
CLI (p. 72).
Topics
• Using Amazon DynamoDB with the AWS CLI (p. 108)
• Using Amazon EC2 with the AWS CLI (p. 110)
• Using Amazon S3 Glacier with the AWS CLI (p. 122)
• Using AWS Identity and Access Management from the AWS CLI (p. 125)
• Using Amazon S3 with the AWS CLI (p. 129)
• Using Amazon SNS with the AWS CLI (p. 135)
• Using Amazon SWF with the AWS CLI (p. 137)
To list the AWS CLI commands for DynamoDB, use the following command.
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
The command line format consists of an DynamoDB command name, followed by the parameters for
that command. The AWS CLI supports the CLI shorthand syntax (p. 91) for the parameter values, and full
JSON.
108
AWS Command Line Interface User Guide
DynamoDB
You can add new lines to the table with commands similar to those shown in the following example.
These examples use a combination of shorthand syntax and JSON.
{
"ConsumedCapacity": {
"CapacityUnits": 1.0,
"TableName": "MusicCollection"
}
}
It can be difficult to compose valid JSON in a single-line command. To make this easier, the AWS CLI
can read JSON files. For example, consider the following JSON snippet, which is stored in a file named
expression-attributes.json.
{
":v1": {"S": "No One You Know"},
":v2": {"S": "Call Me Today"}
}
You can use that file to issue a query request using the AWS CLI. In the following example, the content
of the expression-attributes.json file is used as the value for the --expression-attribute-
values parameter.
109
AWS Command Line Interface User Guide
Amazon EC2
{
"AlbumTitle": {
"S": "Somewhat Famous"
},
"SongTitle": {
"S": "Call Me Today"
},
"Artist": {
"S": "No One You Know"
}
}
],
"ScannedCount": 1,
"ConsumedCapacity": null
}
For more information about using the AWS CLI with DynamoDB, see DynamoDB in the AWS CLI
Command Reference.
In addition to DynamoDB, you can use the AWS CLI with DynamoDB Local. DynamoDB Local is a small
client-side database and server that mimics the DynamoDB service. DynamoDB Local enables you
to write applications that use the DynamoDB API, without manipulating any tables or data in the
DynamoDB web service. Instead, all of the API actions are rerouted to a local database. This lets you save
on provisioned throughput, data storage, and data transfer fees.
For more information about DynamoDB Local and how to use it with the AWS CLI, see the following
sections of the Amazon DynamoDB Developer Guide:
• DynamoDB Local
• Using the AWS CLI with DynamoDB Local
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
This topic shows examples of AWS CLI commands that perform common tasks for Amazon EC2.
Topics
• Creating, Displaying, and Deleting Amazon EC2 Key Pairs (p. 110)
• Creating, Configuring, and Deleting Security Groups for Amazon EC2 (p. 112)
• Launching, Listing, and Terminating Amazon EC2 Instances (p. 116)
110
AWS Command Line Interface User Guide
Amazon EC2 Key Pairs
You must provide the key pair to Amazon EC2 when you create the instance, and then use that key pair
to authenticate when you connect to the instance.
Note
The following examples assume that you have already configured your default
credentials (p. 110).
Topics
• Create a Key Pair (p. 111)
• Display Your Key Pair (p. 112)
• Delete Your Key Pair (p. 112)
For PowerShell, the > file redirection defaults to UTF-8 encoding, which cannot be used with some
SSH clients. So, you must convert the output by piping it to the out-file command and explicitly set
the encoding to ascii.
-----BEGIN RSA PRIVATE KEY-----
EXAMPLEKEYKCAQEAy7WZhaDsrA1W3mRlQtvhwyORRX8gnxgDAfRt/gx42kWXsT4rXE/b5CpSgie/
vBoU7jLxx92pNHoFnByP+Dc21eyyz6CvjTmWA0JwfWiW5/akH7iO5dSrvC7dQkW2duV5QuUdE0QW
Z/aNxMniGQE6XAgfwlnXVBwrerrQo+ZWQeqiUwwMkuEbLeJFLhMCvYURpUMSC1oehm449ilx9X1F
G50TCFeOzfl8dqqCP6GzbPaIjiU19xX/azOR9V+tpUOzEL+wmXnZt3/nHPQ5xvD2OJH67km6SuPW
oPzev/D8V+x4+bHthfSjR9Y7DvQFjfBVwHXigBdtZcU2/wei8D/HYwIDAQABAoIBAGZ1kaEvnrqu
/uler7vgIn5m7lN5LKw4hJLAIW6tUT/fzvtcHK0SkbQCQXuriHmQ2MQyJX/0kn2NfjLV/ufGxbL1
mb5qwMGUnEpJaZD6QSSs3kICLwWUYUiGfc0uiSbmJoap/GTLU0W5Mfcv36PaBUNy5p53V6G7hXb2
bahyWyJNfjLe4M86yd2YK3V2CmK+X/BOsShnJ36+hjrXPPWmV3N9zEmCdJjA+K15DYmhm/tJWSD9
81oGk9TopEp7CkIfatEATyyZiVqoRq6k64iuM9JkA3OzdXzMQexXVJ1TLZVEH0E7bhlY9d8O1ozR
oQs/FiZNAx2iijCWyv0lpjE73+kCgYEA9mZtyhkHkFDpwrSM1APaL8oNAbbjwEy7Z5Mqfql+lIp1
YkriL0DbLXlvRAH+yHPRit2hHOjtUNZh4Axv+cpg09qbUI3+43eEy24B7G/Uh+GTfbjsXsOxQx/x
p9otyVwc7hsQ5TA5PZb+mvkJ5OBEKzet9XcKwONBYELGhnEPe7cCgYEA06Vgov6YHleHui9kHuws
ayav0elc5zkxjF9nfHFJRry21R1trw2Vdpn+9g481URrpzWVOEihvm+xTtmaZlSp//lkq75XDwnU
WA8gkn6O3QE3fq2yN98BURsAKdJfJ5RL1HvGQvTe10HLYYXpJnEkHv+Unl2ajLivWUt5pbBrKbUC
gYBjbO+OZk0sCcpZ29sbzjYjpIddErySIyRX5gV2uNQwAjLdp9PfN295yQ+BxMBXiIycWVQiw0bH
oMo7yykABY7Ozd5wQewBQ4AdSlWSX4nGDtsiFxWiI5sKuAAeOCbTosy1s8w8fxoJ5Tz1sdoxNeGs
Arq6Wv/G16zQuAE9zK9vvwKBgF+09VI/1wJBirsDGz9whVWfFPrTkJNvJZzYt69qezxlsjgFKshy
WBhd4xHZtmCqpBPlAymEjr/TOlbxyARmXMnIOWIAnNXMGB4KGSyl1mzSVAoQ+fqR+cJ3d0dyPl1j
jjb0Ed/NY8frlNDxAVHE8BSkdsx2f6ELEyBKJSRr9snRAoGAMrTwYneXzvTskF/S5Fyu0iOegLDa
NWUH38v/nDCgEpIXD5Hn3qAEcju1IjmbwlvtW+nY2jVhv7UGd8MjwUTNGItdb6nsYqM2asrnF3qS
VRkAKKKYeGjkpUfVTrW0YFjXkfcrR/V+QFL5OndHAKJXjW7a4ejJLncTzmZSpYzwApc=
-----END RSA PRIVATE KEY-----
Your private key isn't stored in AWS and can be retrieved only when it's created. You can't recover it later.
Instead, if you lose the private key, you must create a new key pair.
If you're connecting to your instance from a Linux computer, we recommend that you use the following
command to set the permissions of your private key file so that only you can read it.
111
AWS Command Line Interface User Guide
Amazon EC2 Security Groups
The fingerprint is an SHA1 hash taken from a DER-encoded copy of the private key. This value is captured
when the key pair is created, and is stored in AWS with the public key. You can view the fingerprint in the
Amazon EC2 console or by running the AWS CLI command aws ec2 describe-key-pairs.
For more information about keys and fingerprints, see Amazon EC2 Key Pairs in the Amazon EC2 User
Guide for Linux Instances.
You can create security groups to use in a virtual private cloud (VPC), or in the EC2-Classic shared flat
network. For more information about the differences between EC2-Classic and EC2-VPC, see Supported
Platforms in the Amazon EC2 User Guide for Linux Instances.
Use the AWS Command Line Interface (AWS CLI) to create a security group, add rules to existing security
groups, and delete security groups.
Note
The following examples assume that you have already configured your default
credentials (p. 110).
Topics
• Create a Security Group (p. 113)
• Add Rules to Your Security Group (p. 114)
112
AWS Command Line Interface User Guide
Amazon EC2 Security Groups
EC2-VPC
The following example shows how to create a security group for a specified VPC.
$ aws ec2 create-security-group --group-name my-sg --description "My security group" --vpc-
id vpc-1a2b3c4d
{
"GroupId": "sg-903004f8"
}
To view the initial information for a security group, run the describe-security-groups command. You can
reference an EC2-VPC security group only by its vpc-id, not its name.
EC2-Classic
The following example shows how to create a security group for EC2-Classic.
To view the initial information for my-sg, run the describe-security-groups command. For an EC2-Classic
security group, you can reference it by its name.
113
AWS Command Line Interface User Guide
Amazon EC2 Security Groups
{
"SecurityGroups": [
{
"IpPermissionsEgress": [],
"Description": "My security group"
"IpPermissions": [],
"GroupName": "my-sg",
"OwnerId": "123456789012",
"GroupId": "sg-903004f8"
}
]
}
For example, if you're launching a Windows instance, you typically add a rule to allow inbound traffic
on TCP port 3389 to support Remote Desktop Protocol (RDP). If you're launching a Linux instance, you
typically add a rule to allow inbound traffic on TCP port 22 to support SSH connections.
EC2-VPC
The following example shows how to add a rule for RDP (TCP port 3389) to an EC2-VPC security group
with the ID sg-903004f8. This example assumes the client computer has an address somewhere in the
CIDR range 203.0.113.0/24.
You can start by confirming that your public address shows as included in the CIDR range
203.0.113.0/24.
$ curl https://checkip.amazonaws.com
203.0.113.57
With that information confirmed, you can add the range to your security group by running the
authorize-security-group-ingress command.
The following command adds another rule to enable SSH to instances in the same security group.
114
AWS Command Line Interface User Guide
Amazon EC2 Security Groups
To view the changes to the security group, run the describe-security-groups command.
EC2-Classic
The following command adds a rule for RDP to the EC2-Classic security group named my-sg.
The following command adds another rule for SSH to the same security group.
To view the changes to your security group, run the describe-security-groups command.
115
AWS Command Line Interface User Guide
EC2 Instances
"ToPort": 22,
"IpProtocol": "tcp",
"IpRanges": [
{
"CidrIp": "203.0.113.0/24"
}
]
"UserIdGroupPairs": [],
"FromPort": 22
}
],
"GroupName": "my-sg",
"OwnerId": "123456789012",
"GroupId": "sg-903004f8"
}
]
}
EC2-VPC
The following command deletes an EC2-VPC security group.
EC2-Classic
The following command deletes the EC2-Classic security group named my-sg.
If you launch an instance that isn't within the AWS Free Tier, you are billed after you launch the instance
and charged for the time that the instance is running, even if it remains idle.
Note
The following examples assume that you have already configured your default
credentials (p. 110).
Topics
• Launch Your Instance (p. 117)
• Add a Block Device to Your Instance (p. 120)
116
AWS Command Line Interface User Guide
EC2 Instances
Initially, your instance appears in the pending state, but changes to the running state after a few
minutes.
EC2-VPC
The following example shows how to launch a t2.micro instance in the specified subnet of a VPC.
Replace the italicized parameter values with your own.
117
AWS Command Line Interface User Guide
EC2 Instances
"Status": "in-use",
"SourceDestCheck": true,
"VpcId": "vpc-1a2b3c4d",
"Description": "Primary network interface",
"NetworkInterfaceId": "eni-a7edb1c9",
"PrivateIpAddresses": [
{
"PrivateDnsName": "ip-10-0-1-114.ec2.internal",
"Primary": true,
"PrivateIpAddress": "10.0.1.114"
}
],
"PrivateDnsName": "ip-10-0-1-114.ec2.internal",
"Attachment": {
"Status": "attached",
"DeviceIndex": 0,
"DeleteOnTermination": true,
"AttachmentId": "eni-attach-52193138",
"AttachTime": "2013-07-19T02:42:39.000Z"
},
"Groups": [
{
"GroupName": "my-sg",
"GroupId": "sg-903004f8"
}
],
"SubnetId": "subnet-6e7f829e",
"OwnerId": "123456789012",
"PrivateIpAddress": "10.0.1.114"
}
],
"SourceDestCheck": true,
"Placement": {
"Tenancy": "default",
"GroupName": null,
"AvailabilityZone": "us-west-2b"
},
"Hypervisor": "xen",
"BlockDeviceMappings": [
{
"DeviceName": "/dev/sda1",
"Ebs": {
"Status": "attached",
"DeleteOnTermination": true,
"VolumeId": "vol-877166c8",
"AttachTime": "2013-07-19T02:42:39.000Z"
}
}
],
"Architecture": "x86_64",
"StateReason": {
"Message": "pending",
"Code": "pending"
},
"RootDeviceName": "/dev/sda1",
"VirtualizationType": "hvm",
"RootDeviceType": "ebs",
"Tags": [
{
"Value": "MyInstance",
"Key": "Name"
}
],
"AmiLaunchIndex": 0
}
]
118
AWS Command Line Interface User Guide
EC2 Instances
EC2-Classic
If your account supports it, you can use the following command to launch a t1.micro instance in EC2-
Classic. Replace the italicized parameter values with your own.
119
AWS Command Line Interface User Guide
EC2 Instances
"Message": "pending",
"Code": "pending"
},
"RootDeviceName": "/dev/sda1",
"VirtualizationType": "hvm",
"RootDeviceType": "ebs",
"Tags": [
{
"Value": "MyInstance",
"Key": "Name"
}
],
"AmiLaunchIndex": 0
}
]
}
To add a block device to your instance, specify the --block-device-mappings option when you use
run-instances.
The following example parameter provisions a standard Amazon EBS volume that is 20 GB in size, and
maps it to your instance using the identifier /dev/sdf.
--block-device-mappings "[{\"DeviceName\":\"/dev/sdf\",\"Ebs\":{\"VolumeSize\":20,
\"DeleteOnTermination\":false}}]"
The following example adds an Amazon EBS volume, mapped to /dev/sdf, based on an existing
snapshot. A snapshot represents an image that is loaded onto the volume for you. When you specify a
snapshot, you don't have to specify a volume size; it will be large enough to hold your image. However, if
you do specify a size, it must be greater than or equal to the size of the snapshot.
--block-device-mappings "[{\"DeviceName\":\"/dev/sdf\",\"Ebs\":{\"SnapshotId\":\"snap-
a1b2c3d4\"}}]"
The following example adds two volumes to your instance. The number of volumes available to your
instance depends on its instance type.
--block-device-mappings "[{\"DeviceName\":\"/dev/sdf\",\"VirtualName\":\"ephemeral0\"},
{\"DeviceName\":\"/dev/sdg\",\"VirtualName\":\"ephemeral1\"}]"
The following example creates the mapping (/dev/sdj), but doesn't provision a volume for the
instance.
--block-device-mappings "[{\"DeviceName\":\"/dev/sdj\",\"NoDevice\":\"\"}]"
For more information, see Block Device Mapping in the Amazon EC2 User Guide for Linux Instances.
120
AWS Command Line Interface User Guide
EC2 Instances
The following example shows how to add a tag with the key name "Name and the value "MyInstance" to
the specified instance, by using the create-tags command.
The following command filters the list to only your t2.micro instances and outputs only the
InstanceId values for each match.
The following command lists any of your instances that have the tag Name=MyInstance.
The following command lists your instances that were launched using any of the following AMIs: ami-
x0123456, ami-y0123456, and ami-z0123456.
As soon as the state of the instance changes to shutting-down or terminated, you stop incurring
charges for that instance. If you want to reconnect to an instance later, use stop-instances instead of
terminate-instances. For more information, see Terminate Your Instance in the Amazon EC2 User
Guide for Linux Instances.
When you finish with an instance, you can use the command terminate-instances to delete it.
121
AWS Command Line Interface User Guide
S3 Glacier
"PreviousState": {
"Code": 16,
"Name": "running"
}
}
]
}
This topic shows examples of AWS CLI commands that perform common tasks for S3 Glacier. The
examples demonstrate how to use the AWS CLI to upload a large file to S3 Glacier by splitting it into
smaller parts and uploading them from the command line.
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
Note
This tutorial uses several command line tools that typically come preinstalled on Unix-like
operating systems, including Linux and macOS. Windows users can use the same tools by
installing Cygwin and running the commands from the Cygwin terminal. We note Windows
native commands and utilities that perform the same functions where available.
Topics
• Create an Amazon S3 Glacier Vault (p. 122)
• Prepare a File for Uploading (p. 122)
• Initiate a Multipart Upload and Upload Files (p. 123)
• Complete the Upload (p. 124)
Note
All S3 Glacier commands require an account ID parameter. Use the hyphen character (--
account-id -) to use the current account.
Linux or macOS
122
AWS Command Line Interface User Guide
Initiate a Multipart Upload and Upload Files
dd is a utility that copies a number of bytes from an input file to an output file. The previous example
uses the system device file /dev/urandom as a source of random data. fsutil performs a similar
function in Windows.
Windows
Note
HJ-Split is a free file splitter for Windows and many other platforms.
S3 Glacier requires the size of each part in bytes (1 MiB in this example), your vault name, and an account
ID to configure the multipart upload. The AWS CLI outputs an upload ID when the operation is complete.
Save the upload ID to a shell variable for later use.
Linux or macOS
$ UPLOADID="19gaRezEXAMPLES6Ry5YYdqthHOC_kGRCT03L9yetr220UmPtBYKk-
OssZtLqyFu7sY1_lR7vgFuJV6NtcV5zpsJ"
Windows
Next, use the upload-multipart-part command to upload each of the three parts.
123
AWS Command Line Interface User Guide
Complete the Upload
{
"checksum": "e1f2a7cd6e047fa606fe2f0280350f69b9f8cfa602097a9a026360a7edc1f553"
}
$ aws glacier upload-multipart-part --upload-id $UPLOADID --body chunkab --range 'bytes
1048576-2097151/*' --account-id - --vault-name myvault
{
"checksum": "e1f2a7cd6e047fa606fe2f0280350f69b9f8cfa602097a9a026360a7edc1f553"
}
$ aws glacier upload-multipart-part --upload-id $UPLOADID --body chunkac --range 'bytes
2097152-3145727/*' --account-id - --vault-name myvault
{
"checksum": "e1f2a7cd6e047fa606fe2f0280350f69b9f8cfa602097a9a026360a7edc1f553"
}
Note
The previous example uses the dollar sign ($) to reference the contents of the UPLOADID shell
variable on Linux. On the Windows command line, use a percent sign (%) on either side of the
variable name (for example, %UPLOADID%).
You must specify the byte range of each part when you upload it so that S3 Glacier can reassemble it in
the correct order. Each piece is 1,048,576 bytes, so the first piece occupies bytes 0-1048575, the second
1048576-2097151, and the third 2097152-3145727.
To calculate a tree hash, you must split the file into 1 MiB parts and calculate a binary SHA-256 hash of
each piece. Then you split the list of hashes into pairs, combine the two binary hashes in each pair, and
take hashes of the results. Repeat this process until there is only one hash left. If there is an odd number
of hashes at any level, promote it to the next level without modifying it.
The key to calculating a tree hash correctly when using command line utilities is to store each hash in
binary format and convert to hexadecimal only at the last step. Combining or hashing the hexadecimal
version of any hash in the tree will cause an incorrect result.
Note
Windows users can use the type command in place of cat. OpenSSL is available for Windows at
OpenSSL.org.
1. If you haven't already, split the original file into 1 MiB parts.
3. Combine the first two hashes and take the binary hash of the result.
124
AWS Command Line Interface User Guide
IAM
4. Combine the parent hash of chunks aa and ab with the hash of chunk ac and hash the result, this
time outputting hexadecimal. Store the result in a shell variable.
Finally, complete the upload with the complete-multipart-upload command. This command takes
the original file's size in bytes, the final tree hash value in hexadecimal, and your account ID and vault
name.
You can also check the status of the vault using the describe-vault command.
Note
Vault status is updated about once per day. See Working with Vaults for more information.
Now it's safe to remove the chunk and hash files that you created.
$ rm chunk* hash*
For more information on multipart uploads, see Uploading Large Archives in Parts and Computing
Checksums in the Amazon S3 Glacier Developer Guide.
125
AWS Command Line Interface User Guide
Creating IAM Users and Groups
This topic shows examples of AWS CLI commands that perform common tasks for IAM.
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
Topics
• Creating IAM Users and Groups (p. 126)
• Attaching an IAM Managed Policy to an IAM User (p. 127)
• Setting an Initial Password for an IAM User (p. 128)
• Create an Access Key for an IAM User (p. 128)
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
4. To verify that the MyIamGroup group contains the MyUser, use the get-group command.
126
AWS Command Line Interface User Guide
Attaching an IAM Managed Policy to an IAM User
"CreateDate": "2018-12-14T03:03:52Z",
"GroupId": "AGPAJNUJ2W4IJVEXAMPLE",
"Arn": "arn:aws:iam::123456789012:group/MyIamGroup",
"Path": "/"
},
"Users": [
{
"UserName": "MyUser",
"Path": "/",
"CreateDate": "2018-12-14T03:13:02Z",
"UserId": "AIDAJY2PE5XUZ4EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/MyUser"
}
],
"IsTruncated": "false"
}
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
1. Determine the Amazon Resource Name (ARN) of the policy to attach. The following command uses
list-policies to find the ARN of the policy with the name PowerUserAccess. It then stores
that ARN in an environment variable.
2. To attach the policy, use the attach-user-policy command, and reference the environment
variable that holds the policy ARN.
3. Verify that the policy is attached to the user by running the list-attached-user-policies
command.
For more information, see Access Management Resources. This topic provides links to an overview of
permissions and policies, and links to examples of policies for accessing Amazon S3, Amazon EC2, and
other services.
127
AWS Command Line Interface User Guide
Setting an Initial Password for an IAM User
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
The following command uses create-login-profile to set an initial password on the specified user. When
the user signs in for the first time, the user is required to change the password to something that only
the user knows.
You can use the update-login-profile command to change the password for an IAM user.
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
You can use the create-access-key command to create an access key for an IAM user. An access key is
a set of security credentials that consists of an access key ID and a secret key.
An IAM user can create only two access keys at one time. If you try to create a third set, the command
returns a LimitExceeded error.
Use the delete-access-key command to delete an access key for an IAM user. Specify which access
key to delete by using the access key ID.
128
AWS Command Line Interface User Guide
Amazon S3
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
The AWS CLI provides two tiers of commands for accessing Amazon S3:
• The s3 tier consists of high-level commands that simplify performing common tasks, such as creating,
manipulating, and deleting objects and buckets.
• The s3api tier behaves identically to other AWS services by exposing direct access to all Amazon S3
API operations. It enables you to carry out advanced operations that might not be possible with the
following tier's high-level commands alone.
To get a list of all of the commands available in each tier, use the help argument with the aws s3api or
aws s3 commands.
$ aws s3 help
Note
The AWS CLI supports copying, moving, and syncing from Amazon S3 to Amazon S3 using the
server-side COPY operation provided by Amazon S3. This means that your files are kept in the
cloud, and are not downloaded to the client machine, then back up to Amazon S3.
When operations such as these can be performed completely in the cloud, only the bandwidth
necessary for the HTTP request and response is used.
Topics
• Using High-Level (s3) Commands with the AWS CLI (p. 129)
• Using API-Level (s3api) Commands with the AWS CLI (p. 133)
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
Manage Buckets
High-level aws s3 commands support common bucket operations, such as creating, listing, and deleting
buckets.
Create a Bucket
Use the s3 mb command to create a bucket. Bucket names must be globally unique and should be DNS
compliant. Bucket names can contain lowercase letters, numbers, hyphens, and periods. Bucket names
can start and end only with a letter or number, and cannot contain a period next to a hyphen or another
period.
129
AWS Command Line Interface User Guide
High-Level (s3) Commands
$ aws s3 mb s3://bucket-name
$ aws s3 ls
2018-12-11 17:08:50 my-bucket
2018-12-14 14:55:44 my-bucket2
The following command lists all objects and folders (referred to in S3 as 'prefixes') in a bucket.
$ aws s3 ls s3://bucket-name
PRE path/
2018-12-04 19:05:48 3 MyFile1.txt
The previous output shows that under the prefix path/ there exists one file named MyFile1.txt.
You can filter the output to a specific prefix by including it in the command. The following command lists
the objects in bucket-name/path (that is, objects in bucket-name filtered by the prefix path/).
$ aws s3 ls s3://bucket-name/path/
2018-12-06 18:59:32 3 MyFile2.txt
Delete a Bucket
To remove a bucket, use the s3 rb command.
$ aws s3 rb s3://bucket-name
By default, the bucket must be empty for the operation to succeed. To remove a non-empty bucket, you
need to include the --force option.
The following example deletes all objects and subfolders in the bucket and then removes the bucket.
Note
If you're using a versioned bucket that contains previously deleted—but retained—objects, this
command does not allow you to remove the bucket. You must first remove all of the content.
Manage Objects
The high-level aws s3 commands make it convenient to manage Amazon S3 objects. The object
commands include s3 cp, s3 ls, s3 mv, s3 rm, and s3 sync.
The cp, ls, mv, and rm commands work similarly to their Unix counterparts and enable you to work
seamlessly across your local directories and Amazon S3 buckets. The sync command synchronizes the
contents of a bucket and a directory, or two buckets.
Note
All high-level commands that involve uploading objects into an Amazon S3 bucket (s3 cp, s3
mv, and s3 sync) automatically perform a multipart upload when the object is large.
130
AWS Command Line Interface User Guide
High-Level (s3) Commands
Failed uploads can't be resumed when using these commands. If the multipart upload fails due
to a timeout or is manually canceled by pressing Ctrl+C, the AWS CLI cleans up any files created
and aborts the upload. This process can take several minutes.
If the process is interrupted by a kill command or system failure, the in-progress multipart
upload remains in Amazon S3 and must be cleaned up manually in the AWS Management
Console or with the s3api abort-multipart-upload command.
The cp, mv, and sync commands include a --grants option that you can use to grant permissions on
the object to specified users or groups. Set the --grants option to a list of permissions using following
syntax.
--grants Permission=Grantee_Type=Grantee_ID
[Permission=Grantee_Type=Grantee_ID ...]
• Permission – Specifies the granted permissions, and can be set to read, readacl, writeacl, or
full.
• Grantee_Type – Specifies how to identify the grantee, and can be set to uri, emailaddress, or id.
• Grantee_ID – Specifies the grantee based on Grantee_Type.
• uri – The group's URI. For more information, see Who Is a Grantee?
• emailaddress – The account's email address.
• id – The account's canonical ID.
The following example copies an object into a bucket. It grants read permissions on the object to
everyone and full permissions (read, readacl, and writeacl) to the account associated with
user@example.com.
You can also specify a nondefault storage class (REDUCED_REDUNDANCY or STANDARD_IA) for objects
that you upload to Amazon S3. To do this, use the --storage-class option.
The s3 sync command uses the following syntax. Possible source-target combinations are:
The following example synchronizes the contents of an Amazon S3 folder named path in my-bucket with
the current working directory. s3 sync updates any files that have a different size or modified time than
files with the same name at the destination. The output displays specific operations performed during
the sync. Notice that the operation recursively synchronizes the subdirectory MySubdirectory and its
contents with s3://my-bucket/path/MySubdirectory.
131
AWS Command Line Interface User Guide
High-Level (s3) Commands
Typically, s3 sync only copies missing or outdated files or objects between the source and target.
However, you can also supply the --delete option to remove files or objects from the target that are
not present in the source.
The following example, which extends the previous one, shows how this works.
You can use the --exclude and --include options to specify rules that filter the files or objects
to copy during the sync operation. By default, all items in a specified folder are included in the sync.
Therefore, --include is needed only when you have to specify exceptions to the --exclude option
(that is, --include effectively means "don't exclude"). The options apply in the order that's specified, as
shown in the following example.
The --exclude and --include options also filter files or objects to be deleted during an s3 sync
operation that includes the --delete option. In this case, the parameter string must specify files to
exclude from, or include for, deletion in the context of the target directory or bucket. The following
shows an example.
Assume local directory and s3://my-bucket/path currently in sync and each contains 3 files:
132
AWS Command Line Interface User Guide
API Level (s3api) Commands
MyFile1.txt
MyFile2.rtf
MyFile88.txt
'''
// Delete local .txt files
$ rm *.txt
// Sync with delete, excluding files that match a pattern. MyFile88.txt is deleted, while
remote MyFile1.txt is not.
$ aws s3 sync . s3://my-bucket/path --delete --exclude "my-bucket/path/MyFile?.txt"
delete: s3://my-bucket/path/MyFile88.txt
'''
// Delete MyFile2.rtf
$ aws s3 rm s3://my-bucket/path/MyFile2.rtf
The s3 sync command also accepts an --acl option, by which you may set the access permissions for
files copied to Amazon S3. The --acl option accepts private, public-read, and public-read-
write values.
As previously mentioned, the s3 command set includes cp, mv, ls, and rm, and they work in similar ways
to their Unix counterparts. The following are some examples.
// Delete s3://my-bucket/path/MyFile.txt
$ aws s3 rm s3://my-bucket/path/MyFile.txt
When you use the --recursive option on a directory or folder with cp, mv, or rm, the command
walks the directory tree, including all subdirectories. These commands also accept the --exclude, --
include, and --acl options as the sync command does.
133
AWS Command Line Interface User Guide
API Level (s3api) Commands
level s3 commands. These commands are the equivalent of the other AWS services that provide API-
level access to the services' functionality.
This topic provides examples that demonstrate how to use the lower-level commands that map to
the Amazon S3 APIs. In addition, you can find examples for each S3 API in the s3api section of the CLI
Reference Guide.
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
The following example shows how to grant full control to two AWS users (user1@example.com and
user2@example.com) and read permission to everyone. The identifier for "everyone" comes from a
special URI that you pass as a parameter.
For details about how to construct the ACLs, see PUT Bucket acl in the Amazon Simple Storage Service
API Reference. The s3api ACL commands in the CLI, such as put-bucket-acl, use the same shorthand
argument notation.
In the following example, the AWS user user@example.com is granted full control over the log files, and
all users have read access to them. Notice that the put-bucket-acl command is also required to grant
the Amazon S3 log delivery system (specified by a URI) the permissions needed to read and write the
logs to the bucket.
The file logging.json in the previous command has the following content.
{
"LoggingEnabled": {
"TargetBucket": "MyBucket",
"TargetPrefix": "MyBucketLogs/",
"TargetGrants": [
{
"Grantee": {
"Type": "AmazonCustomerByEmail",
"EmailAddress": "user@example.com"
},
"Permission": "FULL_CONTROL"
},
{
134
AWS Command Line Interface User Guide
Amazon SNS
"Grantee": {
"Type": "Group",
"URI": "http://acs.amazonaws.com/groups/global/AllUsers"
},
"Permission": "READ"
}
]
}
}
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
This topic shows examples of CLI commands that perform common tasks for Amazon SNS.
Topics
• Create a Topic (p. 135)
• Subscribe to a Topic (p. 135)
• Publish to a Topic (p. 136)
• Unsubscribe from a Topic (p. 136)
• Delete a Topic (p. 136)
Create a Topic
To create a topic, use the create-topic command and specify the name to assign to the topic.
Make a note of the response's TopicArn, which you use later to publish a message.
Subscribe to a Topic
To subscribe to a topic, use the subscribe command.
The following example specifies the email protocol and an email address for the notification-
endpoint.
135
AWS Command Line Interface User Guide
Publish to a Topic
AWS immediately sends a confirmation message by email to the address you specified in the subscribe
command. The email message has the following text.
After the recipient clicks the Confirm subscription link, the recipient's browser displays a notification
message with information similar to the following.
Subscription confirmed!
Publish to a Topic
To send a message to all subscribers of a topic, use the publish command.
The following example sends the message "Hello World!" to all subscribers of the specified topic.
In this example, AWS sends an email message with the text "Hello World!" to saanvi@example.com.
To verify that you successfully unsubscribed, use the list-subscriptions command to confirm that the ARN
no longer appears in the list.
Delete a Topic
To delete a topic, run the delete-topic command.
136
AWS Command Line Interface User Guide
Amazon SWF
To verify that AWS successfully deleted the topic, use the list-topics command to confirm that the topic
no longer appears in the list.
To list the AWS CLI commands for Amazon SWF, use the following command.
Before you run any commands, set your default credentials. For more information, see Configuring the
AWS CLI (p. 35).
The following topics show examples of CLI commands that perform common tasks for Amazon SWF.
Topics
• List of Amazon SWF Commands by Category (p. 137)
• Working with Amazon SWF Domains Using the AWS CLI (p. 140)
This section lists the reference topics for Amazon SWF commands in the AWS CLI, grouped by functional
category.
For an alphabetic list of commands, see the Amazon SWF section of the AWS CLI Command Reference, or
use the following command.
You can also get help for an individual command, by placing the help directive after the command
name. The following shows an example.
Topics
• Commands Related to Activities (p. 138)
• Commands Related to Deciders (p. 138)
• Commands Related to Workflow Executions (p. 138)
• Commands Related to Administration (p. 138)
137
AWS Command Line Interface User Guide
List of Amazon SWF Commands
• poll-for-activity-task
• respond-activity-task-completed
• respond-activity-task-failed
• respond-activity-task-canceled
• record-activity-task-heartbeat
• poll-for-decision-task
• respond-decision-task-completed
• request-cancel-workflow-execution
• start-workflow-execution
• signal-workflow-execution
• terminate-workflow-execution
Activity Management
• register-activity-type
• deprecate-activity-type
Workflow Management
• register-workflow-type
• deprecate-workflow-type
138
AWS Command Line Interface User Guide
List of Amazon SWF Commands
Domain Management
• register-domain
• deprecate-domain
For more information and examples of these domain management commands, see Working with
Amazon SWF Domains Using the AWS CLI (p. 140).
Visibility Commands
Although you can perform visibility actions from the Amazon SWF console, you can use the commands in
this section to build your own console or administrative tools.
Activity Visibility
• list-activity-types
• describe-activity-type
Workflow Visibility
• list-workflow-types
• describe-workflow-type
Domain Visibility
• list-domains
• describe-domain
For more information and examples of these domain visibility commands, see Working with Amazon
SWF Domains Using the AWS CLI (p. 140).
139
AWS Command Line Interface User Guide
Working with Amazon SWF Domains
Topics
• List Your Domains (p. 140)
• Get Information about a Domain (p. 140)
• Register a Domain (p. 141)
• Deprecate a Domain (p. 141)
Note
For an example of using DEPRECATED, see Deprecate a Domain (p. 141).
For more information, see list-domains in the AWS CLI Command Reference.
140
AWS Command Line Interface User Guide
Working with Amazon SWF Domains
For more information, see describe-domain in the AWS CLI Command Reference.
Register a Domain
To register new domains, use swf register-domain.
If you specify zero (0) for this value, the retention period is automatically set at the maximum duration.
Otherwise, workflow execution data isn't retained after the specified number of days have passed. The
following example shows how to register a new domain.
The command doesn't return any output, but you can use swf list-domains or swf describe-
domain to see the new domain, as shown in the following example.
For more information, see register-domain in the AWS CLI Command Reference.
Deprecate a Domain
To deprecate a domain (you can still see it, but cannot create new workflow executions or register types
on it), use swf deprecate-domain. It has a sole required parameter, --name, which takes the name of
the domain to deprecate.
As with register-domain, no output is returned. If you use list-domains to view the registered
domains, however, you will see that the domain no longer appears among them. You can also use --
registration-status DEPRECATED.
For more information, see deprecate-domain in the AWS CLI Command Reference.
141
AWS Command Line Interface User Guide
Data Protection
Security is a shared responsibility between AWS and you. The shared responsibility model describes this
as security of the cloud and security in the cloud:
• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in
the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors
regularly test and verify the effectiveness of our security as part of the AWS Compliance Programs. To
learn about the compliance programs that apply to AWS Command Line Interface, see AWS Services in
Scope by Compliance Program.
• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also
responsible for other factors including the sensitivity of your data, your company’s requirements, and
applicable laws and regulations.
This documentation helps you understand how to apply the shared responsibility model when using the
AWS Command Line Interface (AWS CLI). The following topics show you how to configure the AWS CLI
to meet your security and compliance objectives. You also learn how to use the AWS CLI to help you to
monitor and secure your AWS resources.
Topics
• Data Protection in the AWS CLI (p. 142)
• Identity and Access Management for the AWS CLI (p. 143)
• Compliance Validation for the AWS CLI (p. 144)
For data protection purposes, we recommend that you protect AWS account credentials and set up
individual user accounts with AWS Identity and Access Management (IAM), so that each user is given only
the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the
following ways:
142
AWS Command Line Interface User Guide
Data Encryption
We strongly recommend that you never put sensitive identifying information, such as your customers'
account numbers, into free-form fields such as a Name field. This includes when you work with the AWS
CLI or other AWS services using the console, API, or AWS SDKs. Any data that you enter into the AWS
CLI or other services might get picked up for inclusion in diagnostic logs. When you provide a URL to an
external server, don't include credentials information in the URL to validate your request to that server.
For more information about data protection, see the AWS Shared Responsibility Model and GDPR blog
post on the AWS Security Blog.
Data Encryption
A key feature of any secure service is that information is encrypted when it is not being actively used.
Encryption at Rest
The AWS CLI does not itself store any customer data other than the credentials it needs to interact with
the AWS services on the user's behalf.
If you use the AWS CLI to invoke an AWS service that transmits customer data to your local computer for
storage, then refer to the Security & Compliance chapter in that service's User Guide for information on
how that data is stored, protected, and encrypted.
Encryption in Transit
By default, all data transmitted from the client computer running the AWS CLI and AWS service
endpoints is encrypted by sending everything through a HTTPS/TLS connection.
You don't need to do anything to enable the use of HTTPS/TLS. It is always enabled unless you explicitly
disable it for an individual command by using the --no-verify-ssl command line option.
The only major difference is how you authenticate when using a standard IAM user and long-term
credentials. Although an IAM user requires a password to access an AWS service's console, that same IAM
user requires an access key pair to perform the same operations using the AWS CLI. All other short-term
credentials are used in the same way they are used with the console.
The credentials used by the AWS CLI are stored in plaintext files and are not encrypted.
• The $HOME/.aws/credentials file stores long-term credentials required to access your AWS
resources. These include your access key ID and secret access key.
• Short-term credentials, such as those for roles that you assume, or that are for AWS Single Sign-
On services, are also stored in the $HOME/.aws/cli/cache and $HOME/.aws/sso/cache folders,
respectively.
Mitigation of Risk
• We strongly recommend that you configure your file system permissions on the $HOME/.aws folder
and its child folders and files to restrict access to only authorized users.
143
AWS Command Line Interface User Guide
Compliance Validation
• Use roles with temporary credentials wherever possible to reduce the opportunity for damage if the
credentials are compromised. Use long-term credentials only to request and refresh short-term role
credentials.
For a list of AWS services in scope of specific compliance programs, see AWS Services in Scope by
Compliance Program. For general information, see AWS Compliance Programs.
You can download third-party audit reports using the AWS Artifact. For more information, see
Downloading Reports in AWS Artifact.
Your compliance responsibility when using AWS CLI is determined by the sensitivity of your data, your
company's compliance objectives, and applicable laws and regulations. AWS provides the following
resources to help with compliance:
• Security and Compliance Quick Start Guides – These deployment guides discuss architectural
considerations and provide steps for deploying security- and compliance-focused baseline
environments on AWS.
• Architecting for HIPAA Security and Compliance Whitepaper – This whitepaper describes how
companies can use AWS to create HIPAA-compliant applications.
• AWS Compliance Resources – This collection of workbooks and guides might apply to your industry
and location.
• Evaluating Resources with Rules in the AWS Config Developer Guide – The AWS Config service assesses
how well your resource configurations comply with internal practices, industry guidelines, and
regulations.
• AWS Security Hub – This AWS service provides a comprehensive view of your security state within AWS
that helps you check your compliance with security industry standards and best practices.
144
AWS Command Line Interface User Guide
General: Ensure you're running
a recent version of the AWS CLI.
How you update your version of the AWS CLI depends on how you originally installed it. For example, if
you installed the AWS CLI using pip, run pip install --upgrade, as described in Upgrading to the
Latest Version of the AWS CLI version 1 (p. 22).
If you used one of the bundled installers, you should remove the existing installation and download and
install the latest version of the bundled installer for your operating system.
You can send the output to a text file to capture it for later review or to send it to AWS support when
asked for it.
Here's an example of a command run with and without the --debug option.
When you include the --debug option, details include (among other things):
145
AWS Command Line Interface User Guide
General: Use the --debug option.
146
AWS Command Line Interface User Guide
General: Use the --debug option.
147
AWS Command Line Interface User Guide
General: Use the --debug option.
content-type:application/x-www-form-urlencoded; charset=utf-8
host:iam.amazonaws.com
x-amz-date:20190812T193618Z
content-type;host;x-amz-date
5f776d91EXAMPLE9b8cb5eb5d6d4a787a33ae41c8cd6eEXAMPLEca69080e1e1f
2019-08-12 12:36:18,344 - MainThread - botocore.auth - DEBUG - StringToSign:
AWS4-HMAC-SHA256
20190812T193618Z
20190812/us-east-1/iam/aws4_request
ab7e367eEXAMPLE2769f178ea509978cf8bfa054874b3EXAMPLE8d043fab6cc9
2019-08-12 12:36:18,344 - MainThread - botocore.auth - DEBUG - Signature:
d85a0EXAMPLEb40164f2f539cdc76d4f294fe822EXAMPLE18ad1ddf58a1a3ce7
2019-08-12 12:36:18,344 - MainThread - botocore.endpoint - DEBUG - Sending http request:
<AWSPreparedRequest stream_output=False, method=POST, url=https://iam.amazonaws.com/,
headers={'Content-Type': b'application/x-www-form-urlencoded; charset=utf-8',
'User-Agent': b'aws-cli/1.16.215 Python/3.7.3 Linux/4.14.133-113.105.amzn2.x86_64
botocore/1.12.205', 'X-Amz-Date': b'20190812T193618Z', 'Authorization': b'AWS4-HMAC-
SHA256 Credential=AKIA01234567890EXAMPLE-east-1/iam/aws4_request, SignedHeaders=content-
type;host;x-amz-date, Signature=d85a07692aceb401EXAMPLEa1b18ad1ddf58a1a3ce7EXAMPLE',
'Content-Length': '36'}>
2019-08-12 12:36:18,344 - MainThread - urllib3.util.retry - DEBUG - Converted retries
value: False -> Retry(total=False, connect=None, read=None, redirect=0, status=None)
2019-08-12 12:36:18,344 - MainThread - urllib3.connectionpool - DEBUG - Starting new HTTPS
connection (1): iam.amazonaws.com:443
2019-08-12 12:36:18,664 - MainThread - urllib3.connectionpool - DEBUG - https://
iam.amazonaws.com:443 "POST / HTTP/1.1" 200 570
2019-08-12 12:36:18,664 - MainThread - botocore.parsers - DEBUG - Response headers: {'x-
amzn-RequestId': '74c11606-bd38-11e9-9c82-559da0adb349', 'Content-Type': 'text/xml',
'Content-Length': '570', 'Date': 'Mon, 12 Aug 2019 19:36:18 GMT'}
2019-08-12 12:36:18,664 - MainThread - botocore.parsers - DEBUG - Response body:
b'<ListGroupsResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">\n
<ListGroupsResult>\n <IsTruncated>false</IsTruncated>\n <Groups>\n
<member>\n <Path>/</Path>\n <GroupName>MyTestGroup</GroupName>
\n <Arn>arn:aws:iam::123456789012:group/MyTestGroup</Arn>\n
<GroupId>AGPA1234567890EXAMPLE</GroupId>\n <CreateDate>2019-08-12T19:34:04Z</
CreateDate>\n </member>\n </Groups>\n </ListGroupsResult>\n <ResponseMetadata>\n
<RequestId>74c11606-bd38-11e9-9c82-559da0adb349</RequestId>\n </ResponseMetadata>\n</
ListGroupsResponse>\n'
2019-08-12 12:36:18,665 - MainThread - botocore.hooks - DEBUG - Event needs-
retry.iam.ListGroups: calling handler <botocore.retryhandler.RetryHandler object at
0x7fdf16e9a780>
2019-08-12 12:36:18,665 - MainThread - botocore.retryhandler - DEBUG - No retry needed.
2019-08-12 12:36:18,665 - MainThread - botocore.hooks - DEBUG - Event after-
call.iam.ListGroups: calling handler <function json_decode_policies at 0x7fdf189b1d90>
{
"Groups": [
{
148
AWS Command Line Interface User Guide
I get the error "command not found" when I run aws.
"Path": "/",
"GroupName": "MyTestGroup",
"GroupId": "AGPA123456789012EXAMPLE",
"Arn": "arn:aws:iam::123456789012:group/MyTestGroup",
"CreateDate": "2019-08-12T19:34:04Z"
}
]
}
If you use pip to install the AWS CLI, you might need to add the folder that contains the aws program to
your operating system's PATH environment variable, or change its mode to make it executable.
You might need to add the aws executable to your operating system's PATH environment variable.
Follow the steps in the appropriate procedure:
• Windows – Add the AWS CLI version 1 Executable to Your Command Line Path (p. 31)
• macOS – Add the AWS CLI version 1 Executable to Your macOS Command Line Path (p. 28)
• Linux – Add the AWS CLI version 1 Executable to Your Command Line Path (p. 23)
To add run permission for your user, run the following command, substituting ~/.local/bin/aws with
the path to the program on your computer.
$ chmod +x ~/.local/bin/aws
149
AWS Command Line Interface User Guide
I get an "invalid credentials" error.
Most commands call a single action with a name that matches the command name. However, custom
commands like aws s3 sync call multiple APIs. You can see which APIs a command calls by using the
--debug option.
If you are sure that the user or role has the proper permissions assigned by policy, ensure that your AWS
CLI command is using the credentials you expect. See the next section about credentials (p. 150) to
verify that the credentials the AWS CLI is using are the ones you expect.
For information about assigning permissions to IAM users and roles, see Overview of Access
Management: Permissions and Policies in the IAM User Guide.
The following example shows how to check the credentials used for the default profile.
The following example shows how to check the credentials of a named profile.
$ date
If your system clock is not correct within a few minutes, use ntpd to sync it.
150
AWS Command Line Interface User Guide
I get a "signature does not match" error.
On Windows, use the date and time options in the Control Panel to configure your system clock.
$ date
If your system clock is not correct within a few minutes, use ntpd to sync it.
On Windows, use the date and time options in the Control Panel to configure your system clock.
If you process your access keys and secret keys using other tools or scripts, such as tools that build the
credentials file on a new instance as part of its creation, those tools and scripts might have their own
handling of special characters that causes them to be transformed into something that AWS no longer
recognizes.
The easy solution is to regenerate the secret key to get one that does not include the special character.
151
AWS Command Line Interface User Guide
Passing binary parameters
Topics
• AWS CLI version 2 now passes binary parameters as base64-encoded strings by default (p. 152)
• AWS CLI version 2 improves Amazon S3 handling of file properties and tags when performing
multipart copies (p. 153)
• AWS CLI version 2 no longer automatically retrieves http:// or https:// URLs for
parameters (p. 153)
• AWS CLI version 2 uses a paging program for all output by default. (p. 154)
• AWS CLI version 2 now returns all timestamp output values in ISO 8601 format (p. 155)
• AWS CLI version 2 improves handling of AWS CloudFormation deployments that result in no
changes (p. 155)
• AWS CLI version 2 uses Amazon S3 keys more consistently (p. 155)
• AWS CLI version 2 uses the correct Amazon S3 regional endpoint for us-east-1 Region (p. 156)
• AWS CLI version 2 uses regional AWS STS endpoints by default (p. 156)
• AWS CLI version 2 replaces ecr get-login with ecr get-login-password (p. 156)
• AWS CLI version 2 support for plugins is changing (p. 156)
• AWS CLI version 2 no longer supports "hidden" aliases (p. 157)
By default, the AWS CLI version 2 now passes all binary input and binary output parameters as base64-
encoded strings. A parameter that requires binary input has its type specified as blob (binary large
object) in the documentation. To pass binary data as a file to a CLI parameter, the AWS CLI version 2
enables you to specify the file using the following prefixes:
• file:// – The AWS CLI treats the file content as base64-encoded text. For example: --some-param
file://~/my/path/file-with-base64.txt
• fileb:// – The AWS CLI treats the file content as unencoded binary. For example: --some-param
fileb://~/my/path/file-with-raw-binary.bin
152
AWS Command Line Interface User Guide
Improved Amazon S3 property and tag
handling during s3 copy operations
You can tell the AWS CLI version 2 to revert to the AWS CLI version 1 behavior by specifying the
following line in the ~/.aws/config file for a profile.
cli_binary_format=raw-in-base64-out
You can also revert the setting for an individual command, overriding the active profile setting, by
including the parameter --cli-binary-format raw-in-base64-out on the command-line.
If you revert to the AWS CLI version 1 behavior and specify a file for a binary parameter using either
file:// or fileb://, the AWS CLI treats the file content as unencoded raw binary.
By default, the AWS CLI version 2 commands in the s3 namespace that perform multipart copies now
transfer all tags and the following set of properties from the source to the destination copy: content-
type, content-language, content-encoding, content-disposition, cache-control,
expires, and metadata.
This can result in additional AWS API calls to the Amazon S3 endpoint that would not have been
made if you used AWS CLI version 1. These can include: HeadObject, GetObjectTagging, and
PutObjectTagging.
If you need to change this default behavior in AWS CLI version 2 commands, use the --copy-props
parameter to specify one of the following options:
• default – The default value. Specifies that the copy includes all tags attached to the source object
and the properties encompassed by the --metadata-directive parameter used for non-multipart
copies: content-type, content-language, content-encoding, content-disposition,
cache-control, expires, and metadata.
• metadata-directive – Specifies that the copy includes only the properties that are encompassed by the
--metadata-directive parameter used for non-multipart copies. It doesn't copy any tags.
• none – Specifies that the copy includes none of the properties from the source object.
153
AWS Command Line Interface User Guide
Output paging
For example, the following command no longer tries to retrieve the contents of the page found at
http://www.google.com and pass those contents as the parameter. Instead, it passes the literal text
string https://google.com as the parameter.
If you really do want to retrieve and use the contents of a web URL as a parameter, you can do the
following in version 2.
In the previous example, the -o parameter tells curl to save the file in the current folder with the same
name as the source file. The second command retrieves the content of that downloaded file and passes
the content as the value of --policy-document.
You can completely disable all use of an external paging program by setting the variable to an empty
string as shown in the following examples.
The following example shows setting it for the default profile, but you can add the setting to any
profile in your ~/.aws/config file.
[default]
cli_pager=
Linux or macOS:
$ export AWS_PAGER=""
Windows:
154
AWS Command Line Interface User Guide
All date/time values in ISO 8601 format
ISO 8601 formatted timestamps look like the following examples. The first example shows the time in
Coordinated Universal Time (UTC) by including a Z after the time. The date and the time are separated
by a T.
2019-10-31T22:21:41Z
To specify a different time zone, instead of the Z, specify a + or - and the number of hours the desired
time zone is ahead of or behind UTC, as a two-digit value. The following example shows the same time
as the previous example but adjusted to Pacific Standard time, which is eight hours behind UTC.
2019-10-31T14:21:41-08
To see timestamps in the format returned by the HTTP API response, add the following line to your
.aws/config profile.
cli_timestamp_format = wire
Because this is the common case scenario, the AWS CLI version 2 now defaults to returning a successful
exit code of 0 when there is no change caused by the deployment and the operation returns an empty
changeset.
In AWS CLI version 2, to revert to the original behavior, you must add the new flag --fail-on-empty-
changeset.
155
AWS Command Line Interface User Guide
Amazon S3 and us-east-1 Region
By default, AWS CLI version 1 sends AWS STS requests to the global AWS STS endpoint. You can control
this default behavior in V1 by using the sts_regional_endpoints (p. 45) setting.
The aws ecr get-login-password command reduces the risk of exposing your credentials in the
process list, shell history, or other log files. It also improves compatibility with the docker login
command, allowing better automation.
The aws ecr get-login-password command is available in the AWS CLI version 1.17.10 and later,
and the AWS CLI version 2. The older aws ecr get-login command is still available in the AWS CLI
version 1 for backward compatibility.
The aws ecr get-login-password command enables you to replace the following code that
retrieves a password.
To reduce the risk of exposing the password to the shell history or logs, use the following example
command instead. In this example, the password is piped directly to the docker login command,
where it is assigned to the password parameter by the --password-stdin option.
156
AWS Command Line Interface User Guide
No hidden aliases
that a particular plugin or even the CLI plugin interface will be supported in future versions of the
AWS CLI version 2. If you rely on plugins, be sure to lock to a particular version of the CLI and test the
functionality of your plugin when you do upgrade.
[plugins]
cli_legacy_plugin_path = <path-to-plugins>/python3.7/site-packages
<plugin-name> = <plugin-module>
In the [plugins] section, begin by defining the cli_legacy_plugin_path variable and setting
its value to the Python site packages path that your plugin module lives in. Then you can configure a
plugin by providing a name for the plugin (plugin-name), and the file name of the Python module,
(plugin-module), that contains the source code for your plugin. The CLI loads each plugin by importing
its plugin-module and calling its awscli_initialize function.
In the following table, the first column displays the service, command, and parameter that work in all
versions, including AWS CLI version 2. The second column displays the alias that no longer works in AWS
CLI version 2
storagegateway.describe-tape-archives.tape-arns tape-ar-ns
storagegateway.describe-vtl-devices.vtl-device-arns vtl-device-ar-ns
storagegateway.describe-cached-iscsi-volumes.volume-arns volume-ar-ns
storagegateway.describe-stored-iscsi-volumes.volume-arns volume-ar-ns
route53domains.view-billing.start-time start
deploy.create-deployment-group.ec2-tag-set ec-2-tag-set
deploy.list-application-revisions.s3-bucket s-3-bucket
deploy.list-application-revisions.s3-key-prefix s-3-key-prefix
deploy.update-deployment-group.ec2-tag-set ec-2-tag-set
iam.enable-mfa-device.authentication-code1 authentication-code-1
iam.enable-mfa-device.authentication-code2 authentication-code-2
iam.resync-mfa-device.authentication-code1 authentication-code-1
iam.resync-mfa-device.authentication-code2 authentication-code-2
157
AWS Command Line Interface User Guide
No hidden aliases
importexport.get-shipping-label.street1 street-1
importexport.get-shipping-label.street2 street-2
importexport.get-shipping-label.street3 street-3
lambda.publish-version.code-sha256 code-sha-256
lightsail.import-key-pair.public-key-base64 public-key-base-64
opsworks.register-volume.ec2-volume-id ec-2-volume-id
158
AWS Command Line Interface User Guide
AWS Command Line Interface The AWS CLI version 2 is February 10, 2020
(AWS CLI) Version 2 is officially generally available and is the
released recommended version for
customers to install.
macOS installer for AWS CLI The macOS installer for AWS CLI February 3, 2020
version 2 is now an Apple version 2 has been updated from
Package installer .pkg file. a .zip file with a shell script to
full macOS Installer package.
This simplifies installation and
makes it compatible with the
newest macOS releases.
Added content for AWS CLI By default, AWS CLI version January 13, 2020
version 2's improved default 2 now directs requests for
handling of S3 and STS regional the Amazon S3 and AWS
endpoints STS services to the currently
configured regional endpoint
instead of the global endpoint.
Updated to remove support for As of January 10th, 2020, AWS January 10, 2020
Python 2.6 and 3.3 from AWS CLI version 1 no longer supports
CLI version 1 using Python versions 2.6 or
3.3. You must update to a newer
version of Python to use AWS
CLI version 1.17 or later.
Added support for AWS Single AWS CLI version 2 adds support November 7, 2019
Sign-On to AWS CLI named for creating a named profile that
profiles can directly login to an AWS
SSO user account and get AWS
temporary credentials for use in
subsequent AWS CLI commands.
159
AWS Command Line Interface User Guide
Added information regarding By default, AWS CLI version 2 February 19, 20120
client-side pagers for AWS CLI uses the pager program less
version 2 for all client-side output.
160