AWS Command Line Interface
User Guide

Configuration and Credential Files

You can save your frequently used configuration settings and credentials in files that are maintained by the AWS CLI. The files are divided into sections that can be referenced by name. These are called "profiles". Unless you specify otherwise, the CLI uses the settings found in the profile named default. To use alternate settings, you can create and reference additional profiles. You can also override an individual setting by either setting one of the supported environment variables, or by using a command line parameter.

Where Are Configuration Settings Stored?

The AWS CLI stores the credentials that you specify with aws configure in a local file named credentials, in a folder named .aws in your home directory. The other configuration options that you specify with aws configure are stored in a local file named config, also stored in the .aws folder 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.

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

Linux, macOS, or Unix

$ ls ~/.aws

Windows

C:\> dir "%UserProfile%\.aws"

The AWS CLI uses two files to store the sensitive credential information (in ~/.aws/credentials) separated from the less sensitive configuration options (in ~/.aws/config).

You can specify a non-default location for the config file by setting the AWS_CONFIG_FILE environment variable to another local path. See Environment Variables for details.

Storing Credentials in the Config File

The AWS CLI can also read credentials from the config file. You can keep all of your profile settings in a single file. 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 take precedence.

These files are also used by the various language software development kits (SDKs). If you use one of the SDKs in addition to the AWS CLI, you might receive additional warnings if credentials aren't 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

Note

The preceding examples show the files with a single, default profile. For examples of the files with multiple named profiles, see Named Profiles.

Supported config File Settings

The following settings are supported in the config file. The values listed in the specified (or default) profile are used unless they are overridden by the presence of an environment variable with the same name, or a command line option with the same name.

You can configure these settings by editing the config file directly with a text editor, or by using the aws configure set command. Specify the profile that you want to modify with the --profile setting. For example, the following command sets the region setting in the profile named integ.

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

You can also retrieve the value for any setting by using the get subcommand.

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

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

Global Settings

aws_access_key_id

Specifies the AWS 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 = 123456789012
aws_secret_access_key

Specifies the AWS 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
aws_session_token

Specifies an AWS session token. A session token is required only if you are using 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
ca_bundle

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
cli_follow_urlparam

Specifies whether the 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.

  • true: This is the default value. When configured, any string parameters that begin with http:// or https:// are fetched and any downloaded content is used as the parameter value for the command.

  • false: The CLI does not treat parameter string values that begin with http:// or https:// differently from other strings.

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

cli_follow_urlparam = false
cli_timestamp_format

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

  • none: This is the default value. Displays the timestamp value exactly how received in the HTTP query response.

  • iso8601: Reformat the timestamp as specified by ISO 8601.

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

cli_timestamp_format = iso8601
credential_process

Specifies an external command that the 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.

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

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

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

  • json: This is the default value. The output is formatted as a JSON string.

  • text: The output is formatted as multiple lines of tab-separated string values, which can be useful if you want to pass the output to a text processor, like grep, sed, or awk.

  • table: The output is formatted as a table using the characters +|- to form the cell borders. It typically presents the information in a "human-friendly" format that is much easier to read than the others, but not as programmatically useful.

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

output = table
parameter_validation

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

  • true: This is the default value. When configured, the CLI disables local validation of command line parameters.

  • false: When configured, the CLI does not validate command line parameters before sending them to the AWS service endpoint.

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

parameter_validation = false
region

Specifies the default AWS Region to send requests to for commands requested using this profile. You can specify any of the region codes available for the chosen service as listed at AWS Regions and Endpoints in the Amazon Web Services General Reference.

Can be overridden by the AWS_DEFAULT_REGION environment variable or the --region command line option.

region = us-west-2
tcp_keepalive

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

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

tcp_keepalive = false
api_versions

Some AWS services maintain multiple API versions to support backwards compatibility. By default, 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 AWS service and the API version to use. Refer to the documentation for each service to understand which API versions are available.

The following example shows how to specify an API version for two AWS 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

S3 Custom Command Settings

Amazon S3 supports several settings that configure how the CLI performs S3 operations. Some apply to all S3 commands in both the s3api and s3 namespaces. Others are specifically for the S3 "custom" commands that abstract common operations and do more than a one-to-one mapping to an API operation. The aws s3 transfer commands cp, sync, mv, and rm have additional settings you can use to control S3 transfers.

All of these options can be configured by specifying the s3 nested setting in your config file. Each setting is then indented on its own line.

Note

These settings are entirely optional. You should be able to successfully use the aws s3 transfer commands without configuring any of these settings. These settings are provided to enable you to tune for performance or to account for the specific environment where you are running these aws s3 commands.

The following settings apply to any S3 command in the s3 or s3api namespaces.

use_accelerate_endpoint

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

use_dualstack_endpoint

Use the Amazon S3 dual IPv4 / IPv6 endpoint for all s3 and s3api commands. The default value is false. This is mutually exclusive with the use_accelerate_endpoint setting.

If set to true, the CLI directs all Amazon S3 requests to the dual IPv4 / IPv6 endpoint for the configured region.

addressing_style

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

There are two styles of constructing an 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 was 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 AWS Region you configured in the AWS CLI matches the region of your bucket.

payload_sigining_enabled

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.

The following settings apply only to commands in the s3 namespace command set:

max_concurrent_requests

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 AWS 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:

  • Decreasing this value – On some environments, the default of 10 concurrent requests can overwhelm a system. This can cause connection timeouts or slow the responsiveness of the system. Lowering this value makes the S3 transfer commands less resource intensive. The tradeoff is that S3 transfers can take longer to complete. Lowering this value might be necessary if you use a tool to limit bandwidth.

  • Increasing this value – In some scenarios, you might want the S3 transfers to complete as quickly as possible, using as much network bandwidth as necessary. In this scenario, the default number of concurrent requests might not be sufficient to utilize all of the available network bandwidth. Increasing this value can improve the time it takes to complete an S3 transfer.

max_queue_size

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

The AWS CLI internally uses a model where it queues up S3 tasks that are then executed by consumers whose numbers are limited by max_concurrent_requests. A task generally maps to a single S3 operation. For example, as 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 CLI is aware of that need to be run. This means that by default the CLI can only see 1000 tasks ahead. Until the S3 command knows the total number of tasks executed, the progress line shows a total of .... Increasing this value means that the 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.

multipart_threshold

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

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

  • The file size in bytes. For example, 1048576.

  • The file size with a size suffix. You can use KB, MB, GB, or TB. For example: 10MB, 1GB.

    Note

    S3 can impose constraints on valid values that can be used for multipart operations. For more information, see the S3 Multipart Upload documentation in the Amazon Simple Storage Service Developer Guide.

multipart_chunksize

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

When a file transfer exceeds the multipart_threshold, the CLI divides the file into chunks of this size. This value can 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.

max_bandwidth

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 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:

  • An integer. For example, 1048576 sets the maximum bandwidth usage to 1 megabyte per second.

  • An integer followed by a rate suffix. You can specify rate suffixes using: KB/s, MB/s, or GB/s. For example: 300KB/s, 10MB/s.

In general, we recommend that you first try to lower bandwidth consumption by lowering max_concurrent_requests. If that doesn't adequate limit bandwidth consumption to the desired rate, then you can use the max_bandwidth setting can then be used 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 unneccessarily, which can lead to excess resource consumption and connection timeouts.

These settings are all set under a top level s3 key in the config file, as shown in the following example for the development profile:

[profile development] s3 = max_concurrent_requests = 20 max_queue_size = 10000 multipart_threshold = 64MB multipart_chunksize = 16MB max_bandwidth = 50MB/s use_accelerate_endpoint = true addressing_style = path