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

Using endpoints in the AWS CLI

To connect programmatically to an AWS service, you use an endpoint. An endpoint is the URL of the entry point for an AWS web service. The AWS Command Line Interface (AWS CLI) automatically uses the default endpoint for each service in an AWS 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 AWS 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 AWS services

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

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.

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.

For more information on specifying FIPS endpoints by AWS Region, see FIPS Endpoints by Service.

Set to use dual-stack endpoints for all AWS 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 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. 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 AWS CLI requests. These settings provide flexibility to support local endpoints, VPC endpoints, and third-party local AWS development environments. Different endpoints can be used for testing and production environments. You can specify an endpoint URL for individual AWS 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 Configuring environment variables for the AWS 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 AWS 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 AWS 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 AWS Elastic Beanstalk. AWS 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 AWS configuration files, or explicitly declared on the command line as a parameter. The AWS CLI endpoint configuration settings take precedence in the following order: