Configuration and credential file settings in the Amazon CLI

Run this command to quickly set and view your credentials, Region, and output format. The following example shows sample values.

$ 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

You can set any credentials or configuration settings using aws configure set. Specify the profile that you want to view or modify with the --profile setting.

For example, the following command sets the region in the profile named integ.

$ aws configure set region us-west-2 --profile integ

To remove a setting, manually delete the setting in your config and credentials files in a text editor.

You can retrieve any credentials or configuration settings you've set using aws configure get. Specify the profile that you want to view or modify with the --profile setting.

For example, the following command retrieves the region setting in the profile named integ.

$ aws configure get region --profile integ
us-west-2

If the output is empty, the setting is not explicitly set and uses the default value.

To list configuration data, use the aws configure list command. This command lists the profile, access key, secret key, and region configuration information used for the specified profile. For each configuration item, it shows the value, where the configuration value was retrieved, and the configuration variable name.

For example, if you provide the Amazon Web Services Region in an environment variable, this command shows you the name of the region you've configured, that this value came from an environment variable, and the name of the environment variable.

For temporary credential methods such as roles and IAM Identity Center, this command displays the temporarily cached access key and secret access key is displayed.

$ aws configure list
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                <not set>             None    None
access_key     ****************ABCD  shared-credentials-file    
secret_key     ****************ABCD  shared-credentials-file    
    region                us-west-2             env    AWS_DEFAULT_REGION

Some Amazon services maintain multiple API versions to support backward compatibility. By default, Amazon CLI commands use the latest available API version. You can specify an API version to use for a profile by including the api_versions setting in the config file.

This is a "nested" setting that is followed by one or more indented lines that each identify one Amazon service and the API version to use. See the documentation for each service to understand which API versions are available.

The following example shows how to specify an API version for two Amazon services. These API versions are used only for commands that run under the profile that contains these settings.

api_versions =
    ec2 = 2015-03-01
    cloudfront = 2015-09-017

This setting does not have an environment variable or command line parameter equivalent.

Specifies the Amazon access key used as part of the credentials to authenticate the command request. Although this can be stored in the config file, we recommend that you store this in the credentials file.

Can be overridden by the AWS_ACCESS_KEY_ID environment variable. You can't specify the access key ID as a command line option.

aws_access_key_id = AKIAIOSFODNN7EXAMPLE

Specifies the Amazon secret key used as part of the credentials to authenticate the command request. Although this can be stored in the config file, we recommend that you store this in the credentials file.

Can be overridden by the AWS_SECRET_ACCESS_KEY environment variable. You can't specify the secret access key as a command line option.

aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Specifies an Amazon session token. A session token is required only if you manually specify temporary security credentials. Although this can be stored in the config file, we recommend that you store this in the credentials file.

Can be overridden by the AWS_SESSION_TOKEN environment variable. You can't specify the session token as a command line option.

aws_session_token = AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

Specifies a CA certificate bundle (a file with the .pem extension) that is used to verify SSL certificates.

Can be overridden by the AWS_CA_BUNDLE environment variable or the --ca-bundle command line option.

ca_bundle = dev/apps/ca-certs/cabundle-2019mar05.pem

Specifies whether the Amazon CLI attempts to follow URL links in command line parameters that begin with http:// or https://. When enabled, the retrieved content is used as the parameter value instead of the URL.

This entry does not have an equivalent environment variable or command line option.

cli_follow_urlparam = false

Disabled by default. This setting enables command history for the Amazon CLI. After enabling this setting, the Amazon CLI records the history of aws commands.

cli_history = enabled

You can list your history using the aws history list command, and use the resulting command_ids in the aws history show command for details. For more information see aws history in the Amazon CLI reference guide.

Specifies the format of timestamp values included in the output. You can specify either of the following values:

This entry does not have an equivalent environment variable or command line option.

cli_timestamp_format = iso8601

Specifies an external command that the Amazon CLI runs to generate or retrieve authentication credentials to use for this command. The command must return the credentials in a specific format. For more information about how to use this setting, see Sourcing credentials with an external process in the Amazon CLI.

This entry does not have an equivalent environment variable or command line option.

credential_process = /opt/bin/awscreds-retriever --username susan

Used within Amazon EC2 instances or containers to specify where the Amazon CLI can find credentials to use to assume the role you specified with the role_arn parameter. You cannot specify both source_profile and credential_source in the same profile.

This parameter can have one of three values:

credential_source = Ec2InstanceMetadata

Specifies the maximum duration of the role session, in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role (which can be a maximum of 43200). This is an optional parameter and by default, the value is set to 3600 seconds.

Specifies the endpoint that is used for all service requests. If this setting is used in the services section of the config file, then the endpoint is used only for the specified service.

The following example uses the global endpoint http://localhost:1234 and a service-specific endpoint of http://localhost:4567 for Amazon S3.

[profile dev]
endpoint_url = http://localhost:1234
services = s3-specific

[services s3-specific]
s3 = 
  endpoint_url = http://localhost:4567

Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local Amazon configuration files, or explicitly declared on the command line as a parameter. The Amazon CLI endpoint configuration settings take precedence in the following order:

If enabled, the Amazon CLI ignores all custom endpoint configurations specified in the config file. Valid values are true and false.

ignore_configure_endpoint_urls = true

Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local Amazon configuration files, or explicitly declared on the command line as a parameter. The Amazon CLI endpoint configuration settings take precedence in the following order:

Specifies a unique identifier that is used by third parties to assume a role in their customers' accounts. This maps to the ExternalId parameter in the AssumeRole operation. This parameter is needed only if the trust policy for the role specifies a value for ExternalId. For more information, see How to use an external ID when granting access to your Amazon resources to a third party in the IAM User Guide.

Specifies a value of maximum retry attempts the Amazon CLI retry handler uses, where the initial call counts toward the max_attempts value that you provide.

You can override this value by using the AWS_MAX_ATTEMPTS environment variable.

max_attempts = 3

The identification number of an MFA device to use when assuming a role. This is mandatory only if the trust policy of the role being assumed includes a condition that requires MFA authentication. The value can be either a serial number for a hardware device (such as GAHT12345678) or an Amazon Resource Name (ARN) for a virtual MFA device (such as arn:aws:iam::123456789012:mfa/user).

Specifies the default output format for commands requested using this profile. You can specify any of the following values:

Can be overridden by the AWS_DEFAULT_OUTPUT environment variable or the --output command line option.

output = table

Specifies whether the Amazon CLI client attempts to validate parameters before sending them to the Amazon service endpoint.

This entry does not have an equivalent environment variable or command line option.

parameter_validation = false

Specifies the Amazon Web Services Region to send requests to for commands requested using this profile.

You can override this value by using the AWS_DEFAULT_REGION environment variable, or the --region command line option.

region = us-west-2

Specifies which retry mode Amazon CLI uses. There are three retry modes available: legacy (default), standard, and adaptive. For more information on retries, see Amazon CLI retries in the Amazon CLI.

You can override this value by using the AWS_RETRY_MODE environment variable.

retry_mode = standard

Specifies the Amazon Resource Name (ARN) of an IAM role that you want to use to run the Amazon CLI commands. You must also specify one of the following parameters to identify the credentials that have permission to assume this role:

role_arn = arn:aws:iam::123456789012:role/role-name

The environment variable AWS_ROLE_ARN overrides this setting.

For more information on using web identities, see Assume role with web identity.

Specifies the name to attach to the role session. This value is provided to the RoleSessionName parameter when the Amazon CLI calls the AssumeRole operation, and becomes part of the assumed role user ARN: arn:aws:sts::123456789012:assumed-role/role_name/role_session_name. This is an optional parameter. If you do not provide this value, a session name is generated automatically. This name appears in Amazon CloudTrail logs for entries associated with this session.

role_session_name = maria_garcia_role

The environment variable AWS_ROLE_SESSION_NAME overrides this setting.

For more information on using web identities, see Assume role with web identity.

Specifies the service configuration to use for your profile.

[profile dev-s3-specific-and-global]
endpoint_url = http://localhost:1234
services = s3-specific

[services s3-specific]
s3 = 
  endpoint_url = http://localhost:4567

For more information on the services section, see Section type: services.

The environment variable AWS_ROLE_SESSION_NAME overrides this setting.

For more information on using web identities, see Assume role with web identity.

A single Amazon Web Services account can be used by multiple customer applications to make calls to Amazon Web Services services. Application ID identifies which source application made a set of calls using an Amazon Web Services service. Amazon SDKs and services don't use or interpret this value other than to surface it back in customer communications. For example, this value can be included in operational emails to uniquely identify which of your applications is associated with the notification.

The Application ID is a string with maximum length of 50 characters. Letters, numbers and the following special characters are allowed: ! $ % & * + - . , ^ _ ` | ~ By default, no value is assigned.

sdk_ua_app_id = prod1

This setting can be overwritten by using the AWS_SDK_UA_APP_ID environment variable. You can't set this value as a command line parameter.

Specifies a named profile with long-term credentials that the Amazon CLI can use to assume a role that you specified with the role_arn parameter. You cannot specify both source_profile and credential_source in the same profile.

source_profile = production-profile

Specifies how the Amazon CLI determines the Amazon service endpoint that the Amazon CLI client uses to talk to the Amazon Security Token Service (Amazon STS). The default value for Amazon CLI version 1 is legacy.

You can specify one of two values:

This setting can be overwritten by using the AWS_STS_REGIONAL_ENDPOINTS environment variable. You can't set this value as a command line parameter.

Enables the use of dual-stack endpoints to send Amazon requests. To learn more about dual-stack endpoints, which support both IPv4 and IPv6 traffic, see Using Amazon S3 dual-stack endpoints in the Amazon Simple Storage Service User Guide. Dual-stack endpoints are available for some services in some regions. If a dual-stack endpoint does not exist for the service or Amazon Web Services Region, the request fails. This is disabled by default.

This is mutually exclusive with the use_accelerate_endpoint setting.

Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local Amazon configuration files, or explicitly declared on the command line as a parameter. The Amazon CLI endpoint configuration settings take precedence in the following order:

Some Amazon services offer endpoints that support Federal Information Processing Standard (FIPS) 140-2 in some Amazon Web Services Regions. When the Amazon service supports FIPS, this setting specifies what FIPS endpoint the Amazon CLI should use . Unlike standard Amazon endpoints, FIPS endpoints use a TLS software library that complies with FIPS 140-2. These endpoints might be required by enterprises that interact with the United States government.

If this setting is enabled, but a FIPS endpoint does not exist for the service in your Amazon Web Services Region, the Amazon command may fail. In this case, manually specify the endpoint to use in the command using the --endpoint-url option or use service-specific endpoints.

For more information on specifying FIPS endpoints by Amazon Web Services Region, see FIPS Endpoints by Service.

Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local Amazon configuration files, or explicitly declared on the command line as a parameter. The Amazon CLI endpoint configuration settings take precedence in the following order:

Specifies the path to a file that contains an OAuth 2.0 access token or OpenID Connect ID token that is provided by an identity provider. The Amazon CLI loads the contents of this file and passes it as the WebIdentityToken argument to the AssumeRoleWithWebIdentity operation.

The environment variable AWS_WEB_IDENTITY_TOKEN_FILE overrides this setting.

For more information on using web identities, see Assume role with web identity.

Specifies whether the Amazon CLI client uses TCP keep-alive packets.

This entry does not have an equivalent environment variable or command line option.

tcp_keepalive = false

Specifies which addressing style to use. This controls whether the bucket name is in the hostname or is part of the URL. Valid values are: path, virtual, and auto. The default value is auto.

There are two styles of constructing an Amazon S3 endpoint. The first is called virtual and includes the bucket name as part of the hostname. For example: https://bucketname.s3.amazonaws.com. Alternatively, with the path style, you treat the bucket name as if it is a path in the URI; for example, https://s3.amazonaws.com/bucketname. The default value in the CLI is to use auto, which attempts to use the virtual style where it can, but will fall back to path style when required. For example, if your bucket name is not DNS compatible, the bucket name cannot be part of the hostname and must be in the path. With auto, the CLI will detect this condition and automatically switch to path style for you. If you set the addressing style to path, you must then ensure that the Amazon Region you configured in the Amazon CLI matches the Region of your bucket.

Specifies whether to SHA256 sign sigv4 payloads. By default, this is disabled for streaming uploads (UploadPart and PutObject) when using HTTPS. By default, this is set to false for streaming uploads (UploadPart and PutObject), but only if a ContentMD5 is present (it is generated by default) and the endpoint uses HTTPS.

If set to true, S3 requests receive additional content validation in the form of a SHA256 checksum which is calculated for you and included in the request signature. If set to false, the checksum isn't calculated. Disabling this can be useful to reduce the performance overhead created by the checksum calculation.

Use the Amazon S3 Accelerate endpoint for all s3 and s3api commands. The default value is false. This is mutually exclusive with the use_dualstack_endpoint setting.

If set to true, the Amazon CLI directs all Amazon S3 requests to the S3 Accelerate endpoint at s3-accelerate.amazonaws.com. To use this endpoint, you must enable your bucket to use S3 Accelerate. All requests are sent using the virtual style of bucket addressing: my-bucket.s3-accelerate.amazonaws.com. Any ListBuckets, CreateBucket, and DeleteBucket requests aren't sent to the S3 Accelerate endpoint as that endpoint doesn't support those operations. This behavior can also be set if the --endpoint-url parameter is set to https://s3-accelerate.amazonaws.com or http://s3-accelerate.amazonaws.com for any s3 or s3api command.

Specifies the maximum bandwidth that can be consumed for uploading and downloading data to and from Amazon S3. The default is no limit.

This limits the maximum bandwidth that the S3 commands can use to transfer data to and from Amazon S3. This value applies to only uploads and downloads; it doesn't apply to copies or deletes. The value is expressed as bytes per second. The value can be specified as:

In general, we recommend that you first try to lower bandwidth consumption by lowering max_concurrent_requests. If that doesn't adequately limit bandwidth consumption to the desired rate, you can use the max_bandwidth setting to further limit bandwidth consumption. This is because max_concurrent_requests controls how many threads are currently running. If you instead first lower max_bandwidth but leave a high max_concurrent_requests setting, it can result in threads having to wait unnecessarily. This can lead to excess resource consumption and connection timeouts.

Specifies the maximum number of concurrent requests. The default value is 10.

The aws s3 transfer commands are multithreaded. At any given time, multiple Amazon S3 requests can be running. For example, when you use the command aws s3 cp localdir s3://bucket/ --recursive to upload files to an S3 bucket, the Amazon CLI can upload the files localdir/file1, localdir/file2, and localdir/file3 in parallel. The setting max_concurrent_requests specifies the maximum number of transfer operations that can run at the same time.

You might need to change this value for a few reasons:

Specifies the maximum number of tasks in the task queue. The default value is 1000.

The Amazon CLI internally uses a model where it queues up Amazon S3 tasks that are then executed by consumers whose numbers are limited by max_concurrent_requests. A task generally maps to a single Amazon S3 operation. For example, a task could be a PutObjectTask, or a GetObjectTask, or an UploadPartTask. The rate at which tasks are added to the queue can be much faster than the rate at which consumers finish the tasks. To avoid unbounded growth, the task queue size is capped to a specific size. This setting changes the value of that maximum number.

You generally don't need to change this setting. This setting also corresponds to the number of tasks that the Amazon CLI is aware of that need to be run. This means that by default the Amazon CLI can only see 1000 tasks ahead. Increasing this value means that the Amazon CLI can more quickly know the total number of tasks needed, assuming that the queuing rate is quicker than the rate of task completion. The tradeoff is that a larger max_queue_size requires more memory.

Specifies the chunk size that the Amazon CLI uses for multipart transfers of individual files. The default value is 8 MB, with a minimum of 5 MB.

When a file transfer exceeds the multipart_threshold, the Amazon CLI divides the file into chunks of this size. This value can be specified using the same syntax as multipart_threshold, either as the number of bytes as an integer, or by using a size and a suffix.

Specifies the size threshold the Amazon CLI uses for multipart transfers of individual files. The default value is 8 MB.

When uploading, downloading, or copying a file, the Amazon S3 commands switch to multipart operations if the file exceeds this size. You can specify this value in one of two ways: