Configuration and credential file settings in the AWS 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.

Import CSV credentials generated from the IAM web console. This is not for credentials generated from IAM Identity Center; customers who use IAM Identity Center should use aws configure sso. A CSV file is imported with the profile name matching the username. The CSV file must contain the following headers.

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

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

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

$ aws configure list-profiles
default
test

Run this command to configure a new profile to use with multi-factor authentication (MFA) and your IAM user credentials in the specified profile. If no profile is specified, the MFA is based on the default profile. If no default profile is configured, the mfa-login command prompts you for you AWS credentials before asking for your MFA information. The following command example uses your default configuration and creates an MFA profile.

$ aws configure mfa-login
MFA serial number or ARN: arn:aws:iam::123456789012:mfa/MFADeviceName
MFA token code: 123456
Profile to update [session-MFADeviceName]:
Temporary credentials written to profile 'session-MFADeviceName'
Credentials will expire at 2023-05-19 18:06:10 UTC
To use these credentials, specify --profile session-MFADeviceName when running AWS CLI commands

To update an existing profile, use the --update-profile parameter.

$ aws configure mfa-login --profile myprofile --update-profile mfaprofile
MFA token code: 123456
Temporary credentials written to profile 'mfaprofile'
Credentials will expire at 2023-05-19 18:06:10 UTC
To use these credentials, specify --profile mfaprofile when running AWS CLI commands

This command currently supports only hardware or software based one-time password (OTP) authenticators. Passkeys and U2F devices are not currently supported with this command.

For more information on using MFA with IAM, see AWS Multi-factor authentication in IAM in the AWS Identity and Access Management User Guide.

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

$ 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
SSO registration scopes [None]: sso:account:access

Run this command to quickly set and view your AWS IAM Identity Center credentials, Region, and output format in the sso-session section of the credentials and config files. The following example shows sample values.

$ aws configure sso-session
SSO session name: my-sso
SSO start URL [None]: https://my-sso-portal.awsapps.com/start
SSO region [None]: us-east-1
SSO registration scopes [None]: sso:account:access

Run this command to export currently set credentials in the specified format. By default, the command exports the default credentials in the process format, which is a JSON format supported by the AWS SDKs and Tools credential format.

$ aws configure export-credentials
{
  "Version": 1,
  "AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

To export a specific profile and format, use the --profile and --format options. The format options are as follows:

The following example exports the user1 profile to an exported shell format.

$ aws configure export-credentials --profile user1 --format env
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Specifies whether to use AWS account-based endpoint IDs for calls to supported AWS services. For more information on account-based endpoints, see Account-based endpoints.

This setting can be set to the following:

Can be overridden by the AWS_ACCOUNT_ID_ENDPOINT_MODE environment variable. To use account-based endpoints, the ID must be set in the AWS_ACCOUNT_ID environment variable or aws_account_id setting.

account_id_endpoint_mode = preferred

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 = AKIAIOSFODNN7EXAMPLE

Specifies the AWS account-based endpoint ID to use for calls to supported AWS services. For more information on account-based endpoints, see Account-based endpoints.

Can be overridden by the AWS_ACCOUNT_ID environment variable. The AWS_ACCOUNT_ID_ENDPOINT_MODE environment variable or account_id_endpoint_mode setting must be set to preferred or required to use this setting.

aws_account_id = 123456789EXAMPLE

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

Specifies an AWS 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 AWS 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 AWS CLI version 2 auto-prompt feature, see Enabling and using command prompts in the AWS CLI.

Specifies how the AWS 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 AWS 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 AWS 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 AWS CLI expects the file to contain base64-encoded text. If that setting's value is raw-in-base64-out, the AWS CLI expects the file to contain raw binary content.

As of version 2.31.0 The display for the help command is configured by the cli_help_output setting, and has the following values:

cli_help_output = browser

For more information on the help command, see Accessing help and resources for the AWS CLI.

Disabled by default. This setting enables command history for the AWS CLI. After enabling this setting, the AWS 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 AWS CLI reference guide.

Specifies the pager program used for output. By default, AWS 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

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

This setting does not have an equivalent environment variable or command line option. This setting does not alter timestamp inputs, only output formatting.

cli_timestamp_format = iso8601

Specifies an external command that the AWS 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 AWS 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 AWS 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. For more information, see Set global endpoint for all AWS services.

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

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

ignore_configure_endpoint_urls = true

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 AWS resources to a third party in the IAM User Guide.

Specifies a value of maximum retry attempts the AWS 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 AWS CLI client attempts to validate 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

Specifies the AWS 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 when a checksum is calculated for request payloads, and has the following options:

request_checksum_calculation = when_supported

The environment variable AWS_REQUEST_CHECKSUM_CALCULATION overrides this setting.

Specifies when checksum validation is performed for response payloads, and has the following options:

response_checksum_validation = when_supported

The environment variable AWS_RESPONSE_CHECKSUM_VALIDATION overrides this setting.

Specifies which retry mode AWS CLI uses. There are three retry modes available: standard (default), legacy (default), and adaptive. For more information on retries, see AWS CLI retries in the AWS 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 AWS 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 AWS 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 AWS 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 AWS account can be used by multiple customer applications to make calls to AWS services. Application ID identifies which source application made a set of calls using an AWS service. AWS 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 the regions to use when signing with SigV4a using a comma-delimited list. If this variable is not set, the AWS CLI uses the default used by the AWS service. If the AWS service has no default, the request signature becomes valid in all regions using a value of *.

sigv4a_signing_region_set = us-west-2, us-east-1

For more information on SigV4a, see AWS Signature Version 4 for API requests in the IAM User Guide

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

Specifies a named profile with long-term credentials that the AWS 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 AWS 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 AWS Region that contains the AWS 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 AWS access portal. The AWS CLI uses this URL to establish a session with the IAM Identity Center service to authenticate its users. To find your AWS 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

Enables the use of dual-stack endpoints to send AWS 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 AWS Region, the request fails. Valid settings are true and false. This is disabled by default. For more information, see Set to use dual-stack endpoints for all AWS services.

This is mutually exclusive with the use_accelerate_endpoint setting.

Some AWS services offer endpoints that support Federal Information Processing Standard (FIPS) 140-2 in some AWS Regions. When the AWS service supports FIPS, this setting specifies what FIPS endpoint the AWS CLI should use . Unlike standard AWS 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. For more information see, Set to use FIPs endpoints for all AWS services.

If this setting is enabled, but a FIPS endpoint does not exist for the service in your AWS Region, the AWS 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.

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 AWS 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 AWS 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 AWS Region you configured in the AWS 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 AWS 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.

Enables the use of dual-stack endpoints to send s3 and s3api 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 AWS Region, the request fails. Valid settings are true and false. This is disabled by default. For more information, see Set to use dual-stack endpoints for all AWS services.

This is mutually exclusive with the use_accelerate_endpoint setting.

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

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 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 AWS CLI is aware of that need to be run. This means that by default the AWS CLI can only see 1000 tasks ahead. Increasing this value means that the AWS 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 AWS 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 AWS 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 AWS 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: