docs(lstk): update CLI reference to v0.15.0 by gtsiolis · Pull Request #749 · localstack/localstack-docs

gtsiolis · 2026-07-02T12:31:09Z

What

Brings the lstk CLI reference up to date with the current CLI surface. This is the first automated pass triggered by the v0.15.0 release, so it was a full audit of the live CLI (lstk --help and every subcommand) against the doc rather than a single-release diff.

The doc was last expanded around v0.12/v0.13 and had never documented several features that already shipped by then. This PR catches up the full backlog through v0.15.0.

Additions

CLI/IaC proxy tools — new sections for az (incl. az start-interception / az stop-interception), terraform (alias tf), cdk, and sam: usage, the leading --region/--account flags, offline-vs-running-emulator behavior, minimum tool versions, and supported env vars (AWS_ENDPOINT_URL, LSTK_TF_CMD, LSTK_SAM_CMD, LSTK_CDK_CMD, etc.).
setup azure — isolated AZURE_CONFIG_DIR setup that routes lstk az to the Azure emulator.
snapshot show — new subcommand (cloud-only).
S3 remotes — snapshot save/load/list now accept s3://bucket/prefix with a separate pod-name positional and a --profile flag; documented credential precedence and the running-emulator requirement for list s3://….
Snapshot auto-load on start — the snapshot config field, plus global --snapshot <ref> / --no-snapshot flags.
Config fields — image (Docker image override), volumes (bind mounts) with a new Volume mounts section, and snapshot.
Extensions — new section documenting Git-style lstk-<name> dispatch and the LSTK_EXT_* runtime context.
Noted that host LOCALSTACK_-prefixed env vars are forwarded to the emulator on start.

Corrections (stale content)

setup aws is no longer interactive-only: it now has a --force flag and a non-interactive mode (writes the profile with defaults and exits 0). Removed the "requires an interactive terminal / no flag to auto-confirm" note.
snapshot now works for the Snowflake and Azure emulators too, with an experimental-support warning — it is no longer AWS-only. Only reset remains strictly AWS-only. Updated the "four subcommands" count to five.

Needs a human eye

Public-messaging wording for the experimental Snowflake/Azure snapshot warning and the CDK/SAM "known limitations vs. samlocal/azlocal" notes — I mirrored the CLI's own phrasing, but confirm it matches how we want to position maturity externally.
The tool proxies (az/terraform/cdk/sam) and extensions are documented inline in the reference; if a fuller standalone guide is planned, these sections may want to link out to it later.

Cc @localstack/devx for visibility and any corrections.

Generated by Claude Code

cloudflare-workers-and-pages · 2026-07-02T12:32:10Z

Deploying localstack-docs with Cloudflare Pages

Latest commit:	`40ec6bc`
Status:	✅ Deploy successful!
Preview URL:	https://169368e6.localstack-docs.pages.dev
Branch Preview URL:	https://claude-sleepy-ritchie-lvio4k.localstack-docs.pages.dev

View logs

Bring the lstk CLI reference up to date with the current CLI surface (last documented around v0.12/v0.13, now v0.15.0): - Document the CLI/IaC proxy tools: az (+ start/stop-interception), terraform (tf), cdk, sam. - Add setup azure; correct setup aws (now has --force and a non-interactive mode, no longer interactive-only). - Add snapshot show and S3-remote support for snapshot save/load/list (--profile, credential precedence, running-emulator requirement). - Note snapshot now works for Snowflake/Azure with an experimental warning; only reset stays AWS-only. - Add global --snapshot/--no-snapshot flags and snapshot auto-load on start; document LOCALSTACK_ env forwarding. - Add config fields image, volumes, and snapshot; add a Volume mounts section. - Add an Extensions section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QRmA1n8vtvoT3DnGQzRk87

gtsiolis · 2026-07-02T13:49:43Z

Not sure why @nik-localstack and @pinzon were added above[1] as reviewers. Cc @quetzalliwrites @remotesynth

gtsiolis · 2026-07-02T13:49:50Z

Cc @mmaureenliu for visibility

quetzalliwrites · 2026-07-02T14:11:39Z

@gtsiolis hey! the reason it pings the other two folks is because our codeowner's file is going to add the engineer service owner listed

gtsiolis · 2026-07-02T14:14:22Z

Ah, I see. But the file mentioned[1] has nothing to do with the change in this PR, maybe it's a fallback or I guess we don't have an engineer assigned for the lstk CLI?

quetzalliwrites · 2026-07-06T09:31:07Z

I am ok with these changes, but I can't sign off until a PM owner approves for something important like lstk.

@mmaureenliu may we get your ok on this one? :)

(I will also ping her offline, as she may not see this comment on github, but in a slack dm she won't miss visibility)

mmaureenliu

Great job! I've added a few comments, mostly clarification from user point view. Thanks for the great effort!

mmaureenliu · 2026-07-07T09:42:45Z

+| `--region <region>` | Deployment region (default `us-east-1`; falls back to `AWS_REGION`). |
+| `--account <id>`    | Target AWS account id, 12 digits (default `test`; falls back to `AWS_ACCESS_KEY_ID`). |
+
+Commands that don't contact AWS (`fmt`, `validate`, `version`, and `init` when no S3 backend is declared) run without a running emulator; everything else requires the AWS emulator to be running and Docker healthy.


change "AWS" to "emulator" - this applies to all emulators.

- Drop legacy-CLI comparisons ("no per-tool wrapper", "mirroring v1's AUTO_LOAD_POD") — how it works now, not the old xxx-local mapping. - Defer the Extensions section (and its intro mention) until there is a meaningful extension to document. - Remove the duplicated intro note. - Soften snapshot emulator-support framing: no top-level "AWS emulator only" on the config field; note some snapshot features are fully supported only on AWS for now and point to per-emulator docs. - Reword "status resources" to "the resources listing in status". - Volume mounts: fix the init-hook example to mount a script file (not a directory), make it emulator-neutral, drop the untested read-only mount, add an explanation, and link the per-emulator Initialization Hooks guides. - Azure interception: drop "second"/secondary framing and the line steering users away from interception (it is the recommended mode). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QRmA1n8vtvoT3DnGQzRk87

gtsiolis · 2026-07-07T09:56:48Z

Thanks @mmaureenliu! Pushed 40ec6bc addressing the review. Summary of what changed:

Legacy-CLI comparisons removed — dropped "with no per-tool wrapper" (intro) and "mirroring v1's AUTO_LOAD_POD" (snapshot auto-load). Doc now describes only how it works today.
Extensions deferred — removed the ## Extensions section and its intro mention; happy to bring it back as a sub-page once there's a meaningful extension (e.g. a deploy command) to frame it around what it does.
Duplicated intro note removed.
Snapshot emulator support — removed the top-level "AWS emulator only" on the snapshot config field, and reworded the emulator-types line to say some snapshot features are fully supported only on AWS for now, pointing to the per-emulator docs. (The snapshot-command note lower down still documents the exact experimental warning the CLI prints for Snowflake/Azure, since you confirmed that's expected.)
"status resources" → "the resources listing in status".
Volume mounts — rewrote the init-hook example to mount a script file into /etc/localstack/init/ready.d/ (was a directory), made it emulator-neutral, dropped the untested read-only mount, added an explanation, and linked the per-emulator Initialization Hooks guides (AWS, Snowflake).
Azure interception — dropped "second"/secondary framing and removed the line steering users toward the isolated mode, since interception is the recommended mode in the Azure docs.

Two of your comments need a quick note back:

"Does reset not work for other emulators?" — correct, reset is AWS-only today; the CLI returns reset is only supported for the AWS emulator for Snowflake/Azure. I kept reset in the AWS-only list and the snapshot note documents this. Let me know if you'd prefer different wording.
"change AWS to emulator" on the Terraform line (…requires the AWS emulator to be running) — I left this one as-is because the terraform/cdk/sam proxies only work against the AWS emulator (they're AWS IaC tools), so "the AWS emulator" is intentional there. If you meant a different line, point me at it and I'll fix it.

Generated by Claude Code

quetzalliwrites · 2026-07-07T14:54:29Z

hey @gtsiolis appreciate the quick addressing of Maureen's feedback, your reply is super detailed too.

One thing, please make sure to resolve each feedback comment after you address them. Otherwise it can appear like it was missed and it's harder for the reviewer to track down each line item fixed.

quetzalliwrites · 2026-07-07T14:54:43Z

@mmaureenliu this is ready for you again! tyvm

mmaureenliu

LGTM. I've asked the terraform question in #lstk channel and let's leave as is for now (I suspect you are right that our tflocal only supports aws). I did add an extra comment regarding a part not touched by current update, but is non-blocking.

mmaureenliu · 2026-07-08T12:52:33Z


 It depends on the emulator type configured in your `config.toml`.
 The AWS emulator uses `localstack/localstack-pro`, the Snowflake emulator uses `localstack/snowflake`, and the Azure emulator uses `localstack/localstack-azure`.
 All require a valid auth token (including the free Hobby tier).


Unrelated to current update, but I found this when I read the whole doc again - I think it's more correct to say "All require a valid license". An auth token only identifies the user and doesn't guarantee entitlement to product use, and if I remember correctly a registered user always has an auth token.

gtsiolis requested review from HarshCasper, quetzalliwrites and remotesynth as code owners July 2, 2026 12:31

gtsiolis force-pushed the claude/sleepy-ritchie-lvio4k branch from 9130fa3 to 02bc8e5 Compare July 2, 2026 12:32

gtsiolis requested review from nik-localstack and pinzon as code owners July 2, 2026 12:32

gtsiolis changed the base branch from main to aws-docs-release-july July 2, 2026 12:33

gtsiolis requested review from a team, carole-lavillonniere and mmaureenliu and removed request for nik-localstack and pinzon July 2, 2026 13:51

mmaureenliu requested changes Jul 7, 2026

View reviewed changes

gtsiolis requested a review from mmaureenliu July 7, 2026 10:06

gtsiolis self-assigned this Jul 7, 2026

quetzalliwrites approved these changes Jul 8, 2026

View reviewed changes

quetzalliwrites merged commit fb19ccb into aws-docs-release-july Jul 8, 2026
1 check passed

quetzalliwrites deleted the claude/sleepy-ritchie-lvio4k branch July 8, 2026 11:35

mmaureenliu reviewed Jul 8, 2026

View reviewed changes

Uh oh!

Conversation

gtsiolis commented Jul 2, 2026

What

Additions

Corrections (stale content)

Needs a human eye

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying localstack-docs with Cloudflare Pages

Uh oh!

gtsiolis commented Jul 2, 2026

Uh oh!

gtsiolis commented Jul 2, 2026

Uh oh!

quetzalliwrites commented Jul 2, 2026

Uh oh!

gtsiolis commented Jul 2, 2026

Uh oh!

quetzalliwrites commented Jul 6, 2026

Uh oh!

mmaureenliu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mmaureenliu Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gtsiolis commented Jul 7, 2026

Uh oh!

quetzalliwrites commented Jul 7, 2026

Uh oh!

quetzalliwrites commented Jul 7, 2026

Uh oh!

Uh oh!

mmaureenliu left a comment

Choose a reason for hiding this comment

Uh oh!

mmaureenliu Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cloudflare-workers-and-pages Bot commented Jul 2, 2026 •

edited

Loading