Configuring environment variables for the Amazon CLI - Amazon Command Line Interface
How to set environment variablesAmazon CLI supported environment variables
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.

Configuring environment variables for the Amazon CLI

Environment variables provide another way to specify configuration options and credentials, and can be useful for scripting.

Precedence of options

  • If you specify an option by using one of the environment variables described in this topic, it overrides any value loaded from a profile in the configuration file.

  • If you specify an option by using a parameter on the Amazon CLI command line, it overrides any value from either the corresponding environment variable or a profile in the configuration file.

For more information about precedence and how the Amazon CLI determines which credentials to use, see Configuring settings for the Amazon CLI.

How to set environment variables

The following examples show how you can configure environment variables for the default user.

Linux or macOS
$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ export AWS_DEFAULT_REGION=us-west-2

Setting the environment variable changes the value used until the end of your shell session, or until you set the variable to a different value. You can make the variables persistent across future sessions by setting them in your shell's startup script.

Windows Command Prompt

To set for all sessions

C:\> setx AWS_ACCESS_KEY_ID AKIAIOSFODNN7EXAMPLE
C:\> setx AWS_SECRET_ACCESS_KEY wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
C:\> setx AWS_DEFAULT_REGION us-west-2

Using setx to set an environment variable changes the value used in both the current command prompt session and all command prompt sessions that you create after running the command. It does not affect other command shells that are already running at the time you run the command. You may need to restart you terminal for settings to load.

To set for current session only

Using set to set an environment variable changes the value used until the end of the current command prompt session, or until you set the variable to a different value. 

C:\> set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
C:\> set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
C:\> set AWS_DEFAULT_REGION=us-west-2
PowerShell
PS C:\> $Env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
PS C:\> $Env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
PS C:\> $Env:AWS_DEFAULT_REGION="us-west-2"

If you set an environment variable at the PowerShell prompt as shown in the previous examples, it saves the value for only the duration of the current session. To make the environment variable setting persistent across all PowerShell and Command Prompt sessions, store it by using the System application in Control Panel. Alternatively, you can set the variable for all future PowerShell sessions by adding it to your PowerShell profile. See the PowerShell documentation for more information about storing environment variables or persisting them across sessions.

Amazon CLI supported environment variables

The Amazon CLI supports the following environment variables.

AWS_ACCESS_KEY_ID

Specifies an Amazon access key associated with an IAM account.

If defined, this environment variable overrides the value for the profile setting aws_access_key_id. You can't specify the access key ID by using a command line option.

AWS_CA_BUNDLE

Specifies the path to a certificate bundle to use for HTTPS certificate validation.

If defined, this environment variable overrides the value for the profile setting ca_bundle. You can override this environment variable by using the --ca-bundle command line parameter.

AWS_CLI_S3_MV_VALIDATE_SAME_S3_PATHS

If the source and destination buckets are the same when using custom the s3 mv command, the source file or object can be moved onto itself, which can result in accidental deletion of your source file or object. The AWS_CLI_S3_MV_VALIDATE_SAME_S3_PATHS environment variable and --validate-same-s3-paths option specifies whether to validate your access point ARNs or access point aliases in your Amazon S3 source or destination URIs.

Note

Path validation for s3 mv requires additional API calls.

AWS_CONFIG_FILE

Specifies the location of the file that the Amazon CLI uses to store configuration profiles. The default path is ~/.aws/config.

You can't specify this value in a named profile setting or by using a command line parameter.

AWS_DATA_PATH

A list of additional directories to check outside of the built-in search path of ~/.aws/models when loading Amazon CLI data. Setting this environment variable indicates additional directories to check first before falling back to the built-in search path. Multiple entries should be separated with the os.pathsep character, which is : on Linux or macOS and ; on Windows.

AWS_DEFAULT_OUTPUT

Specifies the output format to use.

If defined, this environment variable overrides the value for the profile setting output. You can override this environment variable by using the --output command line parameter.

AWS_DEFAULT_REGION

The Default region name identifies the Amazon Region whose servers you want to send your requests to by default. This is typically the Region closest to you, but it can be any Region. For example, you can type us-west-2 to use US West (Oregon). This is the Region that all later requests are sent to, unless you specify otherwise in an individual command.

Note

You must specify an Amazon Region when using the Amazon CLI, either explicitly or by setting a default Region. For a list of the available Regions, see Regions and Endpoints. The Region designators used by the Amazon CLI are the same names that you see in Amazon Web Services Management Console URLs and service endpoints.

If defined, this environment variable overrides the value for the profile setting region. You can override this environment variable by using the --region command line parameter.

AWS_EC2_METADATA_DISABLED

Disables the use of the Amazon EC2 instance metadata service (IMDS).

If set to true, user credentials or configuration (like the Region) are not requested from IMDS.

AWS_ENDPOINT_URL

Specifies the endpoint that is used for all service requests.

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:

  1. The --endpoint-url command line option.

  2. If enabled, the AWS_IGNORE_CONFIGURED_ENDPOINT_URLS global endpoint environment variable or profile setting ignore_configure_endpoint_urls to ignore custom endpoints.

  3. The value provided by a service-specific environment variable AWS_ENDPOINT_URL_<SERVICE>, such as AWS_ENDPOINT_URL_DYNAMODB.

  4. The values provided by the AWS_USE_DUALSTACK_ENDPOINT, AWS_USE_FIPS_ENDPOINT, and AWS_ENDPOINT_URL environment variables.

  5. The service-specific endpoint value provided by the endpoint_url setting within a services section of the shared config file.

  6. The value provided by the endpoint_url setting within a profile of the shared config file.

  7. use_dualstack_endpoint, use_fips_endpoint, and endpoint_url settings.

  8. Any default endpoint URL for the respective Amazon Web Services service is used last. For a list of the standard service endpoints available in each Region, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.

AWS_ENDPOINT_URL_<SERVICE>

Specifies a custom endpoint that is used for a specific service, where <SERVICE> is replaced with the Amazon Web Services service identifier. For example, Amazon DynamoDB has a serviceId of DynamoDB. For this service, the endpoint URL environment variable is AWS_ENDPOINT_URL_DYNAMODB.

For a list of all service-specific environment variables, see List of service-specific identifiers.

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:

  1. The --endpoint-url command line option.

  2. If enabled, the AWS_IGNORE_CONFIGURED_ENDPOINT_URLS global endpoint environment variable or profile setting ignore_configure_endpoint_urls to ignore custom endpoints.

  3. The value provided by a service-specific environment variable AWS_ENDPOINT_URL_<SERVICE>, such as AWS_ENDPOINT_URL_DYNAMODB.

  4. The values provided by the AWS_USE_DUALSTACK_ENDPOINT, AWS_USE_FIPS_ENDPOINT, and AWS_ENDPOINT_URL environment variables.

  5. The service-specific endpoint value provided by the endpoint_url setting within a services section of the shared config file.

  6. The value provided by the endpoint_url setting within a profile of the shared config file.

  7. use_dualstack_endpoint, use_fips_endpoint, and endpoint_url settings.

  8. Any default endpoint URL for the respective Amazon Web Services service is used last. For a list of the standard service endpoints available in each Region, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.

AWS_IGNORE_CONFIGURED_ENDPOINT_URLS

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

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:

  1. The --endpoint-url command line option.

  2. If enabled, the AWS_IGNORE_CONFIGURED_ENDPOINT_URLS global endpoint environment variable or profile setting ignore_configure_endpoint_urls to ignore custom endpoints.

  3. The value provided by a service-specific environment variable AWS_ENDPOINT_URL_<SERVICE>, such as AWS_ENDPOINT_URL_DYNAMODB.

  4. The values provided by the AWS_USE_DUALSTACK_ENDPOINT, AWS_USE_FIPS_ENDPOINT, and AWS_ENDPOINT_URL environment variables.

  5. The service-specific endpoint value provided by the endpoint_url setting within a services section of the shared config file.

  6. The value provided by the endpoint_url setting within a profile of the shared config file.

  7. use_dualstack_endpoint, use_fips_endpoint, and endpoint_url settings.

  8. Any default endpoint URL for the respective Amazon Web Services service is used last. For a list of the standard service endpoints available in each Region, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.

AWS_MAX_ATTEMPTS

Specifies a value of maximum retry attempts the Amazon CLI retry handler uses, where the initial call counts toward the value that you provide. For more information on retries, see Amazon CLI retries in the Amazon CLI.

If defined, this environment variable overrides the value for the profiles setting max_attempts.

AWS_METADATA_SERVICE_NUM_ATTEMPTS

When attempting to retrieve credentials on an Amazon EC2 instance that has been configured with an IAM role, the Amazon CLI attempts to retrieve credentials once from the instance metadata service before stopping. If you know your commands will run on an Amazon EC2 instance, you can increase this value to make Amazon CLI retry multiple times before giving up.

AWS_METADATA_SERVICE_TIMEOUT

The number of seconds before a connection to the instance metadata service should time out. When attempting to retrieve credentials on an Amazon EC2 instance that is configured with an IAM role, a connection to the instance metadata service times out after 1 second by default. If you know you're running on an Amazon EC2 instance with an IAM role configured, you can increase this value if needed.

AWS_PROFILE

Specifies the name of the Amazon CLI profile with the credentials and options to use. This can be the name of a profile stored in a credentials or config file, or the value default to use the default profile.

If defined, this environment variable overrides the behavior of using the profile named [default] in the configuration file. You can override this environment variable by using the --profile command line parameter.

AWS_RETRY_MODE

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.

If defined, this environment variable overrides the value for the profiles setting retry_mode.

AWS_ROLE_ARN

Specifies the Amazon Resource Name (ARN) of an IAM role with a web identity provider that you want to use to run the Amazon CLI commands.

Used with the AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_SESSION_NAME environment variables.

If defined, this environment variable overrides the value for the profile setting role_arn. You can't specify a role session name as a command line parameter.

Note

This environment variable only applies to an assumed role with web identity provider it does not apply to the general assume role provider configuration.

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

AWS_ROLE_SESSION_NAME

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.

If defined, this environment variable overrides the value for the profile setting role_session_name.

Used with the AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE environment variables.

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

Note

This environment variable only applies to an assumed role with web identity provider it does not apply to the general assume role provider configuration.

AWS_SDK_UA_APP_ID

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.

By default, there is no value.

The Application ID is a string with maximum length of 50 characters. Letters, numbers and the following special characters are allowed: 

! $ % & * + - . , ^ _ ` | ~

If defined, this environment variable overrides the value for the profile setting sdk_ua_app_id. You can't specify Application ID as a command line option.

AWS_SECRET_ACCESS_KEY

Specifies the secret key associated with the access key. This is essentially the "password" for the access key.

If defined, this environment variable overrides the value for the profile setting aws_secret_access_key. You can't specify the secret access key ID as a command line option.

AWS_SESSION_TOKEN

Specifies the session token value that is required if you are using temporary security credentials that you retrieved directly from Amazon STS operations. For more information, see the Output section of the assume-role command in the Amazon CLI Command Reference.

If defined, this environment variable overrides the value for the profile setting aws_session_token.

AWS_SHARED_CREDENTIALS_FILE

Specifies the location of the file that the Amazon CLI uses to store access keys. The default path is ~/.aws/credentials.

You can't specify this value in a named profile setting or by using a command line parameter.

AWS_STS_REGIONAL_ENDPOINTS

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:

  • legacy – Uses the global STS endpoint, sts.amazonaws.com, for the following Amazon Regions: ap-northeast-1, ap-south-1, ap-southeast-1, ap-southeast-2, aws-global, ca-central-1, eu-central-1, eu-north-1, eu-west-1, eu-west-2, eu-west-3, sa-east-1, us-east-1, us-east-2, us-west-1, and us-west-2. All other Regions automatically use their respective Regional endpoint.

  • regional – The Amazon CLI always uses the Amazon STS endpoint for the currently configured Region. For example, if the client is configured to use us-west-2, all calls to Amazon STS are made to the Regional endpoint sts.us-west-2.amazonaws.com instead of the global sts.amazonaws.com endpoint. To send a request to the global endpoint while this setting is enabled, you can set the Region to aws-global.

AWS_USE_DUALSTACK_ENDPOINT

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.

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:

  1. The --endpoint-url command line option.

  2. If enabled, the AWS_IGNORE_CONFIGURED_ENDPOINT_URLS global endpoint environment variable or profile setting ignore_configure_endpoint_urls to ignore custom endpoints.

  3. The value provided by a service-specific environment variable AWS_ENDPOINT_URL_<SERVICE>, such as AWS_ENDPOINT_URL_DYNAMODB.

  4. The values provided by the AWS_USE_DUALSTACK_ENDPOINT, AWS_USE_FIPS_ENDPOINT, and AWS_ENDPOINT_URL environment variables.

  5. The service-specific endpoint value provided by the endpoint_url setting within a services section of the shared config file.

  6. The value provided by the endpoint_url setting within a profile of the shared config file.

  7. use_dualstack_endpoint, use_fips_endpoint, and endpoint_url settings.

  8. Any default endpoint URL for the respective Amazon Web Services service is used last. For a list of the standard service endpoints available in each Region, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.

AWS_USE_FIPS_ENDPOINT

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:

  1. The --endpoint-url command line option.

  2. If enabled, the AWS_IGNORE_CONFIGURED_ENDPOINT_URLS global endpoint environment variable or profile setting ignore_configure_endpoint_urls to ignore custom endpoints.

  3. The value provided by a service-specific environment variable AWS_ENDPOINT_URL_<SERVICE>, such as AWS_ENDPOINT_URL_DYNAMODB.

  4. The values provided by the AWS_USE_DUALSTACK_ENDPOINT, AWS_USE_FIPS_ENDPOINT, and AWS_ENDPOINT_URL environment variables.

  5. The service-specific endpoint value provided by the endpoint_url setting within a services section of the shared config file.

  6. The value provided by the endpoint_url setting within a profile of the shared config file.

  7. use_dualstack_endpoint, use_fips_endpoint, and endpoint_url settings.

  8. Any default endpoint URL for the respective Amazon Web Services service is used last. For a list of the standard service endpoints available in each Region, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.

AWS_WEB_IDENTITY_TOKEN_FILE

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.

Used with the AWS_ROLE_ARN and AWS_ROLE_SESSION_NAME environment variables.

If defined, this environment variable overrides the value for the profile setting web_identity_token_file.

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

Note

This environment variable only applies to an assumed role with web identity provider it does not apply to the general assume role provider configuration.