AWS CLI

Introduction

The AWS Command Line Interface (CLI) is the standard tool from Amazon for creating and managing AWS services via a command line interface. Due to LocalStack’s compatibility with the AWS APIs, this tool can also access LocalStack’s emulated services.

You can use the AWS CLI with LocalStack using one or more of the following approaches:

• AWS CLI - Use the standard aws command with hand-crafted configuration options necessary to communicate with LocalStack.
• LocalStack AWS CLI - Use the lstk aws command to set the configuration options for you.
• Using AWS CLI from a pre-built container - Use Amazon’s pre-built AWS CLI container image instead of installing aws locally.

Note

lstk aws supersedes the older awslocal wrapper script, which is deprecated but still available if you need it.

AWS CLI

If you don’t already have aws (version 2) installed, follow the official AWS CLI installation instructions.

Once installed, you can configure the AWS CLI to redirect AWS API requests to LocalStack using two approaches:

• Configuring an endpoint URL
• Configuring a custom profile

Configuring an endpoint URL

You can use AWS CLI with an endpoint URL by configuring environment variables and including the --endpoint-url=<localstack-url> flag in your aws CLI commands. 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.localstack.cloud:4566 kinesis list-streams

Note

To enable the creation of pre-signed URLs for S3 buckets, please set both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to the value “test.” Our pre-signed URL signature verification algorithm validates the pre-signed URL and its expiration.

Configuring a custom profile

You can configure a custom profile to use with LocalStack. Add the following profile to your AWS configuration file (by default, this file is at ~/.aws/config):

[profile localstack]
region=us-east-1
output=json
endpoint_url = http://localhost.localstack.cloud:4566

Add the following profile to your AWS credentials file (by default, this file is at ~/.aws/credentials):

[localstack]
aws_access_key_id=test
aws_secret_access_key=test

You can now use the localstack profile with the aws CLI:

aws s3 mb s3://test --profile localstack
aws s3 ls --profile localstack

Tip

Alternatively, you can also set the AWS_PROFILE=localstack environment variable, in which case the --profile localstack parameter can be omitted in the commands above.

LocalStack AWS CLI (lstk aws)

lstk aws serves as a thin wrapper and a substitute for the standard aws command, enabling you to run AWS CLI commands within the LocalStack environment without specifying the --endpoint-url parameter or a profile.

Installation

To make use of lstk aws, you must install both the lstk CLI and the standard aws command from Amazon.

1. To install lstk, follow the lstk installation instructions.
2. To install aws, follow the official AWS CLI installation instructions.

Usage

The lstk aws command shares identical usage with the standard aws command. For comprehensive usage instructions, refer to the manual pages by running lstk aws help.

lstk aws kinesis list-streams

Using AWS CLI from a pre-built container

As an alternative to installing the aws command directly on your local machine, Amazon provides a pre-built container image with the AWS CLI pre-installed. This approach is most suitable when working in multi-container environments, rather than single-machine installations. If you take this approach, an extra step is required for communication with LocalStack, also running inside a container.

By default, the AWS CLI container is isolated from 0.0.0.0:4566 on the host machine, which means the AWS CLI cannot reach LocalStack. To ensure the two docker containers can communicate create a network on the docker engine:

docker network create localstack
0c9cb3d37b0ea1bfeb6b77ade0ce5525e33c7929d69f49c3e5ed0af457bdf123

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

networks:
  default:
    external:
      name: 'localstack'

Run the 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": []
}