/ Command-line Tools

aws-cli - A universal command-line interface for Amazon Web Services

aws-cli - A universal command-line interface for Amazon Web Services

aws-cli

This package provides a unified command line interface to Amazon Web Services.

The aws-cli package works on Python versions:

  • 2.6.5 and greater
  • 2.7.x and greater
  • 3.3.x and greater
  • 3.4.x and greater
  • 3.5.x and greater
  • 3.6.x and greater

.. attention::
We recommend that all customers regularly monitor the
Amazon Web Services Security Bulletins website_ for any important security bulletins related to aws-cli.


Installation

The easiest way to install aws-cli is to use pip_::

$ pip install awscli

or, if you are not installing in a virtualenv::

$ sudo pip install awscli

If you have the aws-cli installed and want to upgrade to the latest version
you can run::

$ pip install --upgrade awscli

.. note::

On OS X, if you see an error regarding the version of six that came with
distutils in El Capitan, use the ``--ignore-installed`` option::

    $ sudo pip install awscli --ignore-installed six

This will install the aws-cli package as well as all dependencies. You can
also just download the tarball_. Once you have the
awscli directory structure on your workstation, you can just run::

$ cd <path_to_awscli>
$ python setup.py install

If you want to run the develop branch of the CLI, see the
"CLI Dev Version" section below.


Command Completion

The aws-cli package includes a very useful command completion feature.
This feature is not automatically installed so you need to configure it manually.
To enable tab completion for bash either use the built-in command complete::

$ complete -C aws_completer aws

Or add bin/aws_bash_completer file under /etc/bash_completion.d,
/usr/local/etc/bash_completion.d or any other bash_completion.d location.

For tcsh::

$ complete aws 'p/*/`aws_completer`/'

You should add this to your startup scripts to enable it for future sessions.

For zsh please refer to bin/aws_zsh_completer.sh. Source that file, e.g.
from your ~/.zshrc, and make sure you run compinit before::

$ source bin/aws_zsh_completer.sh

For now the bash compatibility auto completion (bashcompinit) is used.
For further details please refer to the top of bin/aws_zsh_completer.sh.


Getting Started

Before using aws-cli, you need to tell it about your AWS credentials. You
can do this in several ways:

  • Environment variables
  • Shared credentials file
  • Config file
  • IAM Role

The quickest way to get started is to run the aws configure command::

$ aws configure
AWS Access Key ID: foo
AWS Secret Access Key: bar
Default region name [us-west-2]: us-west-2
Default output format [None]: json

To use environment variables, do the following::

$ export AWS_ACCESS_KEY_ID=<access_key>
$ export AWS_SECRET_ACCESS_KEY=<secret_key>

To use the shared credentials file, create an INI formatted file like this::

[default]
aws_access_key_id=foo
aws_secret_access_key=bar

[testing]
aws_access_key_id=foo
aws_secret_access_key=bar

and place it in ~/.aws/credentials (or in
%UserProfile%\.aws/credentials on Windows). If you wish to place the
shared credentials file in a different location than the one specified above,
you need to tell aws-cli where to find it. Do this by setting
the appropriate environment variable::

$ export AWS_SHARED_CREDENTIALS_FILE=/path/to/shared_credentials_file

To use a config file, create a configuration file like this::

[default]
aws_access_key_id=<default access key>
aws_secret_access_key=<default secret key>
# Optional, to define default region for this profile.
region=us-west-1

[profile testing]
aws_access_key_id=<testing access key>
aws_secret_access_key=<testing secret key>
region=us-west-2

and place it in ~/.aws/config (or in %UserProfile%\.aws\config on Windows). If you wish to place the config file in a different location than the one
specified above, you need to tell aws-cli where to find it. Do this by setting
the appropriate environment variable::

$ export AWS_CONFIG_FILE=/path/to/config_file

As you can see, you can have multiple profiles defined in both the shared
credentials file and the configuration file. You can then specify which
profile to use by using the --profile option. If no profile is specified
the default profile is used.

In the config file, except for the default profile, you
must prefix each config section of a profile group with profile.
For example, if you have a profile named "testing" the section header would
be [profile testing].

The final option for credentials is highly recommended if you are
using aws-cli on an EC2 instance. IAM Roles are
a great way to have credentials installed automatically on your
instance. If you are using IAM Roles, aws-cli will find them and use
them automatically.


Other Configurable Variables

In addition to credentials, a number of other variables can be
configured either with environment variables, configuration file
entries or both. The following table documents these.

============================= =========== ============================= ================================= ==================================
Variable Option Config Entry Environment Variable Description
============================= =========== ============================= ================================= ==================================
profile --profile profile AWS_PROFILE Default profile name


region --region region AWS_DEFAULT_REGION Default AWS Region


config_file AWS_CONFIG_FILE Alternate location of config


credentials_file AWS_SHARED_CREDENTIALS_FILE Alternate location of credentials


output --output output AWS_DEFAULT_OUTPUT Default output style


ca_bundle --ca-bundle ca_bundle AWS_CA_BUNDLE CA Certificate Bundle


access_key aws_access_key_id AWS_ACCESS_KEY_ID AWS Access Key


secret_key aws_secret_access_key AWS_SECRET_ACCESS_KEY AWS Secret Key


token aws_session_token AWS_SESSION_TOKEN AWS Token (temp credentials)


cli_timestamp_format cli_timestamp_format Output format of timestamps


metadata_service_timeout metadata_service_timeout AWS_METADATA_SERVICE_TIMEOUT EC2 metadata timeout


metadata_service_num_attempts metadata_service_num_attempts AWS_METADATA_SERVICE_NUM_ATTEMPTS EC2 metadata retry count


parameter_validation parameter_validation Toggles local parameter validation
============================= =========== ============================= ================================= ==================================

^^^^^^^^
Examples
^^^^^^^^

If you get tired of specifying a --region option on the command line
all of the time, you can specify a default region to use whenever no
explicit --region option is included using the region variable.
To specify this using an environment variable::

$ export AWS_DEFAULT_REGION=us-west-2

To include it in your config file::

[default]
aws_access_key_id=<default access key>
aws_secret_access_key=<default secret key>
region=us-west-1

Similarly, the profile variable can be used to specify which profile to use
if one is not explicitly specified on the command line via the
--profile option. To set this via environment variable::

$ export AWS_PROFILE=testing

The profile variable can not be specified in the configuration file
since it would have to be associated with a profile and would defeat the
purpose.

GitHub