awscli-local

0.22.2 · active · verified Fri Apr 10

awscli-local is a thin Python wrapper around the standard 'aws' command-line interface (CLI) that enables seamless interaction with LocalStack, a cloud service emulator. It allows developers to execute AWS CLI commands against their local LocalStack instance without needing to explicitly specify the `--endpoint-url` parameter. The current version is 0.22.2, and it is actively maintained by the LocalStack team, receiving regular updates.

Warnings

breaking Automatic installation of AWS CLI version 2 (AWS CLI v2) is not directly supported via `pip install awscli-local[ver2]` because AWS CLI v2 is not officially available as a PyPI package. While `awslocal` can technically work with a manually installed AWS CLI v2, it's generally recommended to stick with AWS CLI v1 (installed via `awscli-local[ver1]`) to avoid potential issues and limitations.
Fix: Use `pip install awscli-local[ver1]` to install the wrapper with AWS CLI v1. If AWS CLI v2 is desired, install it separately (e.g., using the official AWS installer) and ensure `awslocal`'s PATH is correctly configured. Be aware of known limitations, particularly for CloudFormation.
gotcha After installing `awscli-local` via pip, users might encounter 'awslocal: command not found'. This typically means the executable's location is not in the system's PATH environment variable, or the shell hasn't refreshed its PATH after installation.
Fix: Ensure the directory where `awslocal` is installed (e.g., `~/.local/bin` for user installs, or a virtual environment's `bin` directory) is included in your PATH. Reload your shell by sourcing its configuration file (e.g., `source ~/.bashrc` or `source ~/.zshrc`) or by opening a new terminal window.
deprecated Environment variables `LOCALSTACK_HOST` and `USE_SSL` are deprecated for configuring the LocalStack endpoint. They have been replaced by `AWS_ENDPOINT_URL`.
Fix: Use the `AWS_ENDPOINT_URL` environment variable (e.g., `export AWS_ENDPOINT_URL=http://localhost:4566`) instead of `LOCALSTACK_HOST` or `USE_SSL`.
breaking There is a known limitation when using AWS CLI v2 for `cloudformation package` commands: it is not possible to specify the S3 endpoint URL. This issue affects deploying CloudFormation templates with S3 assets via `awslocal` when backed by AWS CLI v2.
Fix: The recommended workaround is to downgrade to AWS CLI v1 for `cloudformation` commands by installing `awscli-local[ver1]`. Alternatively, for advanced use cases, consider directly interacting with LocalStack's S3 service for asset storage.

Install

pip install awscli-local[ver1] Recommended (includes AWS CLI v1)
pip install awscli-local Wrapper only (manage AWS CLI separately)

Quickstart

This quickstart demonstrates creating and listing an S3 bucket using the `awslocal` command, assuming LocalStack is already running on your machine. This eliminates the need for `--endpoint-url` on most commands.

# First, ensure LocalStack is running (e.g., via `localstack start` or Docker).
# Then, use awslocal as you would aws, but interacting with your local services.
awslocal s3 mb s3://my-local-bucket
awslocal s3 ls

view raw JSON →