docs(lstk hotfix): update CLI reference to v1.0.0

[gtsiolis]

Motivation

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

v1.0.0 itself is the major-version release bump — its only commits over v0.23.0 are release plumbing (ci.yml, .goreleaser.yaml) and a test fix, with nothing under cmd/, internal/, or docs/ — so there is no CLI-surface delta from v0.23.0, and the reference content here is accurate for v1.0.0 as-is.

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.

Review-round fixes

• Docker Compose FAQ corrected. The first FAQ answered a flat "No"; it now explains that lstk's emulator-facing commands (aws, az, terraform/cdk/sam, status, reset, snapshot) can target a Compose-run LocalStack via --endpoint-url / LSTK_ENDPOINT_URL, while lstk start and the other lifecycle commands still manage their own container. Applied to both the AWS FAQ page and the Azure page.
• "Global options" table relocated to the Overview page (index.mdx), right after Quick start, since these flags apply to everyday interactive use, not just automation/CI. The CI-specific deep dives (Structured output, Targeting an external emulator) stay on automation.mdx, cross-linked from the table.

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 (and the Global-options placement) 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 and the Global-options placement forward. The Azure edits here overlap #909 — coordinate on merge order.

Review

Recommended: mostly additive reference content verified against the v1.0.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:	dbffaa1
Status:	✅  Deploy successful!
Preview URL:	https://acdd7d33.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?

[quetzalliwrites]

Yes, @mmaureenliu, I've come up with a solution. Adding it in a new commit.

[quetzalliwrites]

Agreed with both of you. Moved the "Global options" table to index.mdx (the Overview page), right after Quick start. Reasoning: these flags apply to everyday interactive use (--config, --persist, --type, --snapshot, etc.), not just automation/CI, so the Overview page, the first thing every reader hits, is the right home. Left the CI-specific deep dives (Structured output, Targeting an external emulator) on automation.mdx, cross-linked from the table.

Since Azure (#909) and Snowflake (#910) are still open and haven't inherited this page split's IA yet, I'll carry this same placement into both before merging them, so all three product lines land consistent from day one rather than drifting and needing a follow-up fix later.

Pushed as a879299f. Also retitled the PR to v1.0.0 per the note below, since that's the current release tag and there's no CLI-surface delta from v0.23.0.

[gtsiolis]

The v1.0.0 retitle checks out — I verified the CLI surface directly: v0.23.0..v1.0.0 is only three commits, all release plumbing (.github/workflows/ci.yml, .goreleaser.yaml, and an update_test.go timing fix), with nothing touched under cmd/, internal/, or docs/. v1.0.0 is the major-version bump with no user-facing CLI change, so the reference content here stands accurate as-is for v1.0.0 — no further doc edits needed for the release.

The Global-options → index.mdx move reads well, and both it and the earlier Docker Compose FAQ fix build green on Cloudflare Pages. Carrying the same placement into the Azure (#909) and Snowflake (#910) restructures sounds right.

One bookkeeping note: the tracking ticket (DOC-433) still reads v0.23.0 — it should track v1.0.0 to match the retitle. I can't update Linear from here right now (the connector needs re-authorization), so flagging it so it isn't missed.

---

Generated by Claude Code

[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

[gtsiolis]

lstk v1.0.0 is now released. The v0.23.0 → v1.0.0 range contains no user-facing CLI changes — it is a major-version marker (#489) plus a goreleaser config tweak (#488) and a test fix (#485); nothing under cmd/ or internal/config/ changed. A fresh full walk of the v1.0.0 CLI surface matches the corrections and additions already in this PR, so this content is accurate for v1.0.0 as-is and no follow-up commits are needed.

Optional before merge (human decision): retitle to update CLI reference to v1.0.0 so the reference tracks the current release tag. DOC-433 still applies.

---

Generated by Claude Code

[mmaureenliu]

Only my minor edit suggestions for FAQs left (I thought I posted them but obviously not). Not blocking so I'll approve now.