1aws-cli 2======= 3 4.. image:: https://github.com/aws/aws-cli/actions/workflows/run-tests.yml/badge.svg 5 :target: https://github.com/aws/aws-cli/actions/workflows/run-tests.yml 6 :alt: Build Status 7 8This package provides a unified command line interface to Amazon Web 9Services. 10 11Jump to: 12 13- `Getting Started <#getting-started>`__ 14- `Getting Help <#getting-help>`__ 15- `More Resources <#more-resources>`__ 16 17Getting Started 18--------------- 19 20This README is for the AWS CLI version 1. If you are looking for 21information about the AWS CLI version 2, please visit the `v2 22branch <https://github.com/aws/aws-cli/tree/v2>`__. 23 24Requirements 25~~~~~~~~~~~~ 26 27The aws-cli package works on Python versions: 28 29- 3.6.x and greater 30- 3.7.x and greater 31- 3.8.x and greater 32- 3.9.x and greater 33- 3.10.x and greater 34 35On 01/15/2021 deprecation for Python 2.7 was announced and support was dropped 36on 07/15/2021. To avoid disruption, customers using the AWS CLI on Python 2.7 may 37need to upgrade their version of Python or pin the version of the AWS CLI. For 38more information, see this `blog post <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`__. 39 40On 10/29/2020 support for Python 3.4 and Python 3.5 was deprecated and 41support was dropped on 02/01/2021. Customers using the AWS CLI on 42Python 3.4 or 3.5 will need to upgrade their version of Python to 43continue receiving feature and security updates. For more information, 44see this `blog 45post <https://aws.amazon.com/blogs/developer/announcing-the-end-of-support-for-python-3-4-and-3-5-in-the-aws-sdk-for-python-and-aws-cli-v1/>`__. 46 47*Attention!* 48 49*We recommend that all customers regularly monitor the* `Amazon Web 50Services Security Bulletins 51website <https://aws.amazon.com/security/security-bulletins>`__ *for 52any important security bulletins related to aws-cli.* 53 54Maintenance and Support for CLI Major Versions 55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 57The 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. 58 59For 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*. 60 61Installation 62~~~~~~~~~~~~ 63 64Installation of the AWS CLI and its dependencies use a range of packaging 65features provided by ``pip`` and ``setuptools``. To ensure smooth installation, 66it's recommended to use: 67 68- ``pip``: 9.0.2 or greater 69- ``setuptools``: 36.2.0 or greater 70 71The safest way to install the AWS CLI is to use 72`pip <https://pip.pypa.io/en/stable/>`__ in a ``virtualenv``: 73 74:: 75 76 $ python -m pip install awscli 77 78or, if you are not installing in a ``virtualenv``, to install globally: 79 80:: 81 82 $ sudo python -m pip install awscli 83 84or for your user: 85 86:: 87 88 $ python -m pip install --user awscli 89 90If you have the aws-cli package installed and want to upgrade to the 91latest version you can run: 92 93:: 94 95 $ python -m pip install --upgrade awscli 96 97This will install the aws-cli package as well as all dependencies. 98 99.. note:: 100 On macOS, if you see an error regarding the version of ``six`` that 101 came with ``distutils`` in El Capitan, use the ``--ignore-installed`` 102 option: 103 104:: 105 106 $ sudo python -m pip install awscli --ignore-installed six 107 108On Linux and Mac OS, the AWS CLI can be installed using a `bundled 109installer <https://docs.aws.amazon.com/cli/latest/userguide/install-linux.html#install-linux-bundled>`__. 110The AWS CLI can also be installed on Windows via an `MSI 111Installer <https://docs.aws.amazon.com/cli/latest/userguide/install-windows.html#msi-on-windows>`__. 112 113If you want to run the ``develop`` branch of the AWS CLI, see the 114`Development Version <CONTRIBUTING.md#cli-development-version>`__ section of 115the contributing guide. 116 117See the 118`installation <https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html>`__ 119section of the AWS CLI User Guide for more information. 120 121Configuration 122~~~~~~~~~~~~~ 123 124Before using the AWS CLI, you need to configure your AWS credentials. 125You can do this in several ways: 126 127- Configuration command 128- Environment variables 129- Shared credentials file 130- Config file 131- IAM Role 132 133The quickest way to get started is to run the ``aws configure`` command: 134 135:: 136 137 $ aws configure 138 AWS Access Key ID: MYACCESSKEY 139 AWS Secret Access Key: MYSECRETKEY 140 Default region name [us-west-2]: us-west-2 141 Default output format [None]: json 142 143To use environment variables, do the following: 144 145:: 146 147 $ export AWS_ACCESS_KEY_ID=<access_key> 148 $ export AWS_SECRET_ACCESS_KEY=<secret_key> 149 150To use the shared credentials file, create an INI formatted file like 151this: 152 153:: 154 155 [default] 156 aws_access_key_id=MYACCESSKEY 157 aws_secret_access_key=MYSECRETKEY 158 159 [testing] 160 aws_access_key_id=MYACCESKEY 161 aws_secret_access_key=MYSECRETKEY 162 163and place it in ``~/.aws/credentials`` (or in 164``%UserProfile%\.aws/credentials`` on Windows). If you wish to place the 165shared credentials file in a different location than the one specified 166above, you need to tell aws-cli where to find it. Do this by setting the 167appropriate environment variable: 168 169:: 170 171 $ export AWS_SHARED_CREDENTIALS_FILE=/path/to/shared_credentials_file 172 173To use a config file, create an INI formatted file like this: 174 175:: 176 177 [default] 178 aws_access_key_id=<default access key> 179 aws_secret_access_key=<default secret key> 180 # Optional, to define default region for this profile. 181 region=us-west-1 182 183 [profile testing] 184 aws_access_key_id=<testing access key> 185 aws_secret_access_key=<testing secret key> 186 region=us-west-2 187 188and place it in ``~/.aws/config`` (or in ``%UserProfile%\.aws\config`` 189on Windows). If you wish to place the config file in a different 190location than the one specified above, you need to tell the AWS CLI 191where to find it. Do this by setting the appropriate environment 192variable: 193 194:: 195 196 $ export AWS_CONFIG_FILE=/path/to/config_file 197 198As you can see, you can have multiple ``profiles`` defined in both the 199shared credentials file and the configuration file. You can then specify 200which profile to use by using the ``--profile`` option. If no profile is 201specified the ``default`` profile is used. 202 203In the config file, except for the default profile, you **must** prefix 204each config section of a profile group with ``profile``. For example, if 205you have a profile named "testing" the section header would be 206``[profile testing]``. 207 208The final option for credentials is highly recommended if you are using 209the AWS CLI on an EC2 instance. `IAM 210Roles <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html>`__ 211are a great way to have credentials installed automatically on your 212instance. If you are using IAM Roles, the AWS CLI will find and use them 213automatically. 214 215In addition to credentials, a number of other variables can be 216configured either with environment variables, configuration file 217entries, or both. See the `AWS Tools and SDKs Shared Configuration and 218Credentials Reference 219Guide <https://docs.aws.amazon.com/credref/latest/refdocs/overview.html>`__ 220for more information. 221 222For more information about configuration options, please refer to the 223`AWS CLI Configuration Variables 224topic <http://docs.aws.amazon.com/cli/latest/topic/config-vars.html#cli-aws-help-config-vars>`__. 225You can access this topic from the AWS CLI as well by running 226``aws help config-vars``. 227 228Basic Commands 229~~~~~~~~~~~~~~ 230 231An AWS CLI command has the following structure: 232 233:: 234 235 $ aws <command> <subcommand> [options and parameters] 236 237For example, to list S3 buckets, the command would be: 238 239:: 240 241 $ aws s3 ls 242 243To view help documentation, use one of the following: 244 245:: 246 247 $ aws help 248 $ aws <command> help 249 $ aws <command> <subcommand> help 250 251To get the version of the AWS CLI: 252 253:: 254 255 $ aws --version 256 257To turn on debugging output: 258 259:: 260 261 $ aws --debug <command> <subcommand> 262 263You can read more information on the `Using the AWS 264CLI <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-using.html>`__ 265chapter of the AWS CLI User Guide. 266 267Command Completion 268~~~~~~~~~~~~~~~~~~ 269 270The aws-cli package includes a command completion feature for Unix-like 271systems. This feature is not automatically installed so you need to 272configure it manually. To learn more, read the `AWS CLI Command 273completion 274topic <https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-completion.html>`__. 275 276Getting Help 277------------ 278 279The best way to interact with our team is through GitHub. You can `open 280an issue <https://github.com/aws/aws-cli/issues/new/choose>`__ and 281choose from one of our templates for guidance, bug reports, or feature 282requests. 283 284You may find help from the community on `Stack 285Overflow <https://stackoverflow.com/>`__ with the tag 286`aws-cli <https://stackoverflow.com/questions/tagged/aws-cli>`__ or on 287the `AWS Discussion Forum for 288CLI <https://forums.aws.amazon.com/forum.jspa?forumID=150>`__. If you 289have a support plan with `AWS Support 290<https://aws.amazon.com/premiumsupport>`__, you can also create 291a new support case. 292 293Please check for open similar 294`issues <https://github.com/aws/aws-cli/issues/>`__ before opening 295another one. 296 297The AWS CLI implements AWS service APIs. For general issues regarding 298the services or their limitations, you may find the `Amazon Web Services 299Discussion Forums <https://forums.aws.amazon.com/>`__ helpful. 300 301More Resources 302-------------- 303 304- `Changelog <https://github.com/aws/aws-cli/blob/develop/CHANGELOG.rst>`__ 305- `AWS CLI 306 Documentation <https://docs.aws.amazon.com/cli/index.html>`__ 307- `AWS CLI User 308 Guide <https://docs.aws.amazon.com/cli/latest/userguide/>`__ 309- `AWS CLI Command 310 Reference <https://docs.aws.amazon.com/cli/latest/reference/>`__ 311- `Amazon Web Services Discussion 312 Forums <https://forums.aws.amazon.com/>`__ 313- `AWS Support <https://console.aws.amazon.com/support/home#/>`__ 314 315.. |Build Status| image:: https://travis-ci.org/aws/aws-cli.svg?branch=develop 316 :target: https://travis-ci.org/aws/aws-cli 317.. |Gitter| image:: https://badges.gitter.im/aws/aws-cli.svg 318 :target: https://gitter.im/aws/aws-cli 319