From fd849869da4ec3e4af99e886f34368e8030dea0b Mon Sep 17 00:00:00 2001
From: George Tsiolis <george.tsiolis@localstack.cloud>
Date: Wed, 2 Sep 2026 10:32:34 +0000
Subject: [PATCH 01/10] docs(lstk): update CLI reference to v0.22.2

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../running-localstack/lstk/authentication.md | 12 +++----
 .../running-localstack/lstk/automation.mdx    | 26 ++++++++++++++-
 .../lstk/cloud-and-iac-commands.md            | 16 ++++++++++
 .../running-localstack/lstk/configuration.mdx |  4 +++
 .../running-localstack/lstk/index.mdx         |  4 +--
 .../running-localstack/lstk/snapshots.md      | 32 ++++++++++++++++---
 6 files changed, 81 insertions(+), 13 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/authentication.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/authentication.md
index 1b33f526..ce12432f 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/authentication.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/authentication.md
@@ -7,14 +7,14 @@ tags: ['Hobby']
 
 `lstk` resolves your auth token in the following order:
 
-1. **System keyring**: a token stored by a previous `lstk login`.
-2. **`LOCALSTACK_AUTH_TOKEN` environment variable**: used only when the keyring has no token.
+1. **`LOCALSTACK_AUTH_TOKEN` environment variable**: takes precedence over a stored token.
+2. **System keyring**: a token stored by a previous `lstk login`, used when the environment variable is not set.
 3. **Browser login**: triggered automatically in interactive mode when neither of the above provides a token.
 
-:::caution
-The keyring token takes precedence over `LOCALSTACK_AUTH_TOKEN`.
-If you set or change the environment variable but a keyring token already exists, the environment variable is ignored.
-Run `lstk logout` to clear the stored keyring token first.
+:::note
+`LOCALSTACK_AUTH_TOKEN` takes precedence over a token in the keyring.
+A per-invocation token (a CI secret, or `LOCALSTACK_AUTH_TOKEN=... lstk start` for a second account) therefore overrides a previous `lstk login` without needing `lstk logout` first.
+To go back to the stored token, unset the environment variable.
 :::
 
 ## Logging in
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
index 1e52313f..820e11e5 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
@@ -12,6 +12,7 @@ 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](#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 `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`) |
@@ -42,6 +43,28 @@ Commands that mutate state without prompting in CI (`reset`, `volume clear`) req
 `lstk setup aws` works non-interactively — it writes the profile with defaults and needs `--force` only to overwrite a conflicting `localstack` profile.
 :::
 
+## Targeting an external emulator
+
+By default `lstk` discovers the emulator it manages through local Docker.
+The `--endpoint-url <url>` global flag (or the `LSTK_ENDPOINT_URL` environment variable) instead points a command at an emulator `lstk` did not start — a Docker Compose or host-network deployment, one running in CI or on another machine, or a LocalStack cloud-hosted ephemeral instance.
+
+```bash
+# Run against an emulator reachable at a custom URL
+lstk aws --endpoint-url http://localhost:4566 s3 ls
+
+# Equivalent via the environment
+LSTK_ENDPOINT_URL=https://my-ephemeral-instance.localstack.cloud lstk status
+```
+
+The endpoint is resolved from, in order of precedence: the `--endpoint-url` flag, `LSTK_ENDPOINT_URL`, then `AWS_ENDPOINT_URL` (a full synonym for `LSTK_ENDPOINT_URL`, one tier lower).
+Both `http://` and `https://` URLs are accepted (any other scheme is rejected), and the scheme is preserved end-to-end, so `https://` ephemeral instances work.
+
+The commands that accept an external endpoint are the ones that only *talk to* an already-running emulator: [`aws`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#aws), [`az`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#az), [`terraform`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#terraform)/`tf`, [`cdk`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#cdk), [`sam`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#sam), [`status`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#status), [`reset`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#reset), and the [`snapshot`](/aws/developer-tools/running-localstack/lstk/snapshots/) `save`/`load`/`remove` subcommands (including the `lstk save`/`lstk load` aliases) and `list s3://…`.
+
+Commands that manage the emulator's lifecycle or on-disk state have no remote equivalent and **reject** any endpoint source: `start`, the bare `lstk`, `stop`, `restart`, `logs`, and `volume`.
+
+The emulator's type (AWS, Azure, or Snowflake) is auto-detected by probing the endpoint's health API — there is no override flag or config setting, and an inconclusive probe is a hard failure. The AWS-only tools (`terraform`, `cdk`, `sam`) reject an endpoint whose detected type is not AWS.
+
 ## Structured output
 
 The global `--json` flag makes a command emit a single, machine-readable JSON object on stdout instead of human-oriented text, for scripting and CI.
@@ -115,7 +138,8 @@ The following environment variables configure `lstk` itself (not the LocalStack
 
 | Variable                     | Description                                                                                                      |
 |:-------------------------------|:---------------------------------------------------------------------------------------------------------------------|
-| `LOCALSTACK_AUTH_TOKEN`      | Auth token for non-interactive runs or to skip browser login. Used when no keyring token is stored.              |
+| `LOCALSTACK_AUTH_TOKEN`      | Auth token for non-interactive runs or to skip browser login. Takes precedence over a token stored in the keyring. |
+| `LSTK_ENDPOINT_URL`          | Target an existing, externally-managed emulator at this URL (equivalent to `--endpoint-url`). `AWS_ENDPOINT_URL` is a lower-precedence synonym. See [Targeting an external emulator](#targeting-an-external-emulator). |
 | `LOCALSTACK_HOST`            | Override the host (and optional port) used when resolving and printing the emulator endpoint, and when writing the AWS CLI profile. Bypasses the `localhost.localstack.cloud` DNS probe. |
 | `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`).                        |
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
index 2a52c446..02668189 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
@@ -10,6 +10,7 @@ tags: ['Hobby']
 :::note
 Like `lstk aws`, the `az`, `terraform`, `cdk`, and `sam` proxies do not start the emulator — start it first with [`lstk start`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#start).
 Each requires the corresponding third-party CLI to be installed and on your `PATH`.
+To run any of them against an emulator `lstk` did not start, pass [`--endpoint-url`](/aws/developer-tools/running-localstack/lstk/automation/#targeting-an-external-emulator) (or set `LSTK_ENDPOINT_URL`).
 :::
 
 :::note
@@ -40,6 +41,7 @@ The exit code and `stdout`/`stderr` of the underlying `aws` process are passed t
 
 | Option              | Description                                                                                       |
 |:--------------------|:--------------------------------------------------------------------------------------------------|
+| `--account <id>`    | Target a specific 12-digit LocalStack account (default `000000000000`). Must appear **before** the `aws` subcommand. Falls back to a 12-digit `AWS_ACCESS_KEY_ID`. See [Selecting the account](#selecting-the-account). |
 | `--non-interactive` | Suppress the loading spinner. Unlike other commands, this flag is stripped before invoking `aws` (not forwarded). |
 
 :::note
@@ -62,6 +64,20 @@ By default, `lstk` probes whether `localhost.localstack.cloud` resolves to `127.
 Set [`LOCALSTACK_HOST`](/aws/developer-tools/running-localstack/lstk/automation/#environment-variables) to override the host:port used to reach LocalStack and skip the DNS probe.
 The port comes from the AWS container's `port` in `config.toml` (default `4566`).
 
+### Selecting the account
+
+LocalStack derives the AWS account from the access key id it receives, so `lstk aws --account <id>` targets a specific 12-digit LocalStack account by controlling the credentials `aws` runs with (a neutral, real-looking `AKIA…`/`ASIA…` key never reaches the emulator):
+
+```bash
+lstk aws --account 111111111111 s3 mb s3://my-bucket
+```
+
+The flag must appear **before** the `aws` subcommand (placing it after is a placement error, not silently forwarded). When it is omitted, `lstk` falls back to a 12-digit `AWS_ACCESS_KEY_ID` if one is set, then to the default account `000000000000`. The same leading-flag account selection is available on [`lstk terraform`](#terraform) and [`lstk sam`](#sam); `lstk cdk` does not support it.
+
+### Tab completion
+
+`lstk aws <TAB>` completes AWS services, operations, and parameters using the AWS CLI's own completer. It is enabled together with the rest of `lstk`'s completion — see [Shell completions](/aws/developer-tools/running-localstack/lstk/#shell-completions).
+
 ## `az`
 
 Run Azure CLI commands against the running LocalStack Azure emulator.
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/configuration.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/configuration.mdx
index d898bb0d..e9082d1e 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/configuration.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/configuration.mdx
@@ -41,7 +41,9 @@ The default `config.toml` created on first run. The `type` field reflects whiche
 type = "aws"      # Emulator type. Supported: "aws", "snowflake", "azure"
 tag  = "latest"   # Docker image tag, e.g. "latest", "2026.4"
 port = "4566"     # Host port the emulator will be accessible on
+# container_name = ""  # Override the derived container name (also MAIN_CONTAINER_NAME)
 # image = ""      # Full image override (e.g. an internal mirror or offline image)
+# expose_ports = []    # Extra container ports to publish, e.g. [53] for the DNS server
 # volume = ""     # Host directory for persistent state (default: OS cache dir)
 # volumes = []    # Docker-style "host:container[:ro]" bind mounts (see Volumes)
 # env = []        # Named environment profiles to apply (see [env.*] sections below)
@@ -55,7 +57,9 @@ port = "4566"     # Host port the emulator will be accessible on
 | `type`     | string   | `"aws"`    | Emulator type. One of `"aws"`, `"snowflake"`, `"azure"`. Run a single `[[containers]]` block at a time. See [Emulator types](#emulator-types). |
 | `tag`      | string   | `"latest"` | Docker image tag (`"latest"`, `"2026.4"`, etc.). Useful for pinning a specific version. Zero-padded months (`"2026.04"`) are normalized to `"2026.4"`. |
 | `port`     | string   | `"4566"`   | Host port the emulator listens on (1–65535). The in-container port is always `4566`.                 |
+| `container_name` | string | (derived) | Override the derived container name (`localstack-<type>`, plus `-<tag>` when `tag` is not `"latest"`). This is also what the emulator reports as `MAIN_CONTAINER_NAME`. Set it when something outside `lstk` addresses the emulator by a fixed name, e.g. a sidecar proxy on a CI agent. |
 | `image`    | string   | (default)  | Full image reference that overrides the default Docker Hub image, e.g. an internal-registry mirror or a locally loaded offline image. If it already carries a tag, `tag` is ignored; otherwise `tag` (or `latest`) is appended. |
+| `expose_ports` | (int \| string)[] | `[]` | Publish additional container ports on the host, beyond the gateway and service ports `lstk` publishes by default. Each entry is a bare port number (published on the same host port) or a Docker-style `"[host:]container[/proto]"` string — e.g. `expose_ports = [53]` to use the emulator's DNS server as the host's resolver, or `expose_ports = ["5354:5353/udp"]`. |
 | `volume`   | string   | (OS cache) | Host directory for persistent emulator state. Defaults to `<os-cache>/lstk/volume/<container-name>`. See also `volumes`. |
 | `volumes`  | string[] | `[]`       | Docker-style `"host:container[:ro]"` bind mounts (e.g. init hooks). May also carry the persistence mount (target `/var/lib/localstack`). See [Volume mounts](#volume-mounts). |
 | `env`      | string[] | `[]`       | List of named environment profiles to inject into the container (see below).                         |
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
index ba5cb81d..1f2e336b 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
@@ -29,8 +29,8 @@ This section is split into focused pages:
 - [Configuration](/aws/developer-tools/running-localstack/lstk/configuration/): the `config.toml` file, emulator types, environment variables, and volumes.
 - [Lifecycle commands](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/): `start`, `stop`, `restart`, `status`, `logs`, `reset`, `volume`.
 - [Cloud & IaC commands](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/): `aws`, `az`, `terraform`, `cdk`, `sam`.
-- [Snapshots](/aws/developer-tools/running-localstack/lstk/snapshots/): save and load emulator state with `snapshot save`/`load`/`list`/`remove`/`show`.
-- [Automation & CI](/aws/developer-tools/running-localstack/lstk/automation/): global options, non-interactive mode, structured output, and environment variables.
+- [Snapshots](/aws/developer-tools/running-localstack/lstk/snapshots/): save and load emulator state with `snapshot save`/`load`/`list`/`remove`/`show`/`versions`.
+- [Automation & CI](/aws/developer-tools/running-localstack/lstk/automation/): global options, non-interactive mode, structured output, targeting an external emulator, and environment variables.
 - [Setup & maintenance](/aws/developer-tools/running-localstack/lstk/setup-and-maintenance/): `setup`, `config`, `update`, and offline/enterprise environments.
 - [FAQ & Troubleshooting](/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting/).
 
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md
index 3579d2e4..21f9d4e6 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md
@@ -9,12 +9,11 @@ tags: ['Hobby']
 
 Manage emulator snapshots.
 A snapshot captures the running emulator's state, either as a local file on disk, as a Cloud Pod on the LocalStack platform, or in your own S3 bucket.
-The `snapshot` command groups five subcommands — `save`, `load`, `list`, `remove`, and `show`. The first two are also exposed as the top-level aliases `lstk save` and `lstk load`.
+The `snapshot` command groups six subcommands — `save`, `load`, `list`, `remove`, `show`, and `versions`. The first two are also exposed as the top-level aliases `lstk save` and `lstk load`.
 
 :::note
 Snapshots are best supported on the **AWS emulator**.
-`snapshot save`/`load` (and the `save`/`load` aliases) also work for the Snowflake emulator, but its snapshot support is experimental and not fully tested — `lstk` prints a warning such as `Snapshot support for the snowflake emulator is experimental and not fully tested.`
-Azure emulator persistence is still a work in progress and is not yet supported.
+`snapshot save`/`load` (and the `save`/`load` aliases) also work for the Snowflake and Azure emulators, but their snapshot support is experimental and not fully tested — for a non-AWS emulator `lstk` prints a warning such as `Snapshot support for the snowflake emulator is experimental and not fully tested.`
 :::
 
 ## `snapshot save`
@@ -50,6 +49,8 @@ The optional `[destination]` argument takes one of these forms:
 
 Pod operations require an auth token (`LOCALSTACK_AUTH_TOKEN` or a prior `lstk login`); local-file snapshots do not.
 
+Every save to an existing `pod:` snapshot creates a new **version** rather than replacing it; use [`snapshot versions`](#snapshot-versions) to list them and [`snapshot load`](#snapshot-load)/[`snapshot show`](#snapshot-show) with a `pod:<name>:<version>` ref to act on a specific one. `save` itself rejects a version suffix (you cannot save "as version 3").
+
 By default a snapshot captures every service's state. Pass `-s`/`--services` with a comma-separated list to limit it to a subset; this applies uniformly to local files, `pod:` Cloud Pods, and `s3://` remotes.
 
 | Option              | Description                                                                                   |
@@ -66,9 +67,12 @@ Load a snapshot into the emulator, **auto-starting it first** if it is not alrea
 lstk snapshot load my-baseline
 lstk snapshot load ./checkpoint
 
-# Load from a Cloud Pod (requires auth)
+# Load from a Cloud Pod (requires auth; latest version)
 lstk snapshot load pod:my-baseline
 
+# Load a specific version of a Cloud Pod
+lstk snapshot load pod:my-baseline:3
+
 # Load from your own S3 bucket (pod name is required)
 lstk snapshot load my-pod s3://my-bucket/prefix
 
@@ -80,6 +84,7 @@ lstk snapshot load pod:my-baseline --dry-run
 ```
 
 The `REF` argument is required and identifies a local path/name or a `pod:<name>` Cloud Pod.
+For a Cloud Pod you can append a version (`pod:<name>:<version>`) to load an older version; the latest is used when no version is given.
 To load from S3, pass the pod name followed by an `s3://bucket/prefix` location (see [S3 remotes](#s3-remotes)).
 
 | Option               | Description                                                                                              |
@@ -154,10 +159,29 @@ Show metadata for a single Cloud Pod snapshot on the LocalStack platform: its na
 This subcommand is cloud-only and requires authentication.
 
 ```bash
+# Latest version
 lstk snapshot show pod:my-baseline
+
+# A specific version
+lstk snapshot show pod:my-baseline:3
+```
+
+The required `REF` argument must be a `pod:<name>` Cloud Pod reference.
+It defaults to the latest version; append `:<version>` to inspect an older one. Use [`snapshot versions`](#snapshot-versions) to see which versions exist.
+
+## `snapshot versions`
+
+List the version history of a Cloud Pod on the LocalStack platform.
+Every save to an existing pod adds a new version; this prints each version's number, created date, LocalStack version, and services.
+This subcommand is cloud-only and requires authentication.
+
+```bash
+lstk snapshot versions pod:my-baseline
 ```
 
 The required `REF` argument must be a `pod:<name>` Cloud Pod reference.
+Only Cloud Pods have versions — local files and `s3://` remotes do not, and passing a version suffix to `versions` is rejected.
+Act on a specific version elsewhere by appending it to the ref, e.g. `lstk snapshot load pod:my-baseline:3` or `lstk snapshot show pod:my-baseline:3`.
 
 ## S3 remotes
 

From da5d69238be88ff3d5449138d936581407554c5e Mon Sep 17 00:00:00 2001
From: Anisa Oshafi <anisaoshafi@gmail.com>
Date: Wed, 2 Sep 2026 12:56:41 +0200
Subject: [PATCH 02/10] Fix inaccurate statement on aws --account

---
 .../running-localstack/lstk/cloud-and-iac-commands.md         | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
index 02668189..0f90142c 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
@@ -41,7 +41,7 @@ The exit code and `stdout`/`stderr` of the underlying `aws` process are passed t
 
 | Option              | Description                                                                                       |
 |:--------------------|:--------------------------------------------------------------------------------------------------|
-| `--account <id>`    | Target a specific 12-digit LocalStack account (default `000000000000`). Must appear **before** the `aws` subcommand. Falls back to a 12-digit `AWS_ACCESS_KEY_ID`. See [Selecting the account](#selecting-the-account). |
+| `--account <id>`    | Target a specific 12-digit LocalStack account (default `000000000000`). Must appear immediately after `lstk aws`, before the AWS CLI's own action. Falls back to a 12-digit `AWS_ACCESS_KEY_ID`. See [Selecting the account](#selecting-the-account). |
 | `--non-interactive` | Suppress the loading spinner. Unlike other commands, this flag is stripped before invoking `aws` (not forwarded). |
 
 :::note
@@ -72,7 +72,7 @@ LocalStack derives the AWS account from the access key id it receives, so `lstk
 lstk aws --account 111111111111 s3 mb s3://my-bucket
 ```
 
-The flag must appear **before** the `aws` subcommand (placing it after is a placement error, not silently forwarded). When it is omitted, `lstk` falls back to a 12-digit `AWS_ACCESS_KEY_ID` if one is set, then to the default account `000000000000`. The same leading-flag account selection is available on [`lstk terraform`](#terraform) and [`lstk sam`](#sam); `lstk cdk` does not support it.
+The flag must appear immediately after `lstk aws`, before the AWS CLI's own action (placing it before `lstk aws` is a placement error; placing it after the action is not caught — `lstk` silently forwards it to the `aws` CLI, which then rejects it). When it is omitted, `lstk` falls back to a 12-digit `AWS_ACCESS_KEY_ID` if one is set, then to the default account `000000000000`. The same leading-flag account selection is available on [`lstk terraform`](#terraform) and [`lstk sam`](#sam); `lstk cdk` does not support it.
 
 ### Tab completion
 

From c8ad05a86176f91de698a1eab2279e417aa4cf49 Mon Sep 17 00:00:00 2001
From: George Tsiolis <george.tsiolis@localstack.cloud>
Date: Wed, 2 Sep 2026 10:57:31 +0000
Subject: [PATCH 03/10] docs(lstk): fold in runtime discovery, port 443,
 checksum, account placement

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../running-localstack/lstk/automation.mdx    | 14 +++++++++--
 .../lstk/cloud-and-iac-commands.md            |  6 ++---
 .../lstk/faq-and-troubleshooting.md           | 23 ++++++++-----------
 .../lstk/setup-and-maintenance.md             |  2 +-
 4 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
index 820e11e5..3ef5d485 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
@@ -151,10 +151,20 @@ The following environment variables configure `lstk` itself (not the LocalStack
 | `LSTK_API_ENDPOINT`          | Override the LocalStack platform API base URL. Default: `https://api.localstack.cloud`.                          |
 | `LSTK_WEB_APP_URL`           | Override the LocalStack Web Application URL used for browser login. Default: `https://app.localstack.cloud`.     |
 
-When `DOCKER_HOST` is not set, `lstk` tries the default Docker socket and then probes common alternatives (Colima at `~/.colima/default/docker.sock` or `~/.config/colima/default/docker.sock`, OrbStack at `~/.orbstack/run/docker.sock`).
-
 When `LSTK_OTEL` is enabled, the standard `OTEL_EXPORTER_OTLP_*` environment variables are honored by the OpenTelemetry SDK.
 
+### Container runtime discovery
+
+`lstk` talks to a Docker-compatible runtime and works with Docker Desktop, Rancher Desktop, Colima, OrbStack, Lima, and Podman. When `DOCKER_HOST` is not set, it resolves the daemon endpoint in this order:
+
+1. **`DOCKER_HOST`**, if set, always wins.
+2. **`DOCKER_CONTEXT`** or the active Docker CLI context, when it is non-default and reachable (a stale or unreachable context is skipped rather than failing).
+3. On **Linux**, a live `/var/run/docker.sock` — a running Docker daemon is preferred over a co-installed runtime such as Podman.
+4. A probe of known runtime sockets (Docker Desktop, Rancher Desktop, Colima, OrbStack, Podman, Lima). Each candidate is dialed, not just checked for existence, so a leftover socket file never shadows a live daemon.
+5. The Docker SDK's own default.
+
+If no runtime is reachable, the error tailors its suggested start command (`rdctl start`, `colima start`, `podman machine start`, …) to the runtime it detects. Set `DOCKER_HOST` to point at a specific socket to bypass discovery entirely.
+
 ### Container-injected variables
 
 `lstk` injects several environment variables into the LocalStack container on every start, in addition to any profiles you configure:
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
index 02668189..dfa6e1d0 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands.md
@@ -41,7 +41,7 @@ The exit code and `stdout`/`stderr` of the underlying `aws` process are passed t
 
 | Option              | Description                                                                                       |
 |:--------------------|:--------------------------------------------------------------------------------------------------|
-| `--account <id>`    | Target a specific 12-digit LocalStack account (default `000000000000`). Must appear **before** the `aws` subcommand. Falls back to a 12-digit `AWS_ACCESS_KEY_ID`. See [Selecting the account](#selecting-the-account). |
+| `--account <id>`    | Target a specific 12-digit LocalStack account (default `000000000000`). Place it right after `aws`, before the AWS CLI command (e.g. `s3`). Falls back to a 12-digit `AWS_ACCESS_KEY_ID`. See [Selecting the account](#selecting-the-account). |
 | `--non-interactive` | Suppress the loading spinner. Unlike other commands, this flag is stripped before invoking `aws` (not forwarded). |
 
 :::note
@@ -72,7 +72,7 @@ LocalStack derives the AWS account from the access key id it receives, so `lstk
 lstk aws --account 111111111111 s3 mb s3://my-bucket
 ```
 
-The flag must appear **before** the `aws` subcommand (placing it after is a placement error, not silently forwarded). When it is omitted, `lstk` falls back to a 12-digit `AWS_ACCESS_KEY_ID` if one is set, then to the default account `000000000000`. The same leading-flag account selection is available on [`lstk terraform`](#terraform) and [`lstk sam`](#sam); `lstk cdk` does not support it.
+Place `--account` right after `aws`, before the AWS CLI command (`s3` in the example above). Putting it before the `aws` word (`lstk --account … aws`) is rejected with a placement error, and putting it after the AWS CLI command is forwarded to `aws` unchanged rather than interpreted by `lstk`. When it is omitted, `lstk` falls back to a 12-digit `AWS_ACCESS_KEY_ID` if one is set, then to the default account `000000000000`. The same leading-flag account selection is available on [`lstk terraform`](#terraform) and [`lstk sam`](#sam); `lstk cdk` does not support it.
 
 ### Tab completion
 
@@ -84,7 +84,7 @@ Run Azure CLI commands against the running LocalStack Azure emulator.
 `lstk az` runs `az` with an isolated `AZURE_CONFIG_DIR` in which a custom Azure cloud is registered against LocalStack's endpoints, so your global `~/.azure` configuration is left untouched and plain `az` keeps talking to real Azure.
 
 Run [`lstk setup azure`](/aws/developer-tools/running-localstack/lstk/setup-and-maintenance/#setup-azure) once before using this mode.
-Everything after `lstk az` is forwarded verbatim to the host `az` binary, and its exit code and output are passed through unchanged.
+Arguments are forwarded to the host `az` binary, and its exit code and output are passed through unchanged. `lstk`'s own flags (`--non-interactive`, `--config`) are consumed by `lstk` rather than forwarded — for example `lstk az --non-interactive …` suppresses the loading spinner instead of passing the flag to `az`.
 
 ```bash
 lstk az group list
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
index bacb2dce..fb87e35a 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
@@ -48,18 +48,12 @@ port = "4566"
 
 ### Port 443 already in use
 
-By default, LocalStack binds to both port `4566` and port `443` inside the container (controlled by the `GATEWAY_LISTEN` variable).
-On some systems, particularly Windows with Hyper-V, IIS, or VPN software, port 443 may already be in use.
+By default, LocalStack publishes both port `4566` and port `443` (controlled by the `GATEWAY_LISTEN` variable).
+On some systems port 443 is already taken — Windows with Hyper-V, IIS, or VPN software, or an ingress proxy such as Rancher Desktop's Traefik.
 
-**Symptoms:**
+Because port 443 comes from the **default** `GATEWAY_LISTEN`, a busy 443 is **not fatal**: `lstk` drops that publication with a warning and starts anyway, and HTTPS is still served on the edge port `4566`. You only need to act if you want to silence the warning or bind 443 elsewhere.
 
-```text
-failed to start LocalStack: Error response from daemon: ports are not available:
-exposing port TCP 127.0.0.1:443 -> 127.0.0.1:0: listen tcp4 127.0.0.1:443: bind:
-address already in use
-```
-
-**Fix:** Override `GATEWAY_LISTEN` to bind only to port 4566:
+To skip port 443 entirely, override `GATEWAY_LISTEN` to bind only to `4566`:
 
 ```toml
 [[containers]]
@@ -72,7 +66,9 @@ env  = ["nossl"]
 GATEWAY_LISTEN = "0.0.0.0:4566"
 ```
 
-This tells the container to skip the port 443 binding entirely.
+:::note
+A port you list **explicitly** in a custom `GATEWAY_LISTEN` is treated as a hard requirement, so a busy one there fails the start rather than being dropped. Only the `443` from the default value is best-effort.
+:::
 
 ### Docker is not running
 
@@ -83,9 +79,8 @@ If Docker is not reachable, you will see an error like:
 Error: runtime not healthy
 ```
 
-**Fix:** Start Docker Desktop (macOS/Windows) or the Docker daemon (`sudo systemctl start docker` on Linux).
-If you use Colima or OrbStack, make sure the VM is running.
-You can also point `lstk` at a custom socket with `DOCKER_HOST`.
+**Fix:** Start your container runtime. `lstk` works with Docker Desktop, Rancher Desktop, Colima, OrbStack, Lima, and Podman — start the Docker daemon (`sudo systemctl start docker` on Linux) or the relevant VM (`rdctl start`, `colima start`, `podman machine start`, …). When the runtime is unavailable, `lstk`'s error tailors its suggested start command to whichever runtime it detects.
+You can also point `lstk` at a specific socket with `DOCKER_HOST`. See [Container runtime discovery](/aws/developer-tools/running-localstack/lstk/automation/#container-runtime-discovery) for how the daemon is located.
 
 ### Authentication required in non-interactive mode
 
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/setup-and-maintenance.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/setup-and-maintenance.md
index e4672465..723a8d8b 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/setup-and-maintenance.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/setup-and-maintenance.md
@@ -130,7 +130,7 @@ By install method:
 
 - **Homebrew** (binary under a `Caskroom` path): runs `brew upgrade localstack/tap/lstk`.
 - **npm** (binary under `node_modules`): runs `npm install -g @localstack/lstk@latest`.
-- **Binary** (anything else): downloads the release asset for your OS/arch from GitHub, extracts it, and replaces the running executable in place.
+- **Binary** (anything else): downloads the release asset for your OS/arch from GitHub, verifies its SHA-256 against the release's `checksums.txt` (a missing, malformed, or mismatched checksum aborts the update), extracts it, and replaces the running executable in place.
 
 With `--check`, `lstk` only reports whether a newer version is available and exits without downloading or installing anything.
 

From 800fe4037b468534db5b4d5f61e21672fd964532 Mon Sep 17 00:00:00 2001
From: George Tsiolis <george.tsiolis@localstack.cloud>
Date: Wed, 2 Sep 2026 11:15:03 +0000
Subject: [PATCH 04/10] docs(lstk): apply the same v0.22.2 corrections to the
 Azure lstk page

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../docs/azure/developer-tools/lstk.mdx       | 126 ++++++++++++++----
 1 file changed, 98 insertions(+), 28 deletions(-)

diff --git a/src/content/docs/azure/developer-tools/lstk.mdx b/src/content/docs/azure/developer-tools/lstk.mdx
index 0bb19c2e..1b76d7d4 100644
--- a/src/content/docs/azure/developer-tools/lstk.mdx
+++ b/src/content/docs/azure/developer-tools/lstk.mdx
@@ -93,14 +93,14 @@ CI environments require a CI Auth Token; a personal Developer Auth Token cannot
 
 `lstk` resolves your auth token in the following order:
 
-1. **System keyring**: a token stored by a previous `lstk login`.
-2. **`LOCALSTACK_AUTH_TOKEN` environment variable**: used only when the keyring has no token.
+1. **`LOCALSTACK_AUTH_TOKEN` environment variable**: takes precedence over a stored token.
+2. **System keyring**: a token stored by a previous `lstk login`, used when the environment variable is not set.
 3. **Browser login**: triggered automatically in interactive mode when neither of the above provides a token.
 
-:::caution
-The keyring token takes precedence over `LOCALSTACK_AUTH_TOKEN`.
-If you set or change the environment variable but a keyring token already exists, the environment variable is ignored.
-Run `lstk logout` to clear the stored keyring token first.
+:::note
+`LOCALSTACK_AUTH_TOKEN` takes precedence over a token in the keyring.
+A per-invocation token (a CI secret, or `LOCALSTACK_AUTH_TOKEN=... lstk start` for a second account) therefore overrides a previous `lstk login` without needing `lstk logout` first.
+To go back to the stored token, unset the environment variable.
 :::
 
 ### Logging in
@@ -170,7 +170,9 @@ The default `config.toml` created on first run:
 type = "aws"      # Emulator type. Supported: "aws", "snowflake", "azure"
 tag  = "latest"   # Docker image tag, e.g. "latest", "2026.4"
 port = "4566"     # Host port the emulator will be accessible on
+# container_name = ""  # Override the derived container name (also MAIN_CONTAINER_NAME)
 # image = ""      # Full image override (e.g. an internal mirror or offline image)
+# expose_ports = []    # Extra container ports to publish, e.g. [53] for the DNS server
 # volume = ""     # Host directory for persistent state (default: OS cache dir)
 # volumes = []    # Docker-style "host:container[:ro]" bind mounts (see Volumes)
 # env = []        # Named environment profiles to apply (see [env.*] sections below)
@@ -184,7 +186,9 @@ port = "4566"     # Host port the emulator will be accessible on
 | `type`     | string   | `"aws"`    | Emulator type. One of `"aws"`, `"snowflake"`, `"azure"`. Run a single `[[containers]]` block at a time. See [Emulator types](#emulator-types). |
 | `tag`      | string   | `"latest"` | Docker image tag (`"latest"`, `"2026.4"`, etc.). Useful for pinning a specific version. Zero-padded months (`"2026.04"`) are normalized to `"2026.4"`. |
 | `port`     | string   | `"4566"`   | Host port the emulator listens on (1–65535). The in-container port is always `4566`.                 |
+| `container_name` | string | (derived) | Override the derived container name (`localstack-<type>`, plus `-<tag>` when `tag` is not `"latest"`). This is also what the emulator reports as `MAIN_CONTAINER_NAME`. Set it when something outside `lstk` addresses the emulator by a fixed name, e.g. a sidecar proxy on a CI agent. |
 | `image`    | string   | (default)  | Full image reference that overrides the default Docker Hub image, e.g. an internal-registry mirror or a locally loaded offline image. If it already carries a tag, `tag` is ignored; otherwise `tag` (or `latest`) is appended. |
+| `expose_ports` | (int \| string)[] | `[]` | Publish additional container ports on the host, beyond the gateway and service ports `lstk` publishes by default. Each entry is a bare port number (published on the same host port) or a Docker-style `"[host:]container[/proto]"` string — e.g. `expose_ports = [53]` to use the emulator's DNS server as the host's resolver, or `expose_ports = ["5354:5353/udp"]`. |
 | `volume`   | string   | (OS cache) | Host directory for persistent emulator state. Defaults to `<os-cache>/lstk/volume/<container-name>`. See also `volumes`. |
 | `volumes`  | string[] | `[]`       | Docker-style `"host:container[:ro]"` bind mounts (e.g. init hooks). May also carry the persistence mount (target `/var/lib/localstack`). See [Volume mounts](#volume-mounts). |
 | `env`      | string[] | `[]`       | List of named environment profiles to inject into the container (see below).                         |
@@ -549,6 +553,7 @@ The exit code and `stdout`/`stderr` of the underlying `aws` process are passed t
 
 | Option              | Description                                                                                       |
 |:--------------------|:--------------------------------------------------------------------------------------------------|
+| `--account <id>`    | Target a specific 12-digit LocalStack account (default `000000000000`). Must appear immediately after `lstk aws`, before the AWS CLI's own action. Falls back to a 12-digit `AWS_ACCESS_KEY_ID`. See [Selecting the account](#selecting-the-account). |
 | `--non-interactive` | Suppress the loading spinner. Unlike other commands, this flag is stripped before invoking `aws` (not forwarded). |
 
 :::note
@@ -571,13 +576,23 @@ By default, `lstk` probes whether `localhost.localstack.cloud` resolves to `127.
 Set [`LOCALSTACK_HOST`](#environment-variables) to override the host:port used to reach LocalStack and skip the DNS probe.
 The port comes from the AWS container's `port` in `config.toml` (default `4566`).
 
+#### Selecting the account
+
+LocalStack derives the AWS account from the access key id it receives, so `lstk aws --account <id>` targets a specific 12-digit LocalStack account by controlling the credentials `aws` runs with (a neutral, real-looking `AKIA…`/`ASIA…` key never reaches the emulator):
+
+```bash
+lstk aws --account 111111111111 s3 mb s3://my-bucket
+```
+
+The flag must appear immediately after `lstk aws`, before the AWS CLI's own action (placing it before `lstk aws` is a placement error; placing it after the action is not caught — `lstk` silently forwards it to the `aws` CLI, which then rejects it). When it is omitted, `lstk` falls back to a 12-digit `AWS_ACCESS_KEY_ID` if one is set, then to the default account `000000000000`. The same leading-flag account selection is available on [`lstk terraform`](#terraform) and [`lstk sam`](#sam); `lstk cdk` does not support it.
+
 ### `az`
 
 Run Azure CLI commands against the running LocalStack Azure emulator.
 `lstk az` runs `az` with an isolated `AZURE_CONFIG_DIR` in which a custom Azure cloud is registered against LocalStack's endpoints, so your global `~/.azure` configuration is left untouched and plain `az` keeps talking to real Azure.
 
 Run [`lstk setup azure`](#setup-azure) once before using this mode.
-Everything after `lstk az` is forwarded verbatim to the host `az` binary, and its exit code and output are passed through unchanged.
+Arguments are forwarded to the host `az` binary, and its exit code and output are passed through unchanged. `lstk`'s own flags (`--non-interactive`, `--config`) are consumed by `lstk` rather than forwarded — for example `lstk az --non-interactive …` suppresses the loading spinner instead of passing the flag to `az`.
 
 ```bash
 lstk az group list
@@ -676,7 +691,7 @@ When you interrupt a proxied tool (for example Ctrl+C or `kill` during `lstk ter
 
 Manage emulator snapshots.
 A snapshot captures the running emulator's state, either as a local file on disk, as a Cloud Pod on the LocalStack platform, or in your own S3 bucket.
-The `snapshot` command groups five subcommands — `save`, `load`, `list`, `remove`, and `show`. The first two are also exposed as the top-level aliases `lstk save` and `lstk load`.
+The `snapshot` command groups six subcommands — `save`, `load`, `list`, `remove`, `show`, and `versions`. The first two are also exposed as the top-level aliases `lstk save` and `lstk load`.
 
 :::note
 Snapshots are best supported on the **AWS emulator**.
@@ -717,6 +732,8 @@ The optional `[destination]` argument takes one of these forms:
 
 Pod operations require an auth token (`LOCALSTACK_AUTH_TOKEN` or a prior `lstk login`); local-file snapshots do not.
 
+Every save to an existing `pod:` snapshot creates a new **version** rather than replacing it; use [`snapshot versions`](#snapshot-versions) to list them and [`snapshot load`](#snapshot-load)/[`snapshot show`](#snapshot-show) with a `pod:<name>:<version>` ref to act on a specific one. `save` itself rejects a version suffix (you cannot save "as version 3").
+
 By default a snapshot captures every service's state. Pass `-s`/`--services` with a comma-separated list to limit it to a subset; this applies uniformly to local files, `pod:` Cloud Pods, and `s3://` remotes.
 
 | Option              | Description                                                                                   |
@@ -733,9 +750,12 @@ Load a snapshot into the emulator, **auto-starting it first** if it is not alrea
 lstk snapshot load my-baseline
 lstk snapshot load ./checkpoint
 
-# Load from a Cloud Pod (requires auth)
+# Load from a Cloud Pod (requires auth; latest version)
 lstk snapshot load pod:my-baseline
 
+# Load a specific version of a Cloud Pod
+lstk snapshot load pod:my-baseline:3
+
 # Load from your own S3 bucket (pod name is required)
 lstk snapshot load my-pod s3://my-bucket/prefix
 
@@ -747,6 +767,7 @@ lstk snapshot load pod:my-baseline --dry-run
 ```
 
 The `REF` argument is required and identifies a local path/name or a `pod:<name>` Cloud Pod.
+For a Cloud Pod you can append a version (`pod:<name>:<version>`) to load an older version; the latest is used when no version is given.
 To load from S3, pass the pod name followed by an `s3://bucket/prefix` location (see [S3 remotes](#s3-remotes)).
 
 | Option               | Description                                                                                              |
@@ -819,10 +840,29 @@ Show metadata for a single Cloud Pod snapshot on the LocalStack platform: its na
 This subcommand is cloud-only and requires authentication.
 
 ```bash
+# Latest version
 lstk snapshot show pod:my-baseline
+
+# A specific version
+lstk snapshot show pod:my-baseline:3
 ```
 
 The required `REF` argument must be a `pod:<name>` Cloud Pod reference.
+It defaults to the latest version; append `:<version>` to inspect an older one. Use [`snapshot versions`](#snapshot-versions) to see which versions exist.
+
+#### `snapshot versions`
+
+List the version history of a Cloud Pod on the LocalStack platform.
+Every save to an existing pod adds a new version; this prints each version's number, created date, LocalStack version, and services.
+This subcommand is cloud-only and requires authentication.
+
+```bash
+lstk snapshot versions pod:my-baseline
+```
+
+The required `REF` argument must be a `pod:<name>` Cloud Pod reference.
+Only Cloud Pods have versions — local files and `s3://` remotes do not, and passing a version suffix to `versions` is rejected.
+Act on a specific version elsewhere by appending it to the ref, e.g. `lstk snapshot load pod:my-baseline:3` or `lstk snapshot show pod:my-baseline:3`.
 
 #### S3 remotes
 
@@ -1122,7 +1162,7 @@ By install method:
 
 - **Homebrew** (binary under a `Caskroom` path): runs `brew upgrade localstack/tap/lstk`.
 - **npm** (binary under `node_modules`): runs `npm install -g @localstack/lstk@latest`.
-- **Binary** (anything else): downloads the release asset for your OS/arch from GitHub, extracts it, and replaces the running executable in place.
+- **Binary** (anything else): downloads the release asset for your OS/arch from GitHub, verifies its SHA-256 against the release's `checksums.txt` (a missing, malformed, or mismatched checksum aborts the update), extracts it, and replaces the running executable in place.
 
 With `--check`, `lstk` only reports whether a newer version is available and exits without downloading or installing anything.
 
@@ -1179,6 +1219,7 @@ 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](#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 `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`) |
@@ -1209,6 +1250,28 @@ Commands that mutate state without prompting in CI (`reset`, `volume clear`) req
 `lstk setup aws` works non-interactively — it writes the profile with defaults and needs `--force` only to overwrite a conflicting `localstack` profile.
 :::
 
+## Targeting an external emulator
+
+By default `lstk` discovers the emulator it manages through local Docker.
+The `--endpoint-url <url>` global flag (or the `LSTK_ENDPOINT_URL` environment variable) instead points a command at an emulator `lstk` did not start — a Docker Compose or host-network deployment, one running in CI or on another machine, or a LocalStack cloud-hosted ephemeral instance.
+
+```bash
+# Run against an emulator reachable at a custom URL
+lstk az group list --endpoint-url http://localhost:4566
+
+# Equivalent via the environment
+LSTK_ENDPOINT_URL=https://my-ephemeral-instance.localstack.cloud lstk status
+```
+
+The endpoint is resolved from, in order of precedence: the `--endpoint-url` flag, `LSTK_ENDPOINT_URL`, then `AWS_ENDPOINT_URL` (a full synonym for `LSTK_ENDPOINT_URL`, one tier lower).
+Both `http://` and `https://` URLs are accepted (any other scheme is rejected), and the scheme is preserved end-to-end, so `https://` ephemeral instances work.
+
+The commands that accept an external endpoint are the ones that only *talk to* an already-running emulator: `aws`, `az`, `terraform`/`tf`, `cdk`, `sam`, `status`, `reset`, and the `snapshot` `save`/`load`/`remove` subcommands (including the `lstk save`/`lstk load` aliases) and `list s3://…`.
+
+Commands that manage the emulator's lifecycle or on-disk state have no remote equivalent and **reject** any endpoint source: `start`, the bare `lstk`, `stop`, `restart`, `logs`, and `volume`.
+
+The emulator's type (AWS, Azure, or Snowflake) is auto-detected by probing the endpoint's health API — there is no override flag or config setting, and an inconclusive probe is a hard failure. The AWS-only tools (`terraform`, `cdk`, `sam`) reject an endpoint whose detected type is not AWS.
+
 ## Structured output
 
 The global `--json` flag makes a command emit a single, machine-readable JSON object on stdout instead of human-oriented text, for scripting and CI.
@@ -1282,7 +1345,8 @@ The following environment variables configure `lstk` itself (not the LocalStack
 
 | Variable                     | Description                                                                                                      |
 |:-----------------------------|:-----------------------------------------------------------------------------------------------------------------|
-| `LOCALSTACK_AUTH_TOKEN`      | Auth token for non-interactive runs or to skip browser login. Used when no keyring token is stored.              |
+| `LOCALSTACK_AUTH_TOKEN`      | Auth token for non-interactive runs or to skip browser login. Takes precedence over a token stored in the keyring. |
+| `LSTK_ENDPOINT_URL`          | Target an existing, externally-managed emulator at this URL (equivalent to `--endpoint-url`). `AWS_ENDPOINT_URL` is a lower-precedence synonym. See [Targeting an external emulator](#targeting-an-external-emulator). |
 | `LOCALSTACK_HOST`            | Override the host (and optional port) used when resolving and printing the emulator endpoint, and when writing the AWS CLI profile. Bypasses the `localhost.localstack.cloud` DNS probe. |
 | `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`).                        |
@@ -1294,10 +1358,20 @@ The following environment variables configure `lstk` itself (not the LocalStack
 | `LSTK_API_ENDPOINT`          | Override the LocalStack platform API base URL. Default: `https://api.localstack.cloud`.                          |
 | `LSTK_WEB_APP_URL`           | Override the LocalStack Web Application URL used for browser login. Default: `https://app.localstack.cloud`.     |
 
-When `DOCKER_HOST` is not set, `lstk` tries the default Docker socket and then probes common alternatives (Colima at `~/.colima/default/docker.sock` or `~/.config/colima/default/docker.sock`, OrbStack at `~/.orbstack/run/docker.sock`).
-
 When `LSTK_OTEL` is enabled, the standard `OTEL_EXPORTER_OTLP_*` environment variables are honored by the OpenTelemetry SDK.
 
+### Container runtime discovery
+
+`lstk` talks to a Docker-compatible runtime and works with Docker Desktop, Rancher Desktop, Colima, OrbStack, Lima, and Podman. When `DOCKER_HOST` is not set, it resolves the daemon endpoint in this order:
+
+1. **`DOCKER_HOST`**, if set, always wins.
+2. **`DOCKER_CONTEXT`** or the active Docker CLI context, when it is non-default and reachable (a stale or unreachable context is skipped rather than failing).
+3. On **Linux**, a live `/var/run/docker.sock` — a running Docker daemon is preferred over a co-installed runtime such as Podman.
+4. A probe of known runtime sockets (Docker Desktop, Rancher Desktop, Colima, OrbStack, Podman, Lima). Each candidate is dialed, not just checked for existence, so a leftover socket file never shadows a live daemon.
+5. The Docker SDK's own default.
+
+If no runtime is reachable, the error tailors its suggested start command (`rdctl start`, `colima start`, `podman machine start`, …) to the runtime it detects. Set `DOCKER_HOST` to point at a specific socket to bypass discovery entirely.
+
 ### Container-injected variables
 
 `lstk` injects several environment variables into the LocalStack container on every start, in addition to any profiles you configure:
@@ -1359,6 +1433,7 @@ Pair this behavior with a custom [`image`](#custom-container-image) that points
 
 `lstk` includes completion scripts for bash, zsh, fish, and powershell.
 If you installed via Homebrew, completions are set up automatically.
+Once completion is enabled, `lstk aws <TAB>` also completes AWS services, operations, and parameters using the AWS CLI's own completer.
 
 For manual setup:
 
@@ -1454,22 +1529,16 @@ port = "4566"
 
 ### Port 443 already in use
 
-By default, LocalStack binds to both port `4566` and port `443` inside the container (controlled by the `GATEWAY_LISTEN` variable).
-On some systems, particularly Windows with Hyper-V, IIS, or VPN software, port 443 may already be in use.
+By default, LocalStack publishes both port `4566` and port `443` (controlled by the `GATEWAY_LISTEN` variable).
+On some systems port 443 is already taken — Windows with Hyper-V, IIS, or VPN software, or an ingress proxy such as Rancher Desktop's Traefik.
 
-**Symptoms:**
-
-```text
-failed to start LocalStack: Error response from daemon: ports are not available:
-exposing port TCP 127.0.0.1:443 -> 127.0.0.1:0: listen tcp4 127.0.0.1:443: bind:
-address already in use
-```
+Because port 443 comes from the **default** `GATEWAY_LISTEN`, a busy 443 is **not fatal**: `lstk` drops that publication with a warning and starts anyway, and HTTPS is still served on the edge port `4566`. You only need to act if you want to silence the warning or bind 443 elsewhere.
 
-**Fix:** Override `GATEWAY_LISTEN` to bind only to port 4566:
+To skip port 443 entirely, override `GATEWAY_LISTEN` to bind only to `4566`:
 
 ```toml
 [[containers]]
-type = "aws"
+type = "azure"
 tag  = "latest"
 port = "4566"
 env  = ["nossl"]
@@ -1478,7 +1547,9 @@ env  = ["nossl"]
 GATEWAY_LISTEN = "0.0.0.0:4566"
 ```
 
-This tells the container to skip the port 443 binding entirely.
+:::note
+A port you list **explicitly** in a custom `GATEWAY_LISTEN` is treated as a hard requirement, so a busy one there fails the start rather than being dropped. Only the `443` from the default value is best-effort.
+:::
 
 ### Docker is not running
 
@@ -1489,9 +1560,8 @@ If Docker is not reachable, you will see an error like:
 Error: runtime not healthy
 ```
 
-**Fix:** Start Docker Desktop (macOS/Windows) or the Docker daemon (`sudo systemctl start docker` on Linux).
-If you use Colima or OrbStack, make sure the VM is running.
-You can also point `lstk` at a custom socket with `DOCKER_HOST`.
+**Fix:** Start your container runtime. `lstk` works with Docker Desktop, Rancher Desktop, Colima, OrbStack, Lima, and Podman — start the Docker daemon (`sudo systemctl start docker` on Linux) or the relevant VM (`rdctl start`, `colima start`, `podman machine start`, …). When the runtime is unavailable, `lstk`'s error tailors its suggested start command to whichever runtime it detects.
+You can also point `lstk` at a specific socket with `DOCKER_HOST`. See [Container runtime discovery](#container-runtime-discovery) for how the daemon is located.
 
 ### Authentication required in non-interactive mode
 

From 610128e340032fcf1ad2d23ce0651b91a3cbd380 Mon Sep 17 00:00:00 2001
From: George Tsiolis <george.tsiolis@localstack.cloud>
Date: Thu, 3 Sep 2026 08:44:22 +0000
Subject: [PATCH 05/10] docs(lstk): Azure does not support snapshots (only
 Snowflake is experimental)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../aws/developer-tools/running-localstack/lstk/snapshots.md   | 3 ++-
 src/content/docs/azure/developer-tools/lstk.mdx                | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md
index 21f9d4e6..3169687a 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/snapshots.md
@@ -13,7 +13,8 @@ The `snapshot` command groups six subcommands — `save`, `load`, `list`, `remov
 
 :::note
 Snapshots are best supported on the **AWS emulator**.
-`snapshot save`/`load` (and the `save`/`load` aliases) also work for the Snowflake and Azure emulators, but their snapshot support is experimental and not fully tested — for a non-AWS emulator `lstk` prints a warning such as `Snapshot support for the snowflake emulator is experimental and not fully tested.`
+`snapshot save`/`load` (and the `save`/`load` aliases) also work for the Snowflake emulator, but its snapshot support is experimental and not fully tested — `lstk` prints a warning such as `Snapshot support for the snowflake emulator is experimental and not fully tested.`
+The Azure emulator does not support snapshots.
 :::
 
 ## `snapshot save`
diff --git a/src/content/docs/azure/developer-tools/lstk.mdx b/src/content/docs/azure/developer-tools/lstk.mdx
index 1b76d7d4..965774fe 100644
--- a/src/content/docs/azure/developer-tools/lstk.mdx
+++ b/src/content/docs/azure/developer-tools/lstk.mdx
@@ -695,7 +695,8 @@ The `snapshot` command groups six subcommands — `save`, `load`, `list`, `remov
 
 :::note
 Snapshots are best supported on the **AWS emulator**.
-`snapshot save`/`load` (and the `save`/`load` aliases) also work for the Snowflake and Azure emulators, but their snapshot support is experimental and not fully tested — `lstk` prints a warning such as `Snapshot support for the snowflake emulator is experimental and not fully tested.`
+`snapshot save`/`load` (and the `save`/`load` aliases) also work for the Snowflake emulator, but its snapshot support is experimental and not fully tested — `lstk` prints a warning such as `Snapshot support for the snowflake emulator is experimental and not fully tested.`
+The Azure emulator does not support snapshots.
 [`reset`](#reset) remains **AWS-only** and errors out with `reset is only supported for the AWS emulator` otherwise.
 :::
 

From 64c9d0da9a0a5449152fa6914f9349351355892b Mon Sep 17 00:00:00 2001
From: George Tsiolis <george.tsiolis@localstack.cloud>
Date: Thu, 3 Sep 2026 10:48:44 +0000
Subject: [PATCH 06/10] docs(lstk): document --json for start and status
 (v0.23.0)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../running-localstack/lstk/automation.mdx                | 4 ++--
 .../running-localstack/lstk/lifecycle-commands.md         | 4 ++++
 src/content/docs/azure/developer-tools/lstk.mdx           | 8 ++++++--
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
index 3ef5d485..685adb1d 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
@@ -14,7 +14,7 @@ These options are available for all commands:
 | `--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](#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 `stop`, `reset`, and `update`; any other command rejects it. See [Structured output](#structured-output). |
+| `--json`            | Emit a single machine-readable JSON envelope on stdout instead of human-oriented output. Supported by `start`, `stop`, `status`, `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`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#selecting-the-emulator-with---type). |
 | `--snapshot <REF>`  | Snapshot REF to auto-load after start (on `start`/bare `lstk`; overrides config for one run) |
@@ -68,7 +68,7 @@ The emulator's type (AWS, Azure, or Snowflake) is auto-detected by probing the e
 ## Structured output
 
 The global `--json` flag makes a command emit a single, machine-readable JSON object on stdout instead of human-oriented text, for scripting and CI.
-JSON support is available per command: `stop`, `reset`, and `update` accept `--json`.
+JSON support is available per command: `start`, `stop`, `status`, `reset`, and `update` accept `--json`.
 Any other command rejects it with an error envelope (`error.code: NOT_JSON_CAPABLE`) rather than silently printing plain text.
 
 Every JSON-capable command writes **exactly one** JSON object with the following envelope shape:
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/lifecycle-commands.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/lifecycle-commands.md
index 486d6b89..5e059150 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/lifecycle-commands.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/lifecycle-commands.md
@@ -47,6 +47,8 @@ lstk start --persist
 For finer-grained control, you can also set `PERSISTENCE = "1"` in an environment profile (see [Passing environment variables to the container](/aws/developer-tools/running-localstack/lstk/configuration/#passing-environment-variables-to-the-container)).
 :::
 
+`start` supports [`--json`](/aws/developer-tools/running-localstack/lstk/automation/#structured-output) (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`, whether it was `alreadyRunning`, and whether `persistence` is enabled.
+
 ### 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.
@@ -178,6 +180,8 @@ SQS      my-queue     us-east-1  000000000000
 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, with the resource table shown at full width when stdout is not a TTY.
 The Snowflake and Azure emulators show the instance summary only and never report resources.
 
+`status` supports [`--json`](/aws/developer-tools/running-localstack/lstk/automation/#structured-output): the `data` payload lists one entry per configured emulator with its running state, health, version, host, and (for the AWS emulator) a `resourceSummary` and the deployed `resources`. Pass `--no-resources` to omit the resource details for a faster response when polling. `--json` also honors [`--endpoint-url`](/aws/developer-tools/running-localstack/lstk/automation/#targeting-an-external-emulator) to report on an emulator `lstk` did not start.
+
 ## `logs`
 
 Show or stream emulator logs.
diff --git a/src/content/docs/azure/developer-tools/lstk.mdx b/src/content/docs/azure/developer-tools/lstk.mdx
index 965774fe..3166a543 100644
--- a/src/content/docs/azure/developer-tools/lstk.mdx
+++ b/src/content/docs/azure/developer-tools/lstk.mdx
@@ -365,6 +365,8 @@ 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)).
 :::
 
+`start` supports [`--json`](#structured-output) (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`, whether it was `alreadyRunning`, and whether `persistence` is enabled.
+
 #### 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.
@@ -496,6 +498,8 @@ SQS      my-queue     us-east-1  000000000000
 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, with the resource table shown at full width when stdout is not a TTY.
 The Snowflake and Azure emulators show the instance summary only and never report resources.
 
+`status` supports [`--json`](#structured-output): the `data` payload lists one entry per configured emulator with its running state, health, version, and host. For the AWS emulator it also includes a `resourceSummary` and the deployed `resources`, which `--no-resources` omits for a faster response when polling. `--json` also honors [`--endpoint-url`](#targeting-an-external-emulator) to report on an emulator `lstk` did not start.
+
 ### `logs`
 
 Show or stream emulator logs.
@@ -1222,7 +1226,7 @@ These options are available for all commands:
 | `--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](#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 `stop`, `reset`, and `update`; any other command rejects it. See [Structured output](#structured-output). |
+| `--json`            | Emit a single machine-readable JSON envelope on stdout instead of human-oriented output. Supported by `start`, `stop`, `status`, `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) |
@@ -1276,7 +1280,7 @@ The emulator's type (AWS, Azure, or Snowflake) is auto-detected by probing the e
 ## Structured output
 
 The global `--json` flag makes a command emit a single, machine-readable JSON object on stdout instead of human-oriented text, for scripting and CI.
-JSON support is available per command: `stop`, `reset`, and `update` accept `--json`.
+JSON support is available per command: `start`, `stop`, `status`, `reset`, and `update` accept `--json`.
 Any other command rejects it with an error envelope (`error.code: NOT_JSON_CAPABLE`) rather than silently printing plain text.
 
 Every JSON-capable command writes **exactly one** JSON object with the following envelope shape:

From db9a277d3a372626cfeb3b1a0de20e5929700704 Mon Sep 17 00:00:00 2001
From: George Tsiolis <george.tsiolis@localstack.cloud>
Date: Sun, 6 Sep 2026 16:29:13 +0000
Subject: [PATCH 07/10] docs(lstk): fix Docker Compose FAQ to point at
 --endpoint-url

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../running-localstack/lstk/faq-and-troubleshooting.md    | 8 ++++----
 src/content/docs/azure/developer-tools/lstk.mdx           | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
index fb87e35a..d80fd39e 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
@@ -9,11 +9,11 @@ tags: ['Hobby']
 
 ### Can I use `lstk` with Docker Compose?
 
-No. `lstk` manages its own Docker container directly.
-If you use a `docker-compose.yml` to run LocalStack, you do not need `lstk`, and vice versa.
-Do not mix `lstk start` with a Docker Compose setup; they are separate, independent methods.
+Yes, for the commands that talk to an already-running emulator.
+`lstk start` and the other lifecycle commands manage their own Docker container and are not meant to drive a Compose-managed instance, so don't point `lstk start` at one.
+But if you run LocalStack from a `docker-compose.yml`, you can still use `lstk`'s emulator-facing commands against it — `aws`, `az`, `terraform`/`cdk`/`sam`, `status`, `reset`, and `snapshot` — by passing `--endpoint-url <url>` (or setting `LSTK_ENDPOINT_URL`) to target the Compose deployment.
 
-For Docker Compose configuration, see the [Docker Compose installation guide](/aws/getting-started/installation/#docker-compose).
+See [Targeting an external emulator](/aws/developer-tools/running-localstack/lstk/automation/#targeting-an-external-emulator) for the commands that accept an endpoint, and the [Docker Compose installation guide](/aws/getting-started/installation/#docker-compose) for the Compose setup itself.
 
 ### Which Docker image does `lstk` use?
 
diff --git a/src/content/docs/azure/developer-tools/lstk.mdx b/src/content/docs/azure/developer-tools/lstk.mdx
index 3166a543..e5864f41 100644
--- a/src/content/docs/azure/developer-tools/lstk.mdx
+++ b/src/content/docs/azure/developer-tools/lstk.mdx
@@ -1495,11 +1495,11 @@ Restart your shell after persisting completions.
 
 ### Can I use `lstk` with Docker Compose?
 
-No. `lstk` manages its own Docker container directly.
-If you use a `docker-compose.yml` to run LocalStack, you do not need `lstk`, and vice versa.
-Do not mix `lstk start` with a Docker Compose setup; they are separate, independent methods.
+Yes, for the commands that talk to an already-running emulator.
+`lstk start` and the other lifecycle commands manage their own Docker container and are not meant to drive a Compose-managed instance, so don't point `lstk start` at one.
+But if you run LocalStack from a `docker-compose.yml`, you can still use `lstk`'s emulator-facing commands against it — `aws`, `az`, `terraform`/`cdk`/`sam`, `status`, `reset`, and `snapshot` — by passing `--endpoint-url <url>` (or setting `LSTK_ENDPOINT_URL`) to target the Compose deployment.
 
-For Docker Compose configuration, see the [Docker Compose installation guide](/aws/getting-started/installation/#docker-compose).
+See [Targeting an external emulator](#targeting-an-external-emulator) for the commands that accept an endpoint, and the [Docker Compose installation guide](/aws/getting-started/installation/#docker-compose) for the Compose setup itself.
 
 ### Which Docker image does `lstk` use?
 

From a879299f39bd9b3ab60c7ecdee244322a2b6324f Mon Sep 17 00:00:00 2001
From: Quetzalli <alejandra.olvera.novack@gmail.com>
Date: Mon, 7 Sep 2026 19:09:26 +0200
Subject: [PATCH 08/10] docs(lstk): move Global options table to the Overview
 page

Resolves the open placement thread: Global options (--config,
--non-interactive, --json, --persist, --type, --snapshot,
--no-snapshot, --timeout, --endpoint-url, -v, -h) apply to everyday
interactive use, not just automation/CI, so burying them on the
Automation & CI page under-served readers who never get that far.

Move the table itself to index.mdx, right after Quick start and
before Shell completions, since it's the first page every reader
hits. Leave the detailed sections it links out to (Structured
output, Targeting an external emulator) on automation.mdx, since
those really are CI/scripting-specific, and fix their anchors to
point at the automation page now that the table lives elsewhere.

Agreed with @mmaureenliu and @peter-smith-phd on this placement in
the PR thread.
---
 .../running-localstack/lstk/automation.mdx    | 20 +---------------
 .../running-localstack/lstk/index.mdx         | 24 +++++++++++++++++--
 2 files changed, 23 insertions(+), 21 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
index 685adb1d..29142548 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/automation.mdx
@@ -1,28 +1,10 @@
 ---
 title: lstk Automation & CI
-description: Global options, non-interactive mode, structured JSON output, environment variables, tracing, and logging for scripting lstk.
+description: Non-interactive mode, structured JSON output, targeting an external emulator, environment variables, tracing, and logging for scripting lstk.
 template: doc
 tags: ['Hobby']
 ---
 
-## 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](#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 `start`, `stop`, `status`, `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`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#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`)          |
-| `--timeout <duration>` | Startup readiness deadline for `start`/bare `lstk`, as a Go duration; overrides `LSTK_STARTUP_TIMEOUT` for one run. See [`start`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#start). |
-| `-v`, `--version`   | Print the version and exit                                                 |
-| `-h`, `--help`      | Print help and exit                                                        |
-
 ## Interactive and non-interactive mode
 
 `lstk` automatically selects its output mode:
diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
index 1f2e336b..093c0468 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
@@ -24,13 +24,13 @@ Running `lstk` with no arguments takes you through the entire startup flow autom
 
 This section is split into focused pages:
 
-- **Overview** (this page): installation, quick start, and shell completions.
+- **Overview** (this page): installation, quick start, global options, and shell completions.
 - [Authentication](/aws/developer-tools/running-localstack/lstk/authentication/): logging in and out, and how `lstk` resolves your auth token.
 - [Configuration](/aws/developer-tools/running-localstack/lstk/configuration/): the `config.toml` file, emulator types, environment variables, and volumes.
 - [Lifecycle commands](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/): `start`, `stop`, `restart`, `status`, `logs`, `reset`, `volume`.
 - [Cloud & IaC commands](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/): `aws`, `az`, `terraform`, `cdk`, `sam`.
 - [Snapshots](/aws/developer-tools/running-localstack/lstk/snapshots/): save and load emulator state with `snapshot save`/`load`/`list`/`remove`/`show`/`versions`.
-- [Automation & CI](/aws/developer-tools/running-localstack/lstk/automation/): global options, non-interactive mode, structured output, targeting an external emulator, and environment variables.
+- [Automation & CI](/aws/developer-tools/running-localstack/lstk/automation/): non-interactive mode, structured output, targeting an external emulator, and environment variables.
 - [Setup & maintenance](/aws/developer-tools/running-localstack/lstk/setup-and-maintenance/): `setup`, `config`, `update`, and offline/enterprise environments.
 - [FAQ & Troubleshooting](/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting/).
 
@@ -106,6 +106,26 @@ 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.
 
+## 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](/aws/developer-tools/running-localstack/lstk/automation/#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 `start`, `stop`, `status`, `reset`, and `update`; any other command rejects it. See [Structured output](/aws/developer-tools/running-localstack/lstk/automation/#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`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#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`)          |
+| `--timeout <duration>` | Startup readiness deadline for `start`/bare `lstk`, as a Go duration; overrides `LSTK_STARTUP_TIMEOUT` for one run. See [`start`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#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](/aws/developer-tools/running-localstack/lstk/automation/) for the details behind `--non-interactive`, `--json`, and `--endpoint-url`.
+
 ## Shell completions
 
 `lstk` includes completion scripts for bash, zsh, fish, and powershell.

From c7e7722100f46e85d15213aa2b42a3215e2ce8d8 Mon Sep 17 00:00:00 2001
From: George Tsiolis <george.tsiolis@localstack.cloud>
Date: Mon, 7 Sep 2026 17:21:09 +0000
Subject: [PATCH 09/10] docs(lstk): apply reviewer wording to Docker Compose
 FAQ (lstk stop)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../running-localstack/lstk/faq-and-troubleshooting.md          | 2 +-
 src/content/docs/azure/developer-tools/lstk.mdx                 | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md b/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
index d80fd39e..19646f1a 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting.md
@@ -10,7 +10,7 @@ tags: ['Hobby']
 ### Can I use `lstk` with Docker Compose?
 
 Yes, for the commands that talk to an already-running emulator.
-`lstk start` and the other lifecycle commands manage their own Docker container and are not meant to drive a Compose-managed instance, so don't point `lstk start` at one.
+`lstk start`, `lstk stop`, and the other lifecycle commands manage their own Docker container and are not meant to drive a Compose-managed instance, so don't point `lstk stop` at one.
 But if you run LocalStack from a `docker-compose.yml`, you can still use `lstk`'s emulator-facing commands against it — `aws`, `az`, `terraform`/`cdk`/`sam`, `status`, `reset`, and `snapshot` — by passing `--endpoint-url <url>` (or setting `LSTK_ENDPOINT_URL`) to target the Compose deployment.
 
 See [Targeting an external emulator](/aws/developer-tools/running-localstack/lstk/automation/#targeting-an-external-emulator) for the commands that accept an endpoint, and the [Docker Compose installation guide](/aws/getting-started/installation/#docker-compose) for the Compose setup itself.
diff --git a/src/content/docs/azure/developer-tools/lstk.mdx b/src/content/docs/azure/developer-tools/lstk.mdx
index e5864f41..36e9b033 100644
--- a/src/content/docs/azure/developer-tools/lstk.mdx
+++ b/src/content/docs/azure/developer-tools/lstk.mdx
@@ -1496,7 +1496,7 @@ Restart your shell after persisting completions.
 ### Can I use `lstk` with Docker Compose?
 
 Yes, for the commands that talk to an already-running emulator.
-`lstk start` and the other lifecycle commands manage their own Docker container and are not meant to drive a Compose-managed instance, so don't point `lstk start` at one.
+`lstk start`, `lstk stop`, and the other lifecycle commands manage their own Docker container and are not meant to drive a Compose-managed instance, so don't point `lstk stop` at one.
 But if you run LocalStack from a `docker-compose.yml`, you can still use `lstk`'s emulator-facing commands against it — `aws`, `az`, `terraform`/`cdk`/`sam`, `status`, `reset`, and `snapshot` — by passing `--endpoint-url <url>` (or setting `LSTK_ENDPOINT_URL`) to target the Compose deployment.
 
 See [Targeting an external emulator](#targeting-an-external-emulator) for the commands that accept an endpoint, and the [Docker Compose installation guide](/aws/getting-started/installation/#docker-compose) for the Compose setup itself.

From 8f5dee666f991312c163b023aa2af59cc425a01d Mon Sep 17 00:00:00 2001
From: Quetzalli <alejandra.olvera.novack@gmail.com>
Date: Mon, 7 Sep 2026 19:27:49 +0200
Subject: [PATCH 10/10] docs(lstk): remove em dash from Global options
 cross-reference

---
 .../docs/aws/developer-tools/running-localstack/lstk/index.mdx  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
index 093c0468..c7a02b28 100644
--- a/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
+++ b/src/content/docs/aws/developer-tools/running-localstack/lstk/index.mdx
@@ -124,7 +124,7 @@ These options are available for all commands:
 | `-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](/aws/developer-tools/running-localstack/lstk/automation/) for the details behind `--non-interactive`, `--json`, and `--endpoint-url`.
+These apply to both interactive and non-interactive (scripted/CI) use, see [Automation & CI](/aws/developer-tools/running-localstack/lstk/automation/) for the details behind `--non-interactive`, `--json`, and `--endpoint-url`.
 
 ## Shell completions