Why --endpoint Doesn't Work in AWS CLI (And What to Use Instead)

Why --endpoint Doesn't Work in AWS CLI (And What to Use Instead)

Aaron Rose    

Software Engineer & Technology Writer

Problem

A developer noticed that aws --endpoint http://aws:4566 iam list-users fails with an "unknown option" error, while aws --endpoint-url http://aws:4566 iam list-users works perfectly. The question arose: is --endpoint a valid AWS CLI flag? Was it ever supported or has it been deprecated?

Clarifying the Issue

The --endpoint flag has never been a recognized or supported option in the AWS CLI. Only --endpoint-url is documented and functional in the official AWS CLI specification. Any perceived functionality of --endpoint is likely due to shell aliases, custom wrapper scripts, or modified CLI installations in specific environments.

Why It Matters

Using undocumented flags creates brittle automation that fails unpredictably across different environments. When teams share Docker containers, CI/CD pipelines, or LocalStack configurations, inconsistent CLI usage leads to debugging headaches and deployment failures. This has been a persistent developer pain point—AWS received requests for better endpoint configuration as far back as 2015, eventually adding configuration file support to address these workflow challenges.

Key Terms

• AWS CLI – Amazon's official command-line interface for managing AWS services
• LocalStack – A local testing framework that mocks AWS services for development
• --endpoint-url – The correct and only supported AWS CLI flag for overriding service endpoints
• Container DNS – Internal hostnames like http://aws:4566 used in Docker Compose setups

Steps at a Glance

1. Use --endpoint-url for all endpoint specifications
2. Test the incorrect flag to confirm the error
3. Verify your AWS CLI version is current
4. Check for shell aliases that might mask the issue
5. Update all scripts and documentation

Detailed Steps

Step 1: Use the correct flag in your commands

Replace any instances of --endpoint with --endpoint-url: 

bash

# ✅ Correct
aws --endpoint-url http://aws:4566 iam list-users

# ❌ Incorrect - will fail
aws --endpoint http://aws:4566 iam list-users  

The correct command should return your LocalStack IAM users without errors.

Step 2: Test the incorrect flag to confirm the error

Run the problematic command to verify the expected failure: 

bash

aws --endpoint http://aws:4566 iam list-users 

You should see: 

bash

unknown option: --endpoint 

This confirms that --endpoint is not recognized by the AWS CLI.

Step 3: Verify your AWS CLI version is current

Check that you're running a supported version: 

bash

aws --version

Ensure you're using AWS CLI v2.x or a recent v1.x release. Older versions may exhibit different behavior or lack certain features.

Step 4: Check for shell aliases or wrapper functions

If --endpoint appeared to work previously, investigate potential aliases:

bash

alias aws
type aws
which aws

Look for custom functions or aliases that might intercept the aws command and translate --endpoint to --endpoint-url behind the scenes.

Step 5: Update all scripts and documentation

Search your codebase for problematic usage and replace with the correct flag: 

bash

# Search for problematic usage
grep -r "\-\-endpoint[^-]" scripts/
grep -r "\-\-endpoint " scripts/

# Update Docker Compose files, shell scripts, and documentation

Consider using configuration files or environment variables for persistent endpoint settings: 

bash

# Environment variable approach
export AWS_ENDPOINT_URL=http://localhost:4566

# User-friendly configuration approach
aws configure set endpoint_url http://localhost:4566

# Manual configuration file approach (~/.aws/config)
[default]
endpoint_url = http://localhost:4566  

Conclusion

Always use --endpoint-url when working with LocalStack, custom AWS endpoints, or any non-standard service URLs. The --endpoint flag does not exist in the AWS CLI specification and should be avoided for consistency and portability. If teammates report different behavior, check for shell customizations or wrapper scripts rather than assuming CLI support. Standardizing on documented flags ensures reliable automation across all environments.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog.