awscli-local (awslocal)

Since awslocal is compatible with the aws CLI completion feature, you can enable tab-completion for your shell.

For Bash: Add the following lines to your ~/.bashrc to register completion for both aws and awslocal:

complete -C '/usr/local/bin/aws_completer' aws
complete -C '/usr/local/bin/aws_completer' awslocal

For other shells: Follow the official AWS CLI guide for your specific shell and ensure you register the completion for awslocal as well.

The awslocal command is a thin wrapper around the aws CLI designed for use with LocalStack. You can install it via pip.

To install awslocal along with the latest AWS CLI version 1 (awscli), use:

pip install awscli-local[ver1]

If you are on macOS or using ZSH, use quotes around the package name:

pip install "awscli-local[ver1]"

If you already manage your own version of the AWS CLI (v1 or v2) and only want to install the awslocal wrapper script, use:

pip install awscli-local

You can control how awslocal connects to LocalStack using the following environment variables:

• AWS_ENDPOINT_URL: The endpoint URL to connect to. This takes precedence over LOCALSTACK_HOST and USE_SSL.
• LOCALSTACK_HOST (deprecated): A <hostname>:<port> variable defining the LocalStack location (defaults to localhost:4566).
• USE_SSL (deprecated): A boolean indicating whether to use SSL when connecting (defaults to False).

The awslocal CLI is a thin wrapper around the standard AWS CLI (aws). It simplifies interacting with LocalStack by automatically injecting the correct --endpoint-url for the service you are calling, so you don't have to specify it manually for every command.

Instead of running: aws --endpoint-url=https://localhost:4568 --no-verify-ssl kinesis list-streams

You can simply run: awslocal kinesis list-streams

When using CloudFormation package or deploy commands, awslocal attempts to ensure that S3 artifacts are also directed to the LocalStack endpoint.

Important Compatibility Note: If you are using AWS CLI v2, awslocal currently has limitations with the cloudformation package/deploy commands. If you encounter issues, it is recommended to install and use AWS CLI v1 via pip install awscli to ensure full compatibility with awslocal's patching mechanism.

There is a known limitation when using the cloudformation package ... command with AWS CLI v2: it is currently impossible to specify the S3 endpoint URL.

To resolve this, you have two options:

1. Recommended: Downgrade to the v1 AWS CLI.
2. Advanced (Not recommended): Install AWS CLI v2 from sources within a Python virtualenv to avoid system conflicts:

virtualenv .venv
. .venv/bin/activate
pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip

The awslocal command has the same usage as the standard aws CLI. It eliminates the need to manually specify the --endpoint-url for every command by automatically pointing requests to the LocalStack endpoint.

Example: Instead of specifying the endpoint manually:

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

You can simply run:

awslocal kinesis list-streams

The awslocal command follows the same subcommand structure as the AWS CLI. You can pass any standard AWS CLI subcommand or flag to awslocal.

To see the full help documentation for the underlying AWS CLI subcommands, run: awslocal aws help

Note: awslocal automatically handles endpoint injection for most services. However, for certain services like help or configure, it defaults to standard behavior without injecting a LocalStack endpoint.