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

[gtsiolis]

Motivation

The lstk CLI reference reflected roughly v0.20.x, while the latest release is v0.23.0. This catches up the full v0.21.0 → v0.23.0 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, lifecycle-commands.md, 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

v0.21.0 → v0.22.2

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. 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 (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 completion note.

v0.23.0 delta

• --json is now supported by start and status (previously only stop/reset/update). Updated the global-options table and the "Structured output" section on both pages, and added per-command --json notes to start (flat data object) and status (data.emulators[], plus the --no-resources toggle and --json --endpoint-url targeting). AWS-only resource details are labeled as such on the shared Azure page.

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.23.0 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:	64c9d0d
Status:	✅  Deploy successful!
Preview URL:	https://bc4895ee.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

[mmaureenliu]

Looks good in general. Minor fixes required. I assume tech details are correct after @anisaoshafi has done the eng review.

[mmaureenliu]

I think this belongs to the "Cloud and IaC Commands" section as this option is quite important for local dev use case. @peter-smith-phd what do you think?

[gtsiolis]

It lives in the global-options table because --endpoint-url is a persistent/global flag that applies across many commands (aws, az, the IaC tools, status, reset, snapshot), not just the IaC ones — and the full "Targeting an external emulator" section is right below it. I've also cross-referenced it from the Cloud & IaC page's intro note so it's discoverable from there. Happy to move the detailed section into Cloud & IaC (or duplicate a short callout there) if you and @peter-smith-phd prefer that placement — leaving this open for your call rather than restructuring unilaterally.

---

Generated by Claude Code

[peter-smith-phd]

I agree the --endpoint-url can apply to multiple commands, not just IaC commands. Basically, anything that communicates with the emulator can use it (including snapshot, reset, etc).

However, I don't understand why the global options are hidden down on the automation.mdx page. These apply for interactive use, not just for automation, and should be much sooner in the docs.

[gtsiolis]

Agreed on the scope — the docs already frame --endpoint-url as applying to any command that talks to the emulator (aws, az, the IaC tools, status, reset, snapshot), so nothing to change there.

On placement: the "Global options" section living on the Automation & CI page is inherited from the multi-page split (#898), not something this PR introduced — this PR is a content-accuracy sync. You and Maureen are both pointing at the same thing from different angles: Maureen suggested moving it under Cloud & IaC, but your point that these are global and interactive-facing (not IaC-specific, not automation-specific) argues against burying them under either.

Concrete proposal: lift the "Global options" table to the reference landing page (index.mdx) so it's the first thing a reader hits, and leave the detailed "Targeting an external emulator" section where it is (cross-referenced), mirroring the same move on the Azure page. That reshapes the split's IA and overlaps the Azure restructure (#909), so I'd rather not fold it into this sync PR unilaterally — happy to do it as a small follow-up, or add it here if you'd prefer it in one go. Your call; leaving this open.

---

Generated by Claude Code

[mmaureenliu]

@quetzalliwrites are you able to find a better placing for these global options so they are easier to find and also obvious that they apply to all commands?

[mmaureenliu]

@peter-smith-phd do you think it makes sense to apply your update to the first FAQ answer directly in this PR?

[gtsiolis]

Update: extended to v0.23.0

lstk v0.23.0 shipped, so this PR now catches up the reference to that tag (the range is v0.21.0 → v0.23.0). Retitled and description updated; DOC-433 renamed to match.

The only user-facing delta since v0.22.2 is structured --json output landing on start and status (previously stop/reset/update only). Applied to both the AWS multi-page reference and the Azure page:

• Global-options --json row and the "Structured output" section now list start, stop, status, reset, update.
• Added a per-command --json note to start (flat data object) and status (data.emulators[], the --no-resources toggle, and --json --endpoint-url targeting). Resource details are labeled AWS-only on the shared Azure page.

The rest of v0.22.2 → v0.23.0 is deps bumps, a dev sandbox script, an internal PTY-input fix, and the internal IAC error-code group — nothing that changes the documented CLI surface.

The two open review threads (the --endpoint-url placement question and the shared-components question) are untouched by this and still awaiting your call.

Cc @localstack/devx for visibility and any corrections.

---

Generated by Claude Code

[mmaureenliu]

@peter-smith-phd do you want to take this opportunity to fix the first FAQ?