aws-cli
=======

.. image:: https://github.com/aws/aws-cli/actions/workflows/run-tests.yml/badge.svg
   :target: https://github.com/aws/aws-cli/actions/workflows/run-tests.yml
   :alt: Build Status

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

Jump to:

-  `Getting Started <#getting-started>`__
-  `Getting Help <#getting-help>`__
-  `More Resources <#more-resources>`__

Getting Started
---------------

This README is for the AWS CLI version 1. If you are looking for
information about the AWS CLI version 2, please visit the `v2
branch <https://github.com/aws/aws-cli/tree/v2>`__.

Requirements
~~~~~~~~~~~~

The aws-cli package works on Python versions:

-  3.8.x and greater
-  3.9.x and greater
-  3.10.x and greater
-  3.11.x and greater
-  3.12.x and greater

Notices
~~~~~~~

On 2022-05-30, support for Python 3.6 was ended. This follows the
Python Software Foundation `end of support <https://www.python.org/dev/peps/pep-0494/#lifespan>`__
for the runtime which occurred on 2021-12-23.

On 2023-12-13, support for Python 3.7 was ended. This follows the
Python Software Foundation `end of support <https://www.python.org/dev/peps/pep-0537/#lifespan>`__
for the runtime which occurred on 2023-06-27.
For more information, see this `blog post <https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/>`__.

*Attention!*

*We recommend that all customers regularly monitor the* `Amazon Web
Services Security Bulletins
website <https://aws.amazon.com/security/security-bulletins>`__ *for
any important security bulletins related to aws-cli.*

Maintenance and Support for CLI Major Versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The AWS CLI version 1 was made generally available on 09/02/2013 and is currently in the full support phase of the availability life cycle.

For information about maintenance and support for SDK major versions and their underlying dependencies, see the `Maintenance Policy <https://docs.aws.amazon.com/credref/latest/refdocs/maint-policy.html>`__ section in the *AWS SDKs and Tools Shared Configuration and Credentials Reference Guide*.

Installation
~~~~~~~~~~~~

Installation of the AWS CLI and its dependencies use a range of packaging
features provided by ``pip`` and ``setuptools``. To ensure smooth installation,
it's recommended to use:

- ``pip``: 9.0.2 or greater
- ``setuptools``: 36.2.0 or greater

The safest way to install the AWS CLI is to use
`pip <https://pip.pypa.io/en/stable/>`__ in a ``virtualenv``:

::

   $ python -m pip install awscli

or, if you are not installing in a ``virtualenv``, to install globally:

::

   $ sudo python -m pip install awscli

or for your user:

::

   $ python -m pip install --user awscli

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

::

   $ python -m pip install --upgrade awscli

This will install the aws-cli package as well as all dependencies.

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

::

   $ sudo python -m pip install awscli --ignore-installed six

On Linux and Mac OS, the AWS CLI can be installed using a `bundled
installer <https://docs.aws.amazon.com/cli/latest/userguide/install-linux.html#install-linux-bundled>`__.
The AWS CLI can also be installed on Windows via an `MSI
Installer <https://docs.aws.amazon.com/cli/latest/userguide/install-windows.html#msi-on-windows>`__.

If you want to run the ``develop`` branch of the AWS CLI, see the
`Development Version <CONTRIBUTING.md#cli-development-version>`__ section of
the contributing guide.

See the
`installation <https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html>`__
section of the AWS CLI User Guide for more information.

Configuration
~~~~~~~~~~~~~

Before using the AWS CLI, you need to configure your AWS credentials.
You can do this in several ways:

-  Configuration command
-  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: MYACCESSKEY
   AWS Secret Access Key: MYSECRETKEY
   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=MYACCESSKEY
   aws_secret_access_key=MYSECRETKEY

   [testing]
   aws_access_key_id=MYACCESSKEY
   aws_secret_access_key=MYSECRETKEY

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 an INI formatted 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 the 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
the AWS CLI on an EC2 instance. `IAM
Roles <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html>`__
are a great way to have credentials installed automatically on your
instance. If you are using IAM Roles, the AWS CLI will find and use them
automatically.

In addition to credentials, a number of other variables can be
configured either with environment variables, configuration file
entries, or both. See the `AWS Tools and SDKs Shared Configuration and
Credentials Reference
Guide <https://docs.aws.amazon.com/credref/latest/refdocs/overview.html>`__
for more information.

For more information about configuration options, please refer to the
`AWS CLI Configuration Variables
topic <http://docs.aws.amazon.com/cli/latest/topic/config-vars.html#cli-aws-help-config-vars>`__.
You can access this topic from the AWS CLI as well by running
``aws help config-vars``.

Basic Commands
~~~~~~~~~~~~~~

An AWS CLI command has the following structure:

::

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

For example, to list S3 buckets, the command would be:

::

   $ aws s3 ls

To view help documentation, use one of the following:

::

   $ aws help
   $ aws <command> help
   $ aws <command> <subcommand> help

To get the version of the AWS CLI:

::

   $ aws --version

To turn on debugging output:

::

   $ aws --debug <command> <subcommand>

You can read more information on the `Using the AWS
CLI <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-using.html>`__
chapter of the AWS CLI User Guide.

Command Completion
~~~~~~~~~~~~~~~~~~

The aws-cli package includes a command completion feature for Unix-like
systems. This feature is not automatically installed so you need to
configure it manually. To learn more, read the `AWS CLI Command
completion
topic <https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-completion.html>`__.

Getting Help
------------

The best way to interact with our team is through GitHub. You can `open
an issue <https://github.com/aws/aws-cli/issues/new/choose>`__ and
choose from one of our templates for guidance, bug reports, or feature
requests.

You may find help from the community on `Stack
Overflow <https://stackoverflow.com/>`__ with the tag
`aws-cli <https://stackoverflow.com/questions/tagged/aws-cli>`__ or on
the `AWS Discussion Forum for
CLI <https://forums.aws.amazon.com/forum.jspa?forumID=150>`__. If you
have a support plan with `AWS Support
<https://aws.amazon.com/premiumsupport>`__, you can also create
a new support case.

Please check for open similar
`issues <https://github.com/aws/aws-cli/issues/>`__ before opening
another one.

The AWS CLI implements AWS service APIs. For general issues regarding
the services or their limitations, you may find the `Amazon Web Services
Discussion Forums <https://forums.aws.amazon.com/>`__ helpful.

More Resources
--------------

-  `Changelog <https://github.com/aws/aws-cli/blob/develop/CHANGELOG.rst>`__
-  `AWS CLI
   Documentation <https://docs.aws.amazon.com/cli/index.html>`__
-  `AWS CLI User
   Guide <https://docs.aws.amazon.com/cli/latest/userguide/>`__
-  `AWS CLI Command
   Reference <https://docs.aws.amazon.com/cli/latest/reference/>`__
-  `Amazon Web Services Discussion
   Forums <https://forums.aws.amazon.com/>`__
-  `AWS Support <https://console.aws.amazon.com/support/home#/>`__

.. |Build Status| image:: https://travis-ci.org/aws/aws-cli.svg?branch=develop
   :target: https://travis-ci.org/aws/aws-cli
.. |Gitter| image:: https://badges.gitter.im/aws/aws-cli.svg
   :target: https://gitter.im/aws/aws-cli
