Configuration basics

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

Note

AWS requires that all incoming requests are cryptographically signed. The AWS 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 AWS service, AWS rejects the request.

Topics

• Quick configuration with aws configure
• Access key ID and secret access key
  • Creating a key pair
  • Importing a key pair via .CSV file
• Region
• Output format
• Profiles
• Configuration settings and precedence

Quick configuration with aws configure

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

• Access key ID

• Secret access key

• AWS Region

• Output format

The AWS 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 AWS 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 AWS.

Topics

• Creating a key pair
• Importing a key pair via .CSV file

Creating a key pair

Users need programmatic access if they want to interact with AWS outside of the AWS Management Console. The way to grant programmatic access depends on the type of user that's accessing AWS:

• If you manage identities in IAM Identity Center, the AWS APIs require a profile, and the AWS Command Line Interface requires a profile or an environment variable.

• If you have IAM users, the AWS APIs and the AWS 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
Workforce identity (Users managed in IAM Identity Center)	Use short-term credentials to sign programmatic requests to the AWS CLI or AWS APIs (directly or by using the AWS SDKs).	Following the instructions for the interface that you want to use: For the AWS CLI, follow the instructions in Getting IAM role credentials for CLI access in the AWS IAM Identity Center (successor to AWS Single Sign-On) User Guide. For the AWS APIs, follow the instructions in SSO credentials in the AWS SDKs and Tools Reference Guide.
IAM	Use short-term credentials to sign programmatic requests to the AWS CLI or AWS APIs (directly or by using the AWS SDKs).	Following the instructions in Using temporary credentials with AWS resources in the IAM User Guide.
IAM	Use long-term credentials to sign programmatic requests to the AWS CLI or AWS APIs (directly or by using the AWS 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 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.

• 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 AWS 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 AWS CLI.

Configuration settings and precedence

The AWS CLI uses credentials and configuration settings located in multiple places, such as the system or user environment variables, local AWS configuration files, or explicitly declared on the command line as a parameter. Certain locations take precedence over others. The AWS 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.