localstack · gtsiolis · Jul 23, 2026
@@ -340,12 +340,15 @@ lstk start --non-interactive
 | Option              | Description                                                                  |
 |:--------------------|:-----------------------------------------------------------------------------|
 | `--persist`         | Persist emulator state across restarts (sets `LOCALSTACK_PERSISTENCE=1` in the container) |
+| `--type <type>`, `-t <type>` | Select the emulator to start (`aws`, `snowflake`, or `azure`) non-interactively, recording the choice in `config.toml`. See [Selecting the emulator with `--type`](#selecting-the-emulator-with---type). |
 | `--snapshot <REF>`  | Auto-load this snapshot after the emulator starts, overriding the configured `snapshot` for one run (AWS only) |
 | `--no-snapshot`     | Skip auto-loading the configured `snapshot` for this run                      |
 | `--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). See [Container-injected variables](#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 with [`LSTK_STARTUP_TIMEOUT`](#environment-variables) (a Go duration such as `90s` or `2m`).
+
 By default the emulator starts with a fresh state on every run.
 Pass `--persist` to keep data across restarts: `lstk` injects `LOCALSTACK_PERSISTENCE=1` into the container so state is written to the mounted [`volume`](#config-field-reference) and reloaded on the next start.
 When persistence is active, the AWS emulator's startup summary includes a `• Persistence: Enabled` line.
@@ -360,6 +363,31 @@ lstk start --persist
 For finer-grained control, you can also set `PERSISTENCE = "1"` in an environment profile (see [Passing environment variables to the container](#passing-environment-variables-to-the-container)).
 :::
 
+#### 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 (`aws`, `snowflake`, or `azure`) and **records the choice in `config.toml`**, so lifecycle commands (`stop`, `status`, `logs`, `volume`, snapshot auto-load) stay in sync with what you started.
+
+```bash
+# Start the Snowflake emulator, recording the choice in config
+lstk start --type snowflake
+
+# 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`.
+
 #### Auto-loading a snapshot on start
 
 For the **AWS emulator**, you can have `lstk` load a snapshot automatically every time it starts the emulator.
@@ -478,6 +506,7 @@ lstk logs [options]
 |:------------|:-----------------------------------------|
 | `--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. 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, raw log lines are written to stdout.
@@ -491,6 +520,9 @@ 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
 ```
@@ -638,6 +670,10 @@ Like `lstk aws`, the `az`, `terraform`, `cdk`, and `sam` proxies do not start th
 Each requires the corresponding third-party CLI to be installed and on your `PATH`.
 :::
 
+:::note
+When you interrupt a proxied tool (for example Ctrl+C or `kill` during `lstk terraform apply`), `lstk` forwards the termination signal to the wrapped tool and waits for it to shut down cleanly rather than killing it outright, so operations like releasing a Terraform state lock can complete. The wrapped tool's real exit code is passed through unchanged.
+:::
+
 ### `snapshot`
 
 Manage emulator snapshots.
@@ -715,6 +751,8 @@ To load from S3, pass the pod name followed by an `s3://bucket/prefix` location
 - `overwrite`: running state is reset first, then the snapshot is imported onto a clean state.
 - `service-merge`: the snapshot wins per resource; non-overlapping resources are combined.
 
+Set [`LSTK_MERGE_STRATEGY`](#environment-variables) to change the default strategy used when `--merge` is not passed; an explicit `--merge` always wins.
+
 The aliases behave identically:
 
 ```bash
@@ -1083,6 +1121,8 @@ Set `LSTK_GITHUB_TOKEN` to send an authenticated GitHub request and avoid API ra
 It is optional; updates also work unauthenticated.
 :::
 
+If more than one `lstk` installation is found on your `PATH` (for example a Homebrew binary and an npm one), `lstk update` and the start-time update notification print a warning listing each location, its install method, and which one is currently running, so you can tell which binary an update will actually replace.
+
 #### Update notification on start
 
 Separately from `lstk update`, `lstk` checks for a newer version when you run `lstk start` (the default command), using a short timeout that fails silently if GitHub is unreachable.
@@ -1132,6 +1172,7 @@ These options are available for all commands:
 | `--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 `stop`, `reset`, and `update`; any other command rejects it. See [Structured output](#structured-output). |
 | `--persist`         | Persist emulator state across restarts (on `start`/bare `lstk` and `restart`) |
+| `--type <type>`, `-t <type>` | Emulator type to start: `aws`, `snowflake`, or `azure` (on `start`/bare `lstk`; records the choice in config). See [Selecting the emulator with `--type`](#selecting-the-emulator-with---type). |
 | `--snapshot <REF>`  | Snapshot REF to auto-load after start (on `start`/bare `lstk`; overrides config for one run) |
 | `--no-snapshot`     | Skip auto-loading the configured snapshot (on `start`/bare `lstk`)          |
 | `-v`, `--version`   | Print the version and exit                                                 |
@@ -1235,6 +1276,8 @@ The following environment variables configure `lstk` itself (not the LocalStack
 | `LOCALSTACK_DISABLE_EVENTS`  | Set to `1` to disable anonymous telemetry event reporting.                                                       |
 | `DOCKER_HOST`                | Override the Docker daemon socket (e.g. `unix:///home/user/.colima/default/docker.sock`).                        |
 | `LSTK_KEYRING`               | Set to `file` to force file-based token storage instead of the system keyring.                                   |
+| `LSTK_STARTUP_TIMEOUT`       | Startup readiness deadline for `lstk start`, as a Go duration (e.g. `90s`, `2m`). Zero/unset uses the per-mode default (20s interactive, 60s non-interactive). See [`start`](#start). |
+| `LSTK_MERGE_STRATEGY`        | Default merge strategy for `snapshot load` / `load` (`account-region-merge`, `overwrite`, or `service-merge`) when `--merge` is not passed. An explicit `--merge` always wins. |
 | `LSTK_OTEL`                  | Set to `1` to enable OpenTelemetry trace export (disabled by default). See [OpenTelemetry tracing](#opentelemetry-tracing). |
 | `LSTK_GITHUB_TOKEN`          | Optional GitHub token used when checking for or downloading `lstk` updates (raises GitHub API rate limits).      |
 | `LSTK_API_ENDPOINT`          | Override the LocalStack platform API base URL. Default: `https://api.localstack.cloud`.                          |
@@ -1313,7 +1356,7 @@ For manual setup:
 
 ```bash
 # Load in current session
-source <(lstk completion bash)
+eval "$(lstk completion bash)"
 
 # Persist (Linux)
 lstk completion bash > /etc/bash_completion.d/lstk
@@ -1322,6 +1365,11 @@ lstk completion bash > /etc/bash_completion.d/lstk
 lstk completion bash > $(brew --prefix)/etc/bash_completion.d/lstk
 ```
 
+:::note
+Use `eval "$(lstk completion bash)"` rather than `source <(lstk completion bash)`.
+The `lstk` script works with or without the `bash-completion` package (it bundles a fallback for stock macOS bash 3.2), but `source <(...)` is a silent no-op on that shell.
+:::
+
 </TabItem>
 <TabItem label="Zsh">