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

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