awsemu vs AWS CLI

awsemu is a drop-in replacement for the AWS CLI. Every command, subcommand, and option from aws works identically with awsemu. The only difference is that awsemu automatically targets your local LocalEmu instance.

How It Works

• • awsemu automatically sets --endpoint-url=http://localhost:4566 on every call
• • Credentials are pre-set to the AWS-published example pair (AKIAIOSFODNN7EXAMPLE with the matching example secret). The pair is in ROOT_ACCESS_KEYS by default, so it works even under IAM_ENFORCEMENT=1.
• • Everything from aws help works with awsemu
• • Any AWS CLI guide, tutorial, or StackOverflow answer applies directly. Just replace aws with awsemu

# AWS CLI (real AWS)
$ aws s3 ls
$ aws sqs create-queue --queue-name my-queue

# awsemu (LocalEmu) - identical syntax
$ awsemu s3 ls
$ awsemu sqs create-queue --queue-name my-queue

Service-Specific Notes

While awsemu is a drop-in replacement, some services have LocalEmu-specific behaviors worth knowing about.

EC2

• • Use LocalEmu AMI IDs like ami-ubuntu-22.04, ami-ubuntu-20.04, or ami-debian-12 instead of real AMI IDs
• • The SSH port for an instance is returned in the localemu:ssh-port tag

$ awsemu ec2 run-instances \
    --image-id ami-ubuntu-22.04 \
    --instance-type t2.micro \
    --count 1

# SSH port is in the tags
$ awsemu ec2 describe-instances \
    --query 'Reservations[].Instances[].Tags[?Key==`localemu:ssh-port`].Value'

RDS

• • Endpoint.Address is localhost
• • Endpoint.Port is the Docker-mapped port on the host

$ awsemu rds create-db-instance \
    --db-instance-identifier mydb \
    --engine postgres \
    --master-username admin \
    --master-user-password secret123

# Connect with psql using the returned endpoint
$ awsemu rds describe-db-instances \
    --query 'DBInstances[0].Endpoint'
Address: localhost
Port: 49267  # Dynamically assigned; check DescribeDBInstances

OpenSearch

• • Domain endpoint is localhost:<port> where the port is dynamically assigned

$ awsemu opensearch create-domain --domain-name my-domain

# Get the domain endpoint
$ awsemu opensearch describe-domain \
    --domain-name my-domain \
    --query 'DomainStatus.Endpoint'
localhost:43215

Cognito

• • JWKS endpoint is available at http://localhost:4566/<pool-id>/.well-known/jwks.json

$ POOL_ID=$(awsemu cognito-idp create-user-pool \
    --pool-name my-pool \
    --query 'UserPool.Id' --output text)

# Fetch the JWKS for token verification
$ curl http://localhost:4566/$POOL_ID/.well-known/jwks.json

SSM Session Manager

awsemu ssm start-session is intercepted by LocalEmu. Instead of connecting through the real SSM agent, it runs docker exec to open an interactive shell inside the EC2 instance container.

# Opens an interactive shell inside the EC2 container
$ awsemu ssm start-session --target i-345e9b5f68e616e47
root@i-345e9b5f68e616e47:/#

localemu ssh is an alternative that works the same way:

$ localemu ssh i-345e9b5f68e616e47
root@i-345e9b5f68e616e47:/#

Quick Reference