AWS Command Line Interface

How to use the AWS Command Line Interface (CLI) with LocalStack.


The AWS Command Line Interface (CLI) is a unified tool to manage AWS services from the command line. All CLI commands that access services that are implemented in LocalStack can be run against LocalStack.

There are two CLI alternatives:


Use the below command to install aws, if not installed already.

$ pip install awscli

Setting up local region and credentials to run LocalStack

Configure AWS test environment variables and add the --endpoint-url=<localstack-url> flag to your aws CLI invocations. For example:

$ export AWS_ACCESS_KEY_ID="test"
$ export AWS_SECRET_ACCESS_KEY="test"
$ export AWS_DEFAULT_REGION="us-east-1"

$ aws --endpoint-url=http://localhost:4566 kinesis list-streams

Create a configuration profile. The configuration file will be created under ~/.aws directory and in the example below, using the default profile:

$ aws configure --profile default

Verify the current configuration:

aws configure list

LocalStack AWS CLI (awslocal)

awslocal is a thin wrapper and a drop-in replacement for the aws command that runs commands directly against LocalStack (no need to specify --endpoint-url anymore). The source code can be found on GitHub:


You can install the awslocal command via pip:

$ pip install awscli-local[ver1]

Note that the command above also installs the latest version of the underlying AWS CLI version 1 (awscli) package. Use this command if you prefer to manage your own version of awscli (e.g., v1/v2) and install the wrapper script only:

$ pip install awscli-local


The awslocal command has the same usage as the aws command. For detailed usage, please refer to the man pages of aws help.

awslocal kinesis list-streams


You can use the following environment variables for configuration:

LOCALSTACK_HOSTSet the hostname for the localstack instance. Useful when you have localstack is bound to another interface (i.e. docker-machine).
USE_SSLWhether to use https endpoint URLs (required if LocalStack has been started with USE_SSL=true enabled). Defaults to false.
DEFAULT_REGIONDeprecated. Set the default region. Overrides AWS_DEFAULT_REGION environment variable.

Verify the current configuration:

awslocal configure list


Please note that there is a known limitation for using the cloudformation package ... command with the AWS CLI v2. The problem is that the AWS CLI v2 is not available as a package on, but is instead shipped as a binary package that cannot be easily patched from awslocal. To work around this issue, you have 2 options:

  • Downgrade to the v1 AWS CLI (this is the recommended approach)
  • There is an unofficial way to install AWS CLI v2 from sources. We do not recommend this, but it is technically possible. Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system:
$ virtualenv .venv
$ . .venv/bin/activate
$ pip install

Please also note there is a known limitation for issuing requests using --no-sign-request with the AWS CLI. LocalStack’s routing mechanism depends on the signature of each request to identify the correct service for the request. Thus, adding the flag --no-sign-requests provokes your request to reach the wrong service. One possible way to address this is to use the awslocal CLI instead of AWS CLI.


Automatic installation of AWS CLI version 2 is currently not supported (at the time of writing there is no official pypi package for v2 available), but the awslocal technically also works with AWS CLI v2 (see this section for more details).

AWS CLI v2 with Docker and LocalStack

By default, the container running amazon/aws-cli is isolated from on the host machine, that means that aws-cli cannot reach localstack through your shell.

To ensure that the two docker containers can communicate create a network on the docker engine:

$ docker network create localstack

Then modify the docker-compose.yml specifying the network to use:

      name: "localstack"

Run AWS Cli v2 docker container using this network (example):

$ docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566 lambda list-functions
    "Functions": []

If you use AWS CLI v2 from a docker container often, create an alias:

$ alias laws='docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566'

So you can type:

$ laws lambda list-functions
    "Functions": []