Note: You are viewing the documentation for an older major version of the AWS CLI (version 1).
AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click here. For more information see the AWS CLI version 2 installation instructions and migration guide.
Configuration values for the AWS CLI can come from several sources:
Some options are only available in the AWS CLI config. This topic guide covers all the configuration variables available in the AWS CLI.
Note that if you are just looking to get the minimum required configuration to run the AWS CLI, we recommend running aws configure, which will prompt you for the necessary configuration values.
The AWS CLI config file, which defaults to ~/.aws/config has the following format:
[default]
aws_access_key_id=foo
aws_secret_access_key=bar
region=us-west-2
The default section refers to the configuration values for the default profile. You can create profiles, which represent logical groups of configuration. Profiles that aren't the default profile are specified by creating a section titled "profile profilename":
[profile testing]
aws_access_key_id=foo
aws_secret_access_key=bar
region=us-west-2
Some service specific configuration, discussed in more detail below, has a single top level key, with nested sub values. These sub values are denoted by indentation:
[profile testing]
aws_access_key_id = foo
aws_secret_access_key = bar
region = us-west-2
s3 =
max_concurrent_requests=10
max_queue_size=1000
The AWS CLI has a few general options:
Variable | Option | Config Entry | Environment Variable | Description |
---|---|---|---|---|
profile | --profile | N/A | AWS_PROFILE | Default profile name |
region | --region | region | AWS_DEFAULT_REGION | Default AWS Region |
output | --output | output | AWS_DEFAULT_OUTPUT | Default output style |
cli_timestamp_format | N/A | cli_timestamp_format | N/A | Output format of timestamps |
cli_follow_urlparam | N/A | cli_follow_urlparam | N/A | Fetch URL url parameters |
ca_bundle | --ca-bundle | ca_bundle | AWS_CA_BUNDLE | CA Certificate Bundle |
parameter_validation | N/A | parameter_validation | N/A | Toggles parameter validation |
tcp_keepalive | N/A | tcp_keepalive | N/A | Toggles TCP Keep-Alive |
max_attempts | N/A | max_attempts | AWS_MAX_ATTEMPTS | Number of total requests |
retry_mode | N/A | retry_mode | AWS_RETRY_MODE | Type of retries performed |
The third column, Config Entry, is the value you would specify in the AWS CLI config file. By default, this location is ~/.aws/config. If you need to change this value, you can set the AWS_CONFIG_FILE environment variable to change this location.
The valid values of the output configuration variable are:
cli_timestamp_format controls the format of timestamps displayed by the AWS CLI. The valid values of the cli_timestamp_format configuration variable are:
cli_follow_urlparam controls whether or not the CLI will attempt to follow URL links in parameters that start with either prefix https:// or http://. The valid values of the cli_follow_urlparam configuration variable are:
parameter_validation controls whether parameter validation should occur when serializing requests. The default is True. You can disable parameter validation for performance reasons. Otherwise, it's recommended to leave parameter validation enabled.
The max_attempts and retry_mode are explained in the "Retry Configuration" section below.
When you specify a profile, either using --profile profile-name or by setting a value for the AWS_PROFILE environment variable, profile name you provide is used to find the corresponding section in the AWS CLI config file. For example, specifying --profile development will instruct the AWS CLI to look for a section in the AWS CLI config file of [profile development].
The above configuration values have the following precedence:
Credentials can be specified in several ways:
Variable | Creds/Config Entry | Environment Variable | Description |
---|---|---|---|
access_key | aws_access_key_id | AWS_ACCESS_KEY_ID | AWS Access Key |
secret_key | aws_secret_access_key | AWS_SECRET_ACCESS_KEY | AWS Secret Key |
token | aws_session_token | AWS_SESSION_TOKEN | AWS Token (temp credentials) |
metadata_service_timeout | metadata_service_timeout | AWS_METADATA_SERVICE_TIMEOUT | EC2 metadata creds timeout |
metadata_service_num_attempts | metadata_service_num_attempts | AWS_METADATA_SERVICE_NUM_ATTEMPTS | EC2 metadata creds retry count |
The second column specifies the name that you can specify in either the AWS CLI config file or the AWS Shared credentials file (~/.aws/credentials).
Credentials from environment variables have precedence over credentials from the shared credentials and AWS CLI config file. Credentials specified in the shared credentials file have precedence over credentials in the AWS CLI config file. If AWS_PROFILE environment variable is set and the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are set, then the credentials provided by AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY will override the credentials located in the profile provided by AWS_PROFILE.
If you are on an Amazon EC2 instance that was launched with an IAM role, the AWS CLI will automatically retrieve credentials for you. You do not need to configure any credentials.
Additionally, you can specify a role for the AWS CLI to assume, and the AWS CLI will automatically make the corresponding AssumeRole calls for you. Note that configuration variables for using IAM roles can only be in the AWS CLI config file.
You can specify the following configuration values for configuring an IAM role in the AWS CLI config file:
If you do not have MFA authentication required, then you only need to specify a role_arn and either a source_profile or a credential_source.
When you specify a profile that has IAM role configuration, the AWS CLI will make an AssumeRole call to retrieve temporary credentials. These credentials are then stored (in ~/.aws/cli/cache). Subsequent AWS CLI commands will use the cached temporary credentials until they expire, in which case the AWS CLI will automatically refresh credentials.
If you specify an mfa_serial, then the first time an AssumeRole call is made, you will be prompted to enter the MFA code. Subsequent commands will use the cached temporary credentials. However, when the temporary credentials expire, you will be re-prompted for another MFA code.
Example configuration using source_profile:
# In ~/.aws/credentials:
[development]
aws_access_key_id=foo
aws_secret_access_key=bar
# In ~/.aws/config
[profile crossaccount]
role_arn=arn:aws:iam:...
source_profile=development
Example configuration using credential_source to use the instance role as the source credentials for the assume role call:
# In ~/.aws/config
[profile crossaccount]
role_arn=arn:aws:iam:...
credential_source=Ec2InstanceMetadata
Within the ~/.aws/config file, you can also configure a profile to indicate that the AWS CLI should assume a role. When you do this, the AWS CLI will automatically make the corresponding AssumeRoleWithWebIdentity calls to AWS STS on your behalf.
When you specify a profile that has IAM role configuration, the AWS CLI will make an AssumeRoleWithWebIdentity call to retrieve temporary credentials. These credentials are then stored (in ~/.aws/cli/cache). Subsequent AWS CLI commands will use the cached temporary credentials until they expire, in which case the AWS CLI will automatically refresh credentials.
You can specify the following configuration values for configuring an assume role with web identity profile in the shared config:
Below is an example configuration for the minimal amount of configuration needed to configure an assume role with web identity profile:
# In ~/.aws/config
[profile web-identity]
role_arn=arn:aws:iam:...
web_identity_token_file=/path/to/a/token
This provider can also be configured via the environment:
Note
These environment variables currently only apply to the assume role with web identity provider and do not apply to the general assume role provider configuration.
Warning
The following describes a method of sourcing credentials from an external process. This can potentially be dangerous, so proceed with caution. Other credential providers should be preferred if at all possible. If using this option, you should make sure that the config file is as locked down as possible using security best practices for your operating system. Ensure that your custom credential tool does not write any secret information to StdErr because the SDKs and CLI can capture and log such information, potentially exposing it to unauthorized users.
If you have a method of sourcing credentials that isn't built in to the AWS CLI, you can integrate it by using credential_process in the config file. The AWS CLI will call that command exactly as given and then read json data from stdout. The process must write credentials to stdout in the following format:
{
"Version": 1,
"AccessKeyId": "",
"SecretAccessKey": "",
"SessionToken": "",
"Expiration": ""
}
The Version key must be set to 1. This value may be bumped over time as the payload structure evolves.
The Expiration key is an ISO8601 formatted timestamp. If the Expiration key is not returned in stdout, the credentials are long term credentials that do not refresh. Otherwise the credentials are considered refreshable credentials and will be refreshed automatically. NOTE: Unlike with assume role credentials, the AWS CLI will NOT cache process credentials. If caching is needed, it must be implemented in the external process.
The process can return a non-zero RC to indicate that an error occurred while retrieving credentials.
Some process providers may need additional information in order to retrieve the appropriate credentials. This can be done via command line arguments. NOTE: command line options may be visible to process running on the same machine.
Example configuration:
[profile dev]
credential_process = /opt/bin/awscreds-custom
Example configuration with parameters:
[profile dev]
credential_process = /opt/bin/awscreds-custom --username monty
The API version to use for a service can be set using the api_versions key. To specify an API version, set the API version to the name of the service as a sub value for api_versions.
Example configuration:
[profile development]
aws_access_key_id=foo
aws_secret_access_key=bar
api_versions =
ec2 = 2015-03-01
cloudfront = 2015-09-17
By setting an API version for a service, it ensures that the interface for that service's commands is representative of the specified API version.
In the example configuration, the ec2 CLI commands will be representative of Amazon EC2's 2015-03-01 API version and the cloudfront CLI commands will be representative of Amazon CloudFront's 2015-09-17 API version.
To set STS endpoint resolution logic, use the AWS_STS_REGIONAL_ENDPOINTS environment variable or sts_regional_endpoints configuration file option. By default, this configuration option is set to legacy. Valid values are:
Uses the STS endpoint that corresponds to the configured region. For example if the client is configured to use us-west-2, all calls to STS will be make to the sts.us-west-2.amazonaws.com regional endpoint instead of the global sts.amazonaws.com endpoint.
Uses the global STS endpoint, sts.amazonaws.com, for the following configured regions:
All other regions will use their respective regional endpoint.
These configuration variables control how the AWS CLI retries requests.
A string representing the type of retries the AWS CLI will perform. Value values are:
- legacy - The pre-existing retry behavior. This is default value if no retry mode is provided.
- standard - A standardized set of retry rules across the AWS SDKs. This includes a standard set of errors that are retried as well as support for retry quotas, which limit the number of unsuccessful retries an SDK can make. This mode will default the maximum number of attempts to 3 unless a max_attempts is explicitly provided.
- adaptive - An experimental retry mode that includes all the functionality of standard mode along with automatic client side throttling. This is a provisional mode that may change behavior in the future.
There are a number of configuration variables specific to the S3 commands. See AWS CLI S3 Configuration (aws help topics s3-config) for more details.
If you have data stored in AWS that uses a particular encoding, you should make sure that your systems are configured to accept that encoding. For instance, if you have unicode characters as part of a key on EC2 you will need to make sure that your locale is set to a unicode-compatible locale. How you configure your locale will depend on your operating system and your specific IT requirements. One option for UNIX systems is the LC_ALL environment variable. Setting LC_ALL=en_US.UTF-8, for instance, would give you a United States English locale which is compatible with unicode.