lstk Lifecycle Commands

lstk uses a flat command structure. Running lstk with no command is equivalent to lstk start.

start

Start the LocalStack emulator. In an interactive terminal, lstk start launches the TUI; otherwise, it prints plain output. lstk start launches the emulator defined in the [[containers]] block of the resolved config.toml, and refuses to start when the file has more than one block.

lstk start
lstk start --non-interactive

Option	Description
--type <type>, -t <type>	Select the emulator to start (azure) non-interactively, recording the choice in config.toml. See Selecting the emulator with --type.
--timeout <duration>	Maximum time to wait for the emulator to become ready, as a Go duration (e.g. 90s, 2m). Overrides LSTK_STARTUP_TIMEOUT for this run; 0 uses the per-mode default.
--non-interactive	Disable the interactive TUI and use plain output

lstk start forwards host environment variables prefixed with LOCALSTACK_ to the emulator (the host LOCALSTACK_AUTH_TOKEN is dropped so it cannot override the token lstk resolved). The Azure emulator reads a prefixed variable the same way as the plain one, so LOCALSTACK_LS_AZURE_PORTAL=1 lstk start enables the Azure Portal Emulator for that run. See Container-injected variables.

lstk applies a readiness deadline while waiting for the emulator to come up (a crash during startup is detected instantly, with its exit code, and does not wait for the deadline). In an interactive terminal the deadline defaults to 20 seconds and is only a recoverable prompt — you can keep waiting or stop; in non-interactive mode it defaults to 60 seconds and is fatal, leaving the container running for inspection. Override the deadline for a single run with --timeout (a Go duration such as 90s or 2m), or for every run with LSTK_STARTUP_TIMEOUT; an explicit --timeout wins over the environment variable, and --timeout 0 falls back to the per-mode default. The flag is available on start and the bare lstk command only — restart does not expose it.

start supports --json (as does the bare lstk command, which reports "command": "start"): the data payload is a flat object describing the started emulator, its emulator type, container name, endpoint, version, persistence setting, and whether it was alreadyRunning.

Selecting the emulator with --type

--type (shorthand -t, also available on the bare lstk command) is the non-interactive answer to the first-run emulator picker. It selects which emulator to start and records the choice in config.toml, so lifecycle commands (stop, status, logs, volume) stay in sync with what you started.

# Start the Azure emulator, recording the choice in config
lstk start --type azure

# Shorthand
lstk start -t azure

• On first run, the config is created with the selected type.
• If the configured type already matches, --type is a no-op.
• If it differs, lstk rewrites the type line in place (comments and formatting preserved) and prints a note naming the config file.

When switching an existing config to a different type:

• A custom image is a hard error — it pins a specific product that cannot be reinterpreted under a new emulator type. Use a separate config (--config) for that profile instead.
• A non-latest tag and any volume/volumes mounts are kept, but lstk warns that they may be product-specific.
• port, env, and snapshot are kept silently.

--type is a flag only; passing the emulator as a positional (lstk start azure) is rejected with a hint pointing at --type.

stop

Stop the running LocalStack emulator. lstk stop stops every emulator container defined in the resolved config.toml (the [[containers]] entries), with a 30-second stop timeout per container.

lstk stop
lstk stop --non-interactive

stop fails fast if Docker is not reachable (Docker is not available), or if a configured emulator is not currently running (LocalStack Azure Emulator is not running). In an interactive terminal it shows an animated “Stopping LocalStack…” spinner and a styled confirmation; in non-interactive mode it prints the same progress and result as plain text.

stop supports --json: the data payload lists each configured emulator and whether it wasRunning.

restart

Stop and restart the LocalStack emulator. lstk restart stops the running emulator and then starts a new container, using the same auth, config, and Docker settings as start. In an interactive terminal, it launches the TUI; otherwise, it prints plain output.

lstk restart

Emulator state is not retained across the restart; the container starts clean. restart also accepts --persist, but the Azure emulator doesn’t keep its state either way.

status

Show the status of a running emulator. Before contacting the emulator, lstk checks that Docker is reachable; if it is not, the command reports Docker is not available and exits with a non-zero status.

lstk status
lstk --non-interactive status

For each emulator configured in your config.toml (the [[containers]] entries), status reports whether it is running and, if so, prints an instance summary:

✔︎ LocalStack Azure Emulator is running
• Endpoint: localhost.localstack.cloud:4566
• Container: localstack-azure
• Version: 2026.9.0.dev419:0798fbf17
• Uptime: 46s

• Endpoint is the live host:port, queried from Docker, so it stays correct even if the configured port was changed while the container kept running.
• Uptime is computed from the container’s start time and is omitted if it cannot be determined.

If an emulator is not running, status prints an error and exits non-zero without checking the remaining emulators:

Error: LocalStack Azure Emulator is not running
  ==> Start LocalStack: lstk
  ==> See help: lstk -h

For the Azure emulator, status shows the instance summary only. Listing deployed resources is available for the AWS emulator only; to see what you have deployed on Azure, run lstk az resource list. In an interactive terminal the output is rendered through the TUI; in non-interactive mode (or with --non-interactive) the same content is printed as plain text.

status supports --json: the data payload lists one entry per configured emulator with its running state, health, container name, version, host, uptime, and persistence setting. --json also honors --endpoint-url to report on an emulator lstk did not start.

logs

Show or stream emulator logs.

lstk logs [options]

Option	Description
--follow, -f	Stream logs in real-time. Without this flag, lstk prints the currently available logs and exits.
--verbose, -v	Show all logs without filtering. By default, lstk drops noisy lines (internal request logs, provider chatter); --verbose shows every line verbatim.
--tail <N>, -n <N>	Show only the last N lines from the end of the logs, counting only the lines that pass the noise filter. Accepts a non-negative integer or all (the default, showing all available lines).

By default, lstk logs reads from the first configured emulator container and applies a noise filter. In an interactive terminal, lines are color-coded by log level (DEBUG, INFO, WARN, ERROR); in non-interactive mode, the same filtered lines are written to stdout without color.

Example:

# Print current filtered logs and exit
lstk logs

# Stream filtered logs in real-time
lstk logs --follow

# Show only the last 100 lines
lstk logs --tail 100

# Stream all logs without filtering
lstk logs --follow --verbose

volume

Manage the emulator volume: the host directory mounted at /var/lib/localstack, which holds the files the emulator writes, such as its certificates and its cached license.

lstk volume path
lstk volume clear [options]

volume path

lstk volume path prints the resolved volume directory for every emulator in your config, one per line. With a single [[containers]] block it prints one path. Each path is the container’s configured volume value, or the default OS cache location if volume is unset (~/Library/Caches/lstk/volume/localstack-azure on macOS, ~/.cache/lstk/volume/localstack-azure on Linux).

# Print the volume directory for each configured emulator
lstk volume path

volume clear

lstk volume clear removes all data from the emulator volume directory, resetting cached state. It operates on all configured emulators by default, or a single one with --type. Before clearing, it lists each target as <emulator>: <path> (<size>).

Option	Description
--force	Skip the confirmation prompt
--type <type>	Clear only the emulator of this type

# Clear all configured emulator volumes (prompts for confirmation)
lstk volume clear

# Clear only the Azure emulator volume
lstk volume clear --type azure

# Skip the confirmation prompt
lstk volume clear --force

# Clear without prompting in a non-interactive environment
lstk volume clear --type azure --force

In an interactive terminal, lstk volume clear prompts Clear volume data? This cannot be undone before deleting anything; choosing NO or pressing Ctrl+C cancels with no changes. In non-interactive mode, --force is required, otherwise the command fails with volume clear requires confirmation; use --force to skip in non-interactive mode.

Caution

With Docker Engine on Linux, the files that the emulator writes to the volume are owned by root on your host. lstk volume clear then fails with a permission error that ends with some files are owned by root (created by Docker); try: sudo lstk volume clear. You can delete the files from a container instead, which needs no sudo:

docker run --rm -v "$(lstk volume path):/volume" alpine find /volume -mindepth 1 -delete