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).

Named profiles for the Amazon CLI

A named profile is a collection of settings and credentials that you can apply to a Amazon CLI command. When you specify a profile to run a command, the settings and credentials are used to run that command. Multiple named profiles can be stored in the config and credentials files.

You can specify one default profile that is used when no profile is explicitly referenced. Other profiles have names that you can specify as a parameter on the command line for individual commands. Alternatively, you can specify a profile in the AWS_PROFILE environment variable which overrides the default profile for commands that run in that session.

Creating named profiles

You can configure additional profiles by using aws configure with the --profile option, or by manually adding entries to the config and credentials files. For more information on the config and credentials files, see Configuration and credential file settings.

Credentials profile

The following example shows a credentials file with two profiles. The first [default] is used when you run a Amazon CLI command with no profile. The second is used when you run a Amazon CLI command with the --profile user1 parameter.

The credentials file uses a different naming format than the Amazon CLI config file for named profiles. Do not use the word profile when creating an entry in the credentials file.

~/.aws/credentials (Linux & Mac) or %USERPROFILE%\.aws\credentials (Windows)

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

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

For more information on key pairs, see Access key ID and secret access key.

Config profile

Each profile can specify different credentials and can also specify different Amazon Regions and output formats. When naming the profile in a config file, include the prefix word "profile".

The following example specifies Region and output information for the default and user1 profiles.

~/.aws/config (Linux & Mac) or %USERPROFILE%\.aws\config (Windows)

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

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

Using named profiles

To use a named profile, add the --profile profile-name option to your command. The following example lists all of your Amazon EC2 instances using the credentials and settings defined in the user1 profile from the previous example files.

$ aws ec2 describe-instances --profile user1

To use a named profile for multiple commands, you can avoid specifying the profile in every command by setting the AWS_PROFILE environment variable at the command line.

Linux or macOS

$ export AWS_PROFILE=user1

Windows

C:\> setx AWS_PROFILE user1

Using set to set an environment variable changes the value used until the end of the current command prompt session, or until you set the variable to a different value.

Using setx to set an environment variable changes the value in all command shells that you create after running the command. It does not affect any command shell that is already running at the time you run the command. Close and restart the command shell to see the effects of the change.

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. You can make environment variables persistent across future sessions by putting them in your shell's startup script. For more information, see Environment variables to configure the Amazon CLI.