Configuration basics - Amazon Command Line Interface
Quick configuration with aws configureAccess key ID and secret access keyRegionOutput formatProfilesConfiguration settings and precedence
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Configuration basics

This section explains how to quickly configure basic settings using the config and credentials files that the Amazon Command Line Interface (Amazon CLI) uses to interact with Amazon. These include your security credentials, the default output format, and the default Amazon Region. To instead see configuration instructions for Amazon IAM Identity Center (successor to Amazon Single Sign-On), see Configuring the Amazon CLI to use Amazon IAM Identity Center (successor to Amazon Single Sign-On).

Note

Amazon requires that all incoming requests are cryptographically signed. The Amazon CLI does this for you. The "signature" includes a date/time stamp. Therefore, you must ensure that your computer's date and time are set correctly. If you don't, and the date/time in the signature is too far off of the date/time recognized by the Amazon service, Amazon rejects the request.

Quick configuration with aws configure

For general use, the aws configure command is the fastest way to set up your Amazon CLI installation. When you enter this command, the Amazon CLI prompts you for four pieces of information:

The Amazon CLI stores this information in a profile (a collection of settings) named default in the credentials file. By default, the information in this profile is used when you run an Amazon CLI command that doesn't explicitly specify a profile to use. For more information on the credentials file, see Configuration and credential file settings

The following example shows sample values. Replace them with your own values as described in the following sections.

$ 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

Access key ID and secret access key

Access keys use an access key ID and secret access key that you use to sign programmatic requests to Amazon.

Creating a key pair

Users need programmatic access if they want to interact with Amazon outside of the Amazon Web Services Management Console. The Amazon APIs and the Amazon Command Line Interface require access keys. Whenever possible, create temporary credentials that consist of an access key ID, a secret access key, and a security token that indicates when the credentials expire.

To grant users programmatic access, choose one of the following options.

Which user needs programmatic access? To By
IAM Use short-term credentials to sign programmatic requests to the Amazon CLI or Amazon APIs (directly or by using the Amazon SDKs). Following the instructions in Using temporary credentials with Amazon resources in the IAM User Guide.
IAM Use long-term credentials to sign programmatic requests to the Amazon CLI or Amazon APIs (directly or by using the Amazon SDKs).

(Not recommended)

 Following the instructions in Managing access keys for IAM users in the IAM User Guide.

Importing a key pair via .CSV file

Instead of using aws configure to enter in a key pair, you can import the .csv file you downloaded after you created your key pair.

The .csv file must contain the following headers.

  • User Name - This column must be added to your .csv. This is used to create the profile name when you import.

  • Access key ID

  • Secret access key

Note

During initial key pair creation, once you close the Download .csv file dialog box, you cannot access your secret access key after you close the dialog box. If you need a .csv file, you'll need to create one yourself with the required headers and your stored key pair information. If you do not have access to your key pair information, you need to create a new key pair.

To import the .csv file, use the aws configure import command with the --csv option as follows:

$ aws configure import --csv file://credentials.csv

For more information, see aws_configure_import.

Region

The Default region name identifies the Amazon 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 Amazon Region when using the Amazon 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 Amazon CLI are the same names that you see in Amazon Web Services 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.

  • json – The output is formatted as a JSON string.

  • yaml – The output is formatted as a YAML string.

  • yaml-stream – The output is streamed and formatted as a YAML string. Streaming allows for faster handling of large data types.

  • text – 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 – 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.

Profiles

A collection of settings is called a profile. By default, the Amazon CLI uses the default profile. You can create and use additional named profiles with varying credentials and settings by specifying the --profile option and assigning a name.

The following example creates a profile named produser.

$ aws configure --profile produser
AWS Access Key ID [None]: AKIAI44QH8DHBEXAMPLE
AWS Secret Access Key [None]: je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: text

You can then specify a --profile profilename and use the credentials and settings stored under that name.

$ aws s3 ls --profile produser

To update these settings, 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.

For more information on named profiles, see Named profiles for the Amazon CLI.

Configuration settings and precedence

The Amazon CLI uses credentials and configuration settings located in multiple places, such as the system or user environment variables, local Amazon configuration files, or explicitly declared on the command line as a parameter. Certain locations take precedence over others. The Amazon CLI credentials and configuration settings take precedence in the following order:

  1. Command line options – Overrides settings in any other location. You can specify --region, --output, and --profile as parameters on the command line.

  2. Environment variables – You can store values in your system's environment variables.

  3. CLI credentials file – The credentials and config file are updated when you run the command aws configure. The credentials file is located at ~/.aws/credentials on Linux or macOS, or at C:\Users\USERNAME\.aws\credentials on Windows. This file can contain the credential details for the default profile and any named profiles.

  4. CLI configuration file – The credentials and config file are updated when you run the command aws configure. The config 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. Amazon EC2 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.