How to use a custom endpoint URL in AWS CLI

Custom endpoint URLs let AWS CLI commands target local emulators, private service gateways, VPC interface endpoints, or S3-compatible storage without rewriting saved profile settings. That matters when one request has to leave the default AWS hostname path while the rest of the CLI workflow stays unchanged.

The AWS CLI normally resolves the destination host from the selected service and Region. Adding --endpoint-url replaces that resolved URL for the current invocation, while credentials, request signing, output formatting, and other CLI options keep following their usual precedence rules. The explicit command-line endpoint also takes priority over endpoint URLs loaded from environment variables or shared config.

The override must be a full URL with a scheme and host, and it can include a path when a proxy or staged gateway expects one. Some services still need an explicit Region even when the host is local or private, and internal HTTPS endpoints need a trusted CA bundle through --ca-bundle or AWS_CA_BUNDLE instead of disabling TLS verification.

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

   $ aws --profile demo --region us-east-1 s3 ls --endpoint-url http://127.0.0.1:9000
   2026-03-29 08:00:00 demo-bucket
   2026-03-29 08:05:00 logs-bucket

   The URL can include a path when the custom service expects one, such as https://gateway.example.com/dev//.</WRAP> - Repeat the command with --debug when the effective destination must be confirmed before investigating anything else. <code>$ aws –profile demo –region us-east-1 s3 ls –endpoint-url http://127.0.0.1:9000 –debug 2026-03-29 08:09:42,767 - MainThread - botocore.regions - DEBUG - Endpoint provider result: http://127.0.0.1:9000 2026-03-29 08:09:42,767 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=ListBuckets) with params: {'url': 'http://127.0.0.1:9000/', ##### snipped #####} 2026-03-29 08:09:42,768 - MainThread - urllib3.connectionpool - DEBUG - http://127.0.0.1:9000 “GET / HTTP/1.1” 200 423</code>

   The debug trace exposes both the resolved endpoint and the final request URL, which is the quickest way to prove that the override took effect.

   - Keep the normal service arguments, credentials, and Region handling that the operation already requires, because --endpoint-url changes the destination only. <code>$ aws –profile demo –region us-east-1 dynamodb list-tables –endpoint-url http://127.0.0.1:8000 $ aws –profile demo –region us-east-1 sts get-caller-identity –endpoint-url https://sts.internal.example.com</code>

   The override does not supply missing credentials, change permissions, or remove service-specific parameters that the command still needs.

   - Use the command-line endpoint when a saved or exported endpoint must be bypassed for one request, because the explicit --endpoint-url value wins over AWS_ENDPOINT_URL and shared-config endpoint settings. <code>$ AWS_ENDPOINT_URL=http://127.0.0.1:9001 aws –profile demo –region us-east-1 s3 ls –endpoint-url http://127.0.0.1:9000 2026-03-29 08:00:00 demo-bucket 2026-03-29 08:05:00 logs-bucket</code>

   Related: use environment variables in AWS CLI

   - Trust private HTTPS certificates explicitly instead of disabling TLS verification when the custom endpoint is signed by an internal CA. <code>$ aws –profile demo –region us-east-1 s3 ls –endpoint-url https://storage.internal.example.com –ca-bundle /etc/pki/anchors/storage-root-ca.pem</code>

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

   Related: set a custom CA bundle

   - Drop --endpoint-url from later commands when the request should return to the service's standard AWS endpoint for the selected Region. <code>$ aws –profile demo –region us-east-1 s3 ls –endpoint-url http://127.0.0.1:9000 2026-03-29 08:00:00 demo-bucket 2026-03-29 08:05:00 logs-bucket $ aws –profile demo –region us-east-1 s3 ls</code>

   The first command targets the custom host, while the second falls back to the normal endpoint resolution path for the profile and Region.