Configuration and credential file settings

View and edit your settings by directly editing the config and credentials files in a text editor. For more information see Where are configuration settings stored?

To remove a setting, delete the corresponding setting in your config and credentials files.

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

For more information see Quick configuration with aws configure

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, use an empty string as the value, or manually delete the setting in your config and credentials files in a text editor.

$ aws configure set cli_pager "" --profile integ

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.

Import CSV credentials generated from the Amazon web console. A CSV file is imported with the profile name matching the user name. The CSV file must contain the following headers.

$ aws configure import --csv file://credentials.csv

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

To list all configuration data, use the aws configure list command. This command displays the Amazon CLI name of all settings you've configured, their values, and where the configuration was retrieved from.

$ 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

To list all your profile names, use the aws configure list-profiles command.

$ aws configure list-profiles
default
test

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

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

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

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

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

Enables the auto-prompt for the Amazon CLI version 2. There are two settings that can be used:

You can override this setting by using the aws_cli_auto_prompt environment variable or the --cli-auto-prompt and --no-cli-auto-prompt command line parameters.

For information on the Amazon CLI version 2 auto-prompt feature, see Having the Amazon CLI prompt you for commands.

Specifies how the Amazon CLI version 2 interprets binary input parameters. It can be one of the following values:

This entry does not have an equivalent environment variable. You can specify the value on a single command by using the --cli-binary-format raw-in-base64-out parameter.

cli_binary_format = raw-in-base64-out

If you reference a binary value in a file using the fileb:// prefix notation, the Amazon CLI always expects the file to contain raw binary content and does not attempt to convert the value.

If you reference a binary value in a file using the file:// prefix notation, the Amazon CLI handles the file according to the current cli_binary_format setting. If that setting's value is base64 (the default when not explicitly set), the Amazon CLI expects the file to contain base64-encoded text. If that setting's value is raw-in-base64-out, the Amazon CLI expects the file to contain raw binary content.

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 pager program used for output. By default, Amazon CLI version 2 returns all output through your operating system’s default pager program.

Can be overridden by the AWS_PAGER environment variable.

cli_pager=less

To disable all use of an external paging program, set the variable to an empty string as shown in the following example.

cli_pager=

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.

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 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_REGION environment variable, 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.

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 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 the Amazon account ID that contains the IAM role with the permission that you want to grant to the associated IAM Identity Center user.

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

sso_account_id = 123456789012

Specifies the Amazon Region that contains the Amazon access portal host. This is separate from, and can be a different Region than the default CLI region parameter.

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

sso_region = us_west-2

A comma-delimited list of scopes to be authorized for the sso-session. Scopes authorize access to IAM Identity Center bearer token authorized endpoints. A valid scope is a string, such as sso:account:access. This setting isn't applicable to the legacy non-refreshable configuration.

sso_registration_scopes = sso:account:access

Specifies the friendly name of the IAM role that defines the user's permissions when using this profile.

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

sso_role_name = ReadAccess

Specifies the URL that points to the organization's Amazon access portal. The Amazon CLI uses this URL to establish a session with the IAM Identity Center service to authenticate its users. To find your Amazon access portal URL, use one of the following:

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

sso_start_url = https://my-sso-portal.awsapps.com/start

Some Amazon services offer endpoints that support Federal Information Processing Standard (FIPS) 140-2 in some 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 defined, this environment variable is overridden by the AWS_USE_FIPS_ENDPOINT environment variable and --endpoint-url command line option.

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 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 Amazon CLI directs all Amazon S3 requests to the dual IPv4 / IPv6 endpoint for the configured Region.

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: