lstk CLI

Introduction

lstk is a 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 run Azure 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 the Azure CLI, so that lstk az commands run directly against LocalStack. It proxies Terraform, the AWS CLI, the AWS CDK, and the AWS SAM CLI too, but those proxies need the AWS emulator.

This section is split into focused pages:

• Overview (this page): installation, quick start, global options, 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, volume.
• Cloud & IaC commands: az.
• Automation & CI: non-interactive mode, structured output, targeting an external emulator, and environment variables.
• Setup & maintenance: setup, config, update, and offline/enterprise environments.
• Migration guide: moving from the localstack CLI and azlocal to lstk.
• Doctor: checking that your machine and network can run LocalStack.
• FAQ & Troubleshooting.

Prerequisites

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

Installation

Homebrew (macOS/Linux)

brew install localstack/tap/lstk

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

npm

npm install -g @localstack/lstk

Pre-built binaries

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: it authenticates you, pulls the emulator image, and starts the LocalStack container. With the default latest tag, lstk checks for a newer image on every start and downloads it only when there is one. 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: choose z for Azure. It writes your choice to config.toml, so later runs start the Azure emulator right away. See Emulator types for details.

For CI or headless environments, set LOCALSTACK_AUTH_TOKEN, use --non-interactive, and select the emulator with --type azure, because there is no prompt to answer:

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

CI environments require a CI Auth Token; a personal Developer Auth Token cannot be used there (see CI Environments).

Global options

These options are available for all commands:

Option	Description
--config <path>	Path to a specific TOML config file
--endpoint-url <url>	Target an existing, externally-managed emulator at this URL instead of discovering one via local Docker. See Targeting an external emulator.
--non-interactive	Disable the interactive TUI, use plain output
--json	Emit a single machine-readable JSON envelope on stdout instead of human-oriented output. Supported by the bare lstk, start, stop, status, update, and doctor; other commands reject it. See Structured output.
--type <type>, -t <type>	Emulator type to start: azure for LocalStack for Azure (aws and snowflake select the other emulators). Works on start and the bare lstk, and records the choice in the config. See Selecting the emulator with --type.
--timeout <duration>	Startup readiness deadline for start/bare lstk, as a Go duration; overrides LSTK_STARTUP_TIMEOUT for one run. See start.
-v, --version	Print the version and exit
-h, --help	Print help and exit

These apply to both interactive and non-interactive (scripted/CI) use, see Automation & CI for the details behind --non-interactive, --json, and --endpoint-url.

lstk --help also lists --persist, --snapshot, and --no-snapshot. They have no use with the Azure emulator: it doesn’t keep its state across restarts, and loading a snapshot on start works for the AWS emulator only.

Shell completions

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

completion

Generate shell completion scripts.

lstk completion [bash|zsh|fish|powershell]

Run lstk completion to print setup instructions in your terminal.