Docs / CLI Commands

CLI Commands

Complete reference for the localemu and awsemu command-line tools.

localemu start

Start the LocalEmu emulator. All services become available on the gateway port.

Usage
$ localemu start [options]
Option Description
-d Run in detached (background) mode. Returns control to the terminal immediately.
--host <host> Bind address. Default: 0.0.0.0
--port <port> Gateway port. Default: 4566
Examples
# Start in the foreground
$ localemu start
LocalEmu version: 1.0.0
Ready.

# Start in the background
$ localemu start -d
LocalEmu running in background (PID: 12345)

# Start on a custom port
$ localemu start --port 5000
Listening on 0.0.0.0:5000
Ready.

# Start on a specific interface
$ localemu start --host 127.0.0.1 --port 4566

localemu stop

Stop the running LocalEmu instance.

Usage
$ localemu stop
LocalEmu stopped.

localemu status

Check whether LocalEmu is running and display per-service availability.

Usage
$ localemu status
LocalEmu is running (version: 1.0.0)

  ✓ s3: available
  ✓ sqs: available
  ✓ dynamodb: available
  ✓ lambda: available
  ✓ iam: available
  ...

# Check a specific port
$ localemu status --port 5000

# When not running
$ localemu status
LocalEmu is not running.

localemu services

List every supported service in a column grid.

List all services
$ localemu services
LocalEmu supports 132 AWS services:

  s3                  sqs                 sns                 dynamodb
  lambda              iam                 sts                 kms
  cloudformation      cloudwatch          logs                events
  ...

Run 'localemu services <name>' to see operations for a service.

localemu services <name>

Show the implemented operations for a specific service.

Service detail
$ localemu services s3
s3 - 94 operations:

  CreateBucket           DeleteBucket           ListBuckets
  HeadBucket             GetBucketLocation      PutBucketPolicy
  PutObject              GetObject              DeleteObject
  ListObjectsV2          CopyObject             HeadObject
  ...

localemu ssh

SSH into a Docker-backed EC2 instance (requires EC2_VM_MANAGER=docker).

Usage
# Interactive shell
$ localemu ssh i-0abc123

# Run a one-shot command
$ localemu ssh i-0abc123 ls -la /

# List running instances
$ localemu ssh --list

localemu export / import

Snapshot live LocalEmu state to Terraform, CloudFormation, or a JSON snapshot. Replay a snapshot into another LocalEmu instance (or, for Terraform output, deploy against real AWS). See the Export page for the full pipeline.

Usage
# Export to Terraform HCL
$ localemu export --format terraform --output ./snapshot/

# Export to CloudFormation
$ localemu export --format cloudformation --output ./stack.yaml

# Re-apply a JSON snapshot to a fresh LocalEmu
$ localemu import ./snapshot.json

localemu --version

Print the installed version.

Version
$ localemu --version
localemu, version 1.0.0

awsemu <command>

Run any AWS CLI command against LocalEmu. awsemu is a wrapper that automatically sets the endpoint, region, and credentials. Every AWS CLI subcommand is supported.

Usage
$ awsemu <service> <command> [options]
Examples
$ awsemu s3 ls
$ awsemu sqs list-queues
$ awsemu dynamodb list-tables
$ awsemu lambda list-functions
$ awsemu sns list-topics
$ awsemu iam list-users
$ awsemu secretsmanager list-secrets
$ awsemu cloudformation list-stacks

See the awsemu CLI page for detailed usage and more examples.

Quick Reference

Command Description
localemu start Start in the foreground
localemu start -d Start in the background
localemu stop Stop the emulator
localemu status Check if running
localemu services List all services
localemu services s3 Show operations for a service
localemu ssh i-0abc123 SSH into a Docker-backed EC2 instance
localemu export --format terraform Snapshot state to Terraform / CFN / JSON
localemu import snapshot.json Replay a JSON snapshot
localemu --version Print version
awsemu <anything> Run any AWS CLI command against LocalEmu
← Configuration EC2 Docker Instances →