The Wayback Machine - https://web.archive.org/web/20161011232512/http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html
Menu
Sign In to the Console
AWS Command Line Interface
User Guide

Configuring the AWS Command Line Interface

This section explains how to configure settings that the AWS Command Line Interface uses when interacting with AWS, such as your security credentials and the default region.

Note

The AWS CLI signs requests on your behalf, and includes a date in the signature. Ensure that your computer's date and time are set correctly; if not, the date in the signature may not match the date of the request, and AWS rejects the request.

Sections

Using the Examples in this Guide

The examples in this guide are formatted with the following conventions:

  • Prompt – The command prompt is displayed as a dollar sign ('$'). Do not include the prompt when you type commands.

  • Directory – When commands must be executed from a specific directory, the directory name is shown before the prompt symbol.

  • User Input – Command text that you should enter at the command line is formatted as user input.

  • Replaceable Text – Variable text, including names of resources that you choose, or IDs generated by AWS services that you must include in commands, is formatted as replaceable text. In multiple line commands or commands where specific keyboard input is required, keyboard commands can also be shown as replaceable text.

  • Output – Output returned by AWS services is shown beneath user input without any special formatting.

For example, the following command includes user input, replaceable text, and output:

$ 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]: ENTER

To use this example, type aws configure at the command line and press Enter. aws configure is the command. This command is interactive, so the AWS CLI outputs lines of texts, prompting you to enter additional information. Enter each of your access keys in turn and press Enter. Then, enter a region name in the format shown, press Enter, and press Enter a final time to skip the output format setting. The final Enter command is shown as replaceable text because there is no user input for that line. Otherwise, it would be implied.

The following example shows a simple non-interactive command with output from the service in JSON format:

$ aws ec2 create-security-group --group-name my-sg --description "My security group"
{
    "GroupId": "sg-903004f8"
}

To use this example, enter the full text of the command (the highlighted text after the prompt) and press Enter. The name of the security group, my-sg is replaceable. In this case, you can use the group name as shown, but you will probably want to use a more descriptive name.

Note

Arguments that must be replaced (such as AWS Access Key ID), and those that should be replaced (such as group name), are both shown as replaceable text. If an argument must be replaced, it will be noted in the text describing the example.

The JSON document, including the curly braces, is output. If you configure your CLI to output in text or table format, the output will be formatted differently. JSON is the default output format.

Quick Configuration

For general use, the aws configure command is the fastest way to set up your AWS CLI installation. 

$ 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

The AWS CLI will prompt you for four pieces of information. AWS Access Key ID and AWS Secret Access Key are your account credentials. If you don't have keys, see the Getting Set Up section earlier in this guide.

Default region is the name of the region you want to make calls against by default. This is usually the region closest to you, but it can be any region.

Note

You must specify an AWS region when using the AWS CLI. For a list of services and available regions, see Regions and Endpoints.

Default output format can be either json, text, or table. If you don't specify an output format, json will be used.

If you have multiple profiles, you can configure additional, named profiles by using the --profile option. 

$ aws configure --profile user2
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

To update any of your settings, simply run aws configure again and enter new values as appropriate. The next sections contains more information on the files that aws configure creates, additional settings, and named profiles.

Configuration Settings and Precedence

The AWS CLI uses a provider chain to look for AWS credentials in a number of different places, including system or user environment variables and local AWS configuration files.

The AWS CLI looks for credentials and configuration settings in the following order:

  1. Command Line Options – region, output format and profile can be specified as command options to override default settings.

  2. Environment Variables – AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.

  3. The AWS credentials file – located at ~/.aws/credentials on Linux, OS X, or Unix, or at C:\Users\USERNAME \.aws\credentials on Windows. This file can contain multiple named profiles in addition to a default profile.

  4. The CLI configuration file – typically located at ~/.aws/config on Linux, OS X, or Unix, or at C:\Users\USERNAME \.aws\config on Windows. This file can contain a default profile, named profiles, and CLI specific configuration parameters for each.

  5. Instance profile credentials – these credentials can be used on EC2 instances with an assigned instance role, and are delivered through the Amazon EC2 metadata service.

Configuration and Credential Files

The CLI stores credentials specified with aws configure in a local file named credentials in a folder named .aws in your home directory. Home directory location varies but can be referred to using the environment variables %UserProfile% in Windows and $HOME or ~ (tilde) in Unix-like systems.

For example, the following commands list the contents of the .aws folder:

Linux, OS X, or Unix

$ ls  ~/.aws

Windows

> dir %UserProfile%\.aws

In order to separate credentials from less sensitive options, region and output format are stored in a separate file named config in the same folder.

The default file location for the config file can be overridden by setting the AWS_CONFIG_FILE environment variable to another local path. See Environment Variables for details.

Storing Credentials in Config

The AWS CLI will also read credentials from the config file. If you want to keep all of your profile settings in a single file, you can. If there are ever credentials in both locations for a profile (say you used aws configure to update the profile's keys), the keys in the credentials file will take precedence.

If you use one of the SDKs in addition to the AWS CLI, you may notice additional warnings if credentials are not stored in their own file.

The files generated by the CLI for the profile configured in the previous section look like this:

~/.aws/credentials

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

~/.aws/config

[default]
region=us-west-2
output=json

The following settings are supported.

aws_access_key_id – AWS access key.

aws_secret_access_key – AWS secret key.

aws_session_token – AWS session token. A session token is only required if you are using temporary security credentials.

region – AWS region.

output – output format (json, text, or table)

Named Profiles

The AWS CLI supports named profiles stored in the config and credentials files. You can configure additional profiles by using aws configure with the --profile option or by adding entries to the config and credentials files.

The following example shows a credentials file with two profiles:

~/.aws/credentials

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[user2]
aws_access_key_id=AKIAI44QH8DHBEXAMPLE
aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

Each profile uses different credentials—perhaps from two different IAM users—and can also use different regions and output formats.

~/.aws/config

[default]
region=us-west-2
output=json

[profile user2]
region=us-east-1
output=text

Important

The AWS credentials file uses a different naming format than the CLI config file for named profiles. Do not include the 'profile ' prefix when configuring a named profile in the AWS credentials file.

Using Profiles with the AWS CLI

To use a named profile, add the --profile option to your command. The following example lists running instances using the user2 profile from the previous section. 

$ aws ec2 describe-instances --profile user2

If you are going to use a named profile for multiple commands, you can avoid specifying the profile in every command by setting the AWS_DEFAULT_PROFILE environment variable at the command line:

Linux, OS X, or Unix

$ export AWS_DEFAULT_PROFILE=user2

Windows

> set AWS_DEFAULT_PROFILE=user2

Setting the environment variable changes the default profile until the end of your shell session, or until you set the variable to a different value. More on variables in the next section.

Environment Variables

Environment variables override configuration and credential files and can be useful for scripting or temporarily setting a named profile as the default.

The following variables are supported by the AWS CLI

AWS_ACCESS_KEY_ID – AWS access key.

AWS_SECRET_ACCESS_KEY – AWS secret key. Access and secret key variables override credentials stored in credential and config files.

AWS_SESSION_TOKEN – session token. A session token is only required if you are using temporary security credentials.

AWS_DEFAULT_REGION – AWS region. This variable overrides the default region of the in-use profile, if set.

AWS_DEFAULT_PROFILE – name of the CLI profile to use. This can be the name of a profile stored in a credential or config file, or default to use the default profile.

AWS_CONFIG_FILE – path to a CLI config file.

If the config file variable is set, aws configure will write region and output settings to the specified file, and the CLI will attempt to read profiles' settings from there instead of the default file (~/.aws/config). Credentials will still be read from and written to the default credentials file (~/.aws/credentials).

The following example shows how you would configure environment variables for the default user from earlier in this guide.

Linux, OS X, or Unix

$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ export AWS_DEFAULT_REGION=us-west-2

Windows

> set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
> set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
> set AWS_DEFAULT_REGION=us-west-2

Command Line Options

The AWS CLI uses GNU-style long command line options preceded by two hyphens. Command line options can be used to override default configuration settings for a single operation, but cannot be used to specify credentials.

The following settings can be specified at the command line.

--profile – name of a profile to use, or "default" to use the default profile.

--region – AWS region to call.

--output – output format.

--endpoint-url – The endpoint to make the call against. The endpoint can be the address of a proxy or an endpoint URL for the in-use AWS region. Specifying an endpoint is not required for normal use as the AWS CLI determines which endpoint to call based on the in-use region.

The above options override the corresponding profile settings for a single operation. Each takes a string argument with a space or equals sign ("=") separating the argument from the option name. Quotes around the argument are not required unless the argument string contains a space.

Tip

You can use the --profile option with aws configure to set up additional profiles

$ aws configure --profile profilename

Common uses for command line options include checking your resources in multiple regions and changing output format for legibility or ease of use when scripting. For example, if you are not sure which region your instance is running in you could run the describe-instances command against each region until you find it: 

$ aws ec2 describe-instances --output table --region us-east-1
-------------------
|DescribeInstances|
+-----------------+
$ aws ec2 describe-instances --output table --region us-west-1
-------------------
|DescribeInstances|
+-----------------+
$ aws ec2 describe-instances --output table --region us-west-2
------------------------------------------------------------------------------
|                              DescribeInstances                             |
+----------------------------------------------------------------------------+
||                               Reservations                               ||
|+-------------------------------------+------------------------------------+|
||  OwnerId                            |  012345678901                      ||
||  ReservationId                      |  r-abcdefgh                        ||
|+-------------------------------------+------------------------------------+|
|||                                Instances                               |||
||+------------------------+-----------------------------------------------+||
|||  AmiLaunchIndex        |  0                                            |||
|||  Architecture          |  x86_64                                       |||
...

Command line option parameter types (string, boolean, etc.) are discussed in detail in the Specifying Parameter Values for the AWS Command Line Interface section later in this guide.

Instance Metadata

To use the CLI from an EC2 instance, create a role that has access to the resources needed and assign that role to the instance when it is launched. Launch the instance and check to see if the AWS CLI is already installed (it comes pre-installed on Amazon Linux).

Install the AWS CLI if necessary and configure a default region to avoid having to specify it in every command. You can set the region using aws configure without entering credentials by pressing enter twice to skip the first two prompts: 

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

The AWS CLI will read credentials from the instance metadata. For more information, see Granting Applications that Run on Amazon EC2 Instances Access to AWS Resources in IAM User Guide.