Setting up the Amazon CLI - Amazon Command Line Interface
Gather your credential information for programmatic accessSetting up new configuration and credentialsUsing existing configuration and credentials files
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).

Setting up the Amazon CLI

This topic explains how to quickly configure basic settings 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.

Gather your credential information for programmatic access

You'll need programmatic access if you want to interact with Amazon outside of the Amazon Web Services Management Console. For authentication and credential instructions, choose one of the following options:

Authentication type Purpose Instructions

IAM Identity Center workforce users short-term credentials

 (Recommended) Use short-term credentials for an IAM Identity Center workforce user.

Security best practice is to use Amazon Organizations with IAM Identity Center. It combines short-term credentials with a user directory, such as the built-in IAM Identity Center directory or Active Directory.

 Configuring IAM Identity Center authentication with the Amazon CLI
IAM user short-term credentials Use IAM user short-term credentials, which are more secure than long-term credentials. If your credentials are compromised, there is a limited time they can be used before they expire. Authenticating with short-term credentials for the Amazon CLI
IAM or IAM Identity Center users on an Amazon EC2 instance. Use Amazon EC2 instance metadata to query for temporary credentials using the role assigned to the Amazon EC2 instance. Using Amazon EC2 instance metadata as credentials in the Amazon CLI
Assume roles for permissions Pair another credential method and assume a role for temporary access to Amazon Web Services services your user might not have access to. Using an IAM role in the Amazon CLI
IAM user long-term credentials (Not recommended) Use long-term credentials, which have no expiration. Authenticating using IAM user credentials for the Amazon CLI
External storage of IAM or IAM Identity Center workforce users (Not recommended) Pair another credential method but store credential values in a location outside of the Amazon CLI. This method is only as secure as the external location the credentials are stored. Sourcing credentials with an external process in the Amazon CLI

Setting up new configuration and credentials

The Amazon CLI stores your configuration and credential information in a profile (a collection of settings) in the credentials and config files.

The following examples use sample values for each of the authentication methods. Replace sample values with your own.

Configuring using Amazon CLI commands

For general use, the aws configure or aws configure sso commands in your preferred terminal are the fastest way to set up your Amazon CLI installation. Based on the credential method you prefer, the Amazon CLI prompts you for the relevant information. 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 and config files, see Configuration and credential file settings in the Amazon CLI.

IAM Identity Center (SSO)

This example is for Amazon IAM Identity Center using the aws configure sso wizard. For more information, see Configuring IAM Identity Center authentication with the Amazon CLI.

$ aws configure sso
SSO session name (Recommended): my-sso
SSO start URL [None]: https://my-sso-portal.awsapps.com/start
SSO region [None]:us-east-1

Attempting to automatically open the SSO authorization page in your default browser.

There are 2 Amazon accounts available to you.
> DeveloperAccount, developer-account-admin@example.com (111122223333) 
  ProductionAccount, production-account-admin@example.com (444455556666)

Using the account ID 111122223333

There are 2 roles available to you.
> ReadOnly
  FullAccess

Using the role name "ReadOnly"

CLI default client Region [None]: us-west-2
CLI default output format [None]: json
CLI profile name [123456789011_ReadOnly]: user1
IAM Identity Center (Legacy SSO)

This example is for the legacy method of Amazon IAM Identity Center using the aws configure sso wizard. To use the legacy SSO, leave the session name blank. For more information, see Configuring IAM Identity Center authentication with the Amazon CLI.

$ aws configure sso
SSO session name (Recommended):
SSO start URL [None]: https://my-sso-portal.awsapps.com/start
SSO region [None]:us-east-1

SSO authorization page has automatically been opened in your default browser.
Follow the instructions in the browser to complete this authorization request.

There are 2 Amazon accounts available to you.
> DeveloperAccount, developer-account-admin@example.com (111122223333) 
  ProductionAccount, production-account-admin@example.com (444455556666)

Using the account ID 111122223333

There are 2 roles available to you.
> ReadOnly
  FullAccess

Using the role name "ReadOnly"

CLI default client Region [None]: us-west-2
CLI default output format [None]: json
CLI profile name [123456789011_ReadOnly]: user1
Short-term credentials

This example is for the short-term credentials from Amazon Identity and Access Management. The aws configure wizard is used to set initial values and then the aws configure set command assigns the last value needed. For more information, see Authenticating with short-term credentials for the Amazon CLI.

$ 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
$ aws configure set aws_session_token fcZib3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
IAM role

This example is for assuming an IAM role. Profiles that use IAM roles pull credentials from another profile, and then apply IAM role permissions. In the following examples, default is the source profile for credentials and user1 borrows the same credentials then assumes a new role. There is no wizard for this process, therefore each value is set using the aws configure set command. For more information, see Using an IAM role in the Amazon CLI.

$ aws configure set role_arn arn:aws-cn:iam::123456789012:role/defaultrole
$ aws configure set source_profile default
$ aws configure set role_session_name session_user1
$ aws configure set region us-west-2
$ aws configure set output json
Amazon EC2 instance metadata credentials

This example is for the credentials obtained from the hosting Amazon EC2 instance metadata. There is no wizard for this process, therefore each value is set using the aws configure set command. For more information, see Using Amazon EC2 instance metadata as credentials in the Amazon CLI.

$ aws configure set role_arn arn:aws-cn:iam::123456789012:role/defaultrole
$ aws configure set credential_source Ec2InstanceMetadata
$ aws configure set region us-west-2
$ aws configure set output json
Long-term credentials
Warning

To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as Amazon IAM Identity Center.

This example is for the long-term credentials from Amazon Identity and Access Management. For more information, see Authenticating using IAM user credentials for the Amazon CLI.

$ 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

For more detailed information on authentication and credential methods see Authentication and access credentials for the Amazon CLI.

Manually editing the credentials and config files

When copy and pasting information, we suggest manually editing the config and credentials file. Based on the credential method you prefer, the files are setup in a different way.

The files are stored in your home directory under the .aws folder. Where you find your home directory location varies based on the operating system, but is referred to using the environment variables %UserProfile% in Windows and $HOME or ~ (tilde) in Unix-based systems. For more information on where these settings are stored, see Where are configuration settings stored?.

The following examples show a default profile and a profile named user1 and use sample values. Replace sample values with your own. For more information on the credentials and config files, see Configuration and credential file settings in the Amazon CLI.

IAM Identity Center (SSO)

This example is for Amazon IAM Identity Center. For more information, see Configuring IAM Identity Center authentication with the Amazon CLI.

Credentials file

The credentials file is not used for this authentication method.

Config file

[default]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = readOnly
region = us-west-2
output = text

[profile user1]
sso_session = my-sso
sso_account_id = 444455556666
sso_role_name = readOnly
region = us-east-1
output = json

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access
IAM Identity Center (Legacy SSO)

This example is for the legacy method of Amazon IAM Identity Center. For more information, see Configuring IAM Identity Center authentication with the Amazon CLI.

Credentials file

The credentials file is not used for this authentication method.

Config file

[default]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = 111122223333
sso_role_name = readOnly
region = us-west-2
output = text

[profile user1]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = 444455556666
sso_role_name = readOnly
region = us-east-1
output = json
Short-term credentials

This example is for the short-term credentials from Amazon Identity and Access Management. For more information, see Authenticating with short-term credentials for the Amazon CLI.

Credentials file

[default]
aws_access_key_id=ASIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

[user1]
aws_access_key_id=ASIAI44QH8DHBEXAMPLE
aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
aws_session_token = fcZib3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

Config file

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

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

This example is for assuming an IAM role. Profiles that use IAM roles pull credentials from another profile, and then apply IAM role permissions. In the following examples, default is the source profile for credentials and user1 borrows the same credentials then assumes a new role. For more information, see Using an IAM role in the Amazon CLI.

Credentials file

The credentials file depends on what authentication your source profile uses. For the following example, the source profile uses short-term credentials.

[default]
aws_access_key_id=ASIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

Config file

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

[profile user1]
role_arn=arn:aws-cn:iam::777788889999:role/user1role
source_profile=default
role_session_name=session_user1
region=us-east-1
output=text
Amazon EC2 instance metadata credentials

This example is for the credentials obtained from the hosting Amazon EC2 instance metadata. For more information, see Using Amazon EC2 instance metadata as credentials in the Amazon CLI.

Credentials file

The credentials file is not used for this authentication method.

Config file

[default]
role_arn=arn:aws-cn:iam::123456789012:role/defaultrole
credential_source=Ec2InstanceMetadata
region=us-west-2
output=json

[profile user1]
role_arn=arn:aws-cn:iam::777788889999:role/user1role
credential_source=Ec2InstanceMetadata
region=us-east-1
output=text
Long-term credentials
Warning

To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as Amazon IAM Identity Center.

This example is for the long-term credentials from Amazon Identity and Access Management. For more information, see Authenticating using IAM user credentials for the Amazon CLI.

Credentials file

[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

Config file

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

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

For more detailed information on authentication and credential methods see Authentication and access credentials for the Amazon CLI.

Using existing configuration and credentials files

If you have existing configuration and credentials files, these can be used for the Amazon CLI.

To use the config and credentials files, move them to the folder named .aws in your home directory. Where you find your home directory location varies based on the operating system, but is referred to using the environment variables %UserProfile% in Windows and $HOME or ~ (tilde) in Unix-based systems.

You can specify a non-default location for the config and credentials files by setting the AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE environment variables to another local path. See Configuring environment variables for the Amazon CLI for details.

For more detailed information on configuration and credentials files, see Configuration and credential file settings in the Amazon CLI.