docs(lstk hotfix): update CLI reference to v0.22.2

[gtsiolis]

Motivation

The lstk CLI reference reflected roughly v0.20.x, while the latest release is v0.22.2. This catches up the full v0.21.0 → v0.22.2 backlog — fixing claims that no longer match the CLI and documenting features that shipped in that range — and folds in the corrections from the three superseded doc-sync PRs (#833, #850, #877) that were closed when the docs were restructured.

Reference surfaces in scope

There are no shared lstk components, so content lives directly in the pages.

• AWS — the canonical multi-page reference under src/content/docs/aws/developer-tools/running-localstack/lstk/: index.mdx, authentication.md, configuration.mdx, cloud-and-iac-commands.md, snapshots.md, automation.mdx, faq-and-troubleshooting.md, setup-and-maintenance.md.
• Azure — src/content/docs/azure/developer-tools/lstk.mdx (the single-page reference), brought to the same accuracy.

What changed

Corrections (stale / no longer accurate):

• Auth token resolution order was inverted. LOCALSTACK_AUTH_TOKEN takes precedence over a keyring token (v0.21+); the docs said the opposite and told users to lstk logout first. Fixed on both pages (resolution list, admonition, env-var table).
• "Port 443 already in use" described a hard failure. In v0.22.2 the auto-added 443 is dropped with a warning (HTTPS stays on 4566); only an explicitly-listed port is a hard requirement. Rewrote it (and fixed the Azure page's example, which used type = "aws").
• "Docker is not running" named only Colima/OrbStack → now the full runtime set.
• Azure snapshots — experimental (same warning as Snowflake), not "not yet supported".

Additions (present in v0.22.2, previously undocumented):

• --endpoint-url / LSTK_ENDPOINT_URL — new "Targeting an external emulator" section, plus global-options and env-var rows and cross-references.
• snapshot versions subcommand and pod:<name>:<version> refs on load/show.
• lstk aws --account leading flag, with a "Selecting the account" section.
• container_name and expose_ports config fields.
• Container runtime discovery — full runtime set, resolution order (DOCKER_HOST → DOCKER_CONTEXT/CLI context → Linux socket → probe → SDK default), and the tailored start-command hint.
• Binary self-update SHA-256 checksum verification; lstk az consuming its own flags; lstk aws <TAB> completion note.

Snowflake

There is no lstk reference page under src/content/docs/snowflake/ on main yet — it is being introduced by #910. There is nothing to correct there; these same fixes should be folded into #910 (and into the Azure restructure #909) since both are copies of this shared content.

Needs a human decision

The Azure (#909) and Snowflake (#910) lstk doc restructures split this same content into the multi-page layout. Whichever of these merges first, the other must carry these corrections forward. The Azure edits here overlap #909 — coordinate on merge order.

Review

Recommended: mostly additive reference content verified against the v0.22.2 CLI surface, but the auth-token precedence reversal and the Port 443 drop-with-warning reframing are user-facing behavior corrections worth a second look.

Closes DOC-433

Cc @localstack/devx for visibility and any corrections.

[cloudflare-workers-and-pages]

Deploying localstack-docs with    Cloudflare Pages

Latest commit:	800fe40
Status:	✅  Deploy successful!
Preview URL:	https://33616e54.localstack-docs.pages.dev
Branch Preview URL:	https://claude-hopeful-babbage-21z8t.localstack-docs.pages.dev

View logs

[gtsiolis]

The one red check here is Validate Refs, which is the repo's branch-naming gate (feature-branch-only-to-main.yml): a PR into main must have a head branch named aws-docs-* or snowflake-docs-*. This branch is claude/hopeful-babbage-21z8t2, so it fails the gate.

This is unrelated to the docs changes themselves — Cloudflare Pages built the site successfully and the preview renders. The same check is red on the sibling in-flight lstk doc PRs (#909, #910), which target main from doc-429-*/doc-430-* branches for the same reason, so this isn't specific to this PR's content.

I can't rename the branch to satisfy the gate from here (the branch name is fixed for this change). A maintainer can either merge via the usual docs flow that bypasses this check, or re-target/rename onto an aws-docs-* feature branch. Flagging rather than working around it.

---

Generated by Claude Code

[gtsiolis]

Update: expanded scope to the Azure page + folded in the superseded PRs

Since the last round, this PR now also brings azure/developer-tools/lstk.mdx to v0.22.2 accuracy, and folds in the corrections from the three closed doc-sync PRs (#833, #850, #877) that never merged. The PR description has been rewritten to match.

Applied to both the AWS multi-page reference and the Azure page:

• Auth-token precedence reversed (LOCALSTACK_AUTH_TOKEN wins over the keyring).
• --endpoint-url / LSTK_ENDPOINT_URL — new "Targeting an external emulator" section + table rows.
• snapshot versions subcommand and pod:<name>:<version> refs.
• lstk aws --account + "Selecting the account".
• container_name and expose_ports config fields.
• Container runtime discovery (full runtime set, resolution order, tailored start hint).
• "Port 443 already in use" rewritten (drop-with-warning, not fatal; Azure example corrected to type = "azure").
• "Docker is not running" now names the full runtime set.
• Self-update SHA-256 checksum; lstk az consuming its own flags; lstk aws <TAB> completion note.
• Azure snapshots noted as experimental (not "unsupported").

Snowflake: there's no lstk page under snowflake/ on main yet (it's being added by #910), so nothing to correct there — these same fixes should land in #910 and in the Azure restructure #909, both of which are copies of this shared content.

Review threads: all three resolved — the --account wording (fixed) and the two AWS/Azure/Snowflake-scope questions (mentions kept intentionally, now consistent across both pages).

CI: Cloudflare Pages builds green on the current head; the only red is the Validate Refs branch-naming gate, which the docs-team PRs trip too and which doesn't re-run on pushes.

Cc @localstack/devx for visibility and any corrections.

---

Generated by Claude Code