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.

Use endpoints in the Amazon CLI

To connect programmatically to an Amazon Web Service, you use an endpoint. An endpoint is the URL of the entry point for an Amazon web service. The Amazon Command Line Interface (Amazon CLI) automatically uses the default endpoint for each service in an Amazon Web Services Region, but you can specify an alternate endpoint for your API requests.

Set endpoint for a single command

To override any endpoint settings or environment variables for a single command, use the --endpoint-url command line option. The following command example uses a custom Amazon S3 endpoint URL.

$ aws s3 ls --endpoint-url http://localhost:4567

Set global endpoint for all Amazon Web Services

To route requests for all services to a custom endpoint URL, use one of the following settings:

Service-specific endpoints and the --endpoint-url command line option override any global endpoints.

Set to use FIPs endpoints for all Amazon Web Services

To route requests for all services to use FIPs endpoints, use one of the following:

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.

Set to use dual-stack endpoints for all Amazon Web Services

To route requests for all services to use dual-stack endpoints when available, use one of the following settings:

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.

Set service-specific endpoints

Service-specific endpoint configuration provides the option to use a persistent endpoint of your choosing for Amazon CLI requests. These settings provide flexibility to support local endpoints, VPC endpoints, and third-party local Amazon development environments. Different endpoints can be used for testing and production environments. You can specify an endpoint URL for individual Amazon Web Services.

Service-specific endpoints can be specified in the following ways:

Service-specific endpoints: Environment variables

Environment variables override settings in your config file, but do not override options specified on the command line. Use environment variables if you want all profiles to use the same endpoints on your device.

The following are service-specific environment variables:

For more information on setting environment variables, see Environment variables to configure the Amazon CLI.

Service-specific endpoints: Shared config file

In the shared config file, endpoint_url is used in multiple sections. To set a service-specific endpoint, use the endpoint_url setting nested under a service identifier key within a services section. For details on defining a services section in your shared config file, see Section type: services.

The following example uses a services section to configure a service-specific endpoint URL for Amazon S3 and a custom global endpoint used for all other services:

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

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

A single profile can configure endpoints for multiple services. The following example sets the service-specific endpoint URLs for Amazon S3 and Amazon Elastic Beanstalk in the same profile.

For a list of all service identifier keys to use in the services section, see List of service-specific identifiers.

[profile dev1]
services = testing-s3-and-eb

[services testing-s3-and-eb]
s3 = 
  endpoint_url = http://localhost:4567
elastic_beanstalk = 
  endpoint_url = http://localhost:8000

The service configuration section can be used in multiple profiles. The following example has two profiles use the same services definition:

[profile dev1]
output = json
services = testing-s3

[profile dev2]
output = text
services = testing-s3

[services testing-s3]
s3 = 
  endpoint_url = https://localhost:4567

Service-specific endpoints: List of service-specific identifiers

The Amazon Web Service identifier is based on the API model’s serviceId by replacing all spaces with underscores and lowercasing all letters.

The following service identifier example uses Amazon Elastic Beanstalk. Amazon Elastic Beanstalk has a serviceId of Elastic Beanstalk, therefore the service identifier key is elastic_beanstalk.

The following table lists all service-specific identifiers, config file keys, and environment variables.

Endpoint configuration and settings precedence

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: