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
• • SSH via the instance's PrivateIpAddress, from a container on the same VPC network (see EC2: API reference)

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

# PrivateIpAddress is the connectable address
$ awsemu ec2 describe-instances \
    --query 'Reservations[].Instances[].PrivateIpAddress'

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

Use the real aws CLI for this one, not awsemu: with AWS_ENDPOINT_URL set, aws ssm start-session opens a genuine interactive shell against LocalEmu -- the wire codec matches the real session-manager-plugin byte-for-byte, no LocalEmu-specific interception.

$ export AWS_ENDPOINT_URL=http://localhost:4566
$ aws ssm start-session --target i-345e9b5f68e616e47
root@i-345e9b5f68e616e47:/#

localemu ssh is a lighter alternative: a direct docker exec into the instance's container, run from the host, no SSM protocol or key pair involved:

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

Quick Reference