How to use a custom endpoint URL in AWS CLI

A custom endpoint URL sends one AWS CLI command to a different service host without changing the normal endpoint path used by later commands. That is useful for local S3-compatible storage, private service gateways, VPC endpoints, and test environments that should not become the shell default.

Current AWS CLI v2 documentation treats --endpoint-url as the explicit per-command endpoint override. It takes precedence over endpoint values from AWS_ENDPOINT_URL, service-specific AWS_ENDPOINT_URL_<SERVICE> variables, and saved endpoint_url settings in the shared config file, while credentials, signing, and normal service arguments still apply.

The override must be a full URL that includes the scheme and host, and AWS also allows an optional path component when the request must pass through a staged proxy or gateway path. A valid Region is still required for many signed requests even when the endpoint is private or local, and internal HTTPS endpoints should use --ca-bundle or AWS_CA_BUNDLE instead of disabling certificate checks.

1. Run the target AWS CLI command with --endpoint-url and the full custom URL that should receive the request.

   $ aws --region us-east-1 s3 ls --endpoint-url http://127.0.0.1:9000
   2026-04-19 20:47:36 demo-bucket
   2026-04-19 20:47:36 logs-bucket

   The command-line option changes only the destination URL for that request, so credentials, signing, and service behavior still follow the normal rules for the selected service.

2. Repeat the command with --debug when the effective endpoint must be confirmed before troubleshooting anything else.

   $ aws --region us-east-1 s3 ls --endpoint-url http://127.0.0.1:9000 --debug
   2026-04-19 20:47:57,905 - MainThread - botocore.regions - DEBUG - Endpoint provider result: http://127.0.0.1:9000
   2026-04-19 20:47:57,906 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=ListBuckets) with params: {'url': 'http://127.0.0.1:9000/',
   ##### snipped #####
   2026-04-19 20:47:57,909 - MainThread - urllib3.connectionpool - DEBUG - http://127.0.0.1:9000 "GET / HTTP/1.1" 200 463

   The debug trace shows both the resolved endpoint and the final request URL, which is the quickest proof that the override took effect.

3. Keep --endpoint-url on the command line when a saved or exported endpoint must be bypassed for one request.

   $ AWS_ENDPOINT_URL=http://127.0.0.1:9001 aws --region us-east-1 s3 ls --endpoint-url http://127.0.0.1:9000
   2026-04-19 20:47:36 demo-bucket
   2026-04-19 20:47:36 logs-bucket

   The command-line endpoint overrides the global AWS_ENDPOINT_URL value for that one command, which matches current AWS endpoint precedence.

4. Add --ca-bundle when the custom endpoint uses HTTPS with an internal or private certificate authority.

   $ aws --region us-east-1 s3 ls --endpoint-url https://storage.internal.example.com --ca-bundle /etc/ssl/certs/company-root-ca.pem

   Using --no-verify-ssl hides certificate trust failures and should stay limited to short troubleshooting, not normal operation.