lstk CLI

Introduction

lstk is a high-performance command-line interface for LocalStack, built in Go. It provides a built-in terminal UI (TUI) for interactive use and plain text output for CI/CD pipelines and scripting.

lstk handles the full emulator lifecycle: authentication, pulling the Docker image, starting, stopping, and restarting the container, streaming logs, and checking status. It can also save and load emulator state (as local snapshots or Cloud Pods) reset running state, run AWS CLI commands against the emulator, and manage the on-disk volume. Running lstk with no arguments takes you through the entire startup flow automatically.

lstk also proxies developer tools so they run directly against LocalStack: the AWS CLI (lstk aws), the Azure CLI (lstk az), Terraform (lstk terraform), the AWS CDK (lstk cdk), and the AWS SAM CLI (lstk sam).

This section is split into focused pages:

Overview (this page): installation, quick start, and shell completions.
Authentication: logging in and out, and how lstk resolves your auth token.
Configuration: the config.toml file, emulator types, environment variables, and volumes.
Lifecycle commands: start, stop, restart, status, logs, reset, volume.
AWS & IaC commands: aws, az, terraform, cdk, sam.
Snapshots: snapshot save/load/list/remove/show, and S3 remotes.
Automation & CI: global options, non-interactive mode, structured output, and environment variables.
Setup & maintenance: setup, config, update, and offline/enterprise environments.
FAQ & Troubleshooting.

Prerequisites

Docker installed and running.
A LocalStack account with a license, and lstk handles authentication for you (see Authentication).

Installation

brew install localstack/tap/lstk

Homebrew also installs shell completions for bash, zsh, and fish automatically.

npm install -g @localstack/lstk

Download the binary for your platform from GitHub Releases, extract it, and place it on your PATH.

Verify the installation:

lstk --version

Updating

lstk can update itself. It detects how it was originally installed (Homebrew, npm, or binary) and uses the matching update method:

# Check for updates without installing
lstk update --check

# Update to the latest version
lstk update

See the update command for details, including the start-time update notification.

Quick start

lstk

Running lstk without arguments performs the full startup sequence: authenticates you automatically, pulls the latest image if needed, and starts the LocalStack container. In an interactive terminal it launches the TUI; in a non-interactive environment it prints plain text output.

On the very first interactive run, lstk prompts you to pick which emulator to run (AWS, Snowflake, or Azure) and writes your choice to config.toml. See Emulator types for the available options.

For CI or headless environments, set LOCALSTACK_AUTH_TOKEN and use --non-interactive:

LOCALSTACK_AUTH_TOKEN=<your-ci-auth-token> lstk --non-interactive

CI environments require a CI Auth Token; a personal Developer Auth Token cannot be used there.

Shell completions

lstk includes completion scripts for bash, zsh, fish, and powershell. If you installed via Homebrew, completions are set up automatically.

For manual setup:

# Load in current session
eval "$(lstk completion bash)"

# Persist (Linux)
lstk completion bash > /etc/bash_completion.d/lstk

# Persist (macOS with Homebrew)
lstk completion bash > $(brew --prefix)/etc/bash_completion.d/lstk

# Load in current session
source <(lstk completion zsh)

# Persist (Linux)
lstk completion zsh > "${fpath[1]}/_lstk"

# Persist (macOS with Homebrew)
lstk completion zsh > $(brew --prefix)/share/zsh/site-functions/_lstk

# Load in current session
lstk completion fish | source

# Persist
lstk completion fish > ~/.config/fish/completions/lstk.fish

Restart your shell after persisting completions.

`completion`

Generate shell completion scripts.

lstk completion [bash|zsh|fish|powershell]

See Shell completions above for setup instructions.

Was this page helpful?