Mention the lstk CLI in the localstack CLI docs by gtsiolis · Pull Request #700 · localstack/localstack-docs

gtsiolis · 2026-06-12T11:18:48Z

Summary

Adds a short note to the top of the LocalStack CLI reference pointing readers to lstk, our new Go-based CLI, and aligns the lstk page so the two pages describe lstk consistently.

It also replaces the auto-generated "This documentation was auto-generated from LocalStack CLI version …" note, which wasn't useful and was reliably out of date. That version is captured only when the monthly update-cli-docs workflow runs (the 15th), so it always trails the actual release — the page read 2026.4.0 while 2026.5.x had been on PyPI for weeks (2026.5.0 shipped 5 days after the last regeneration). A stamp that's accurate for ~1 day a month is worse than none.

Changes

The LocalStack CLI page is auto-generated by scripts/generate_cli_docs.py, so that change is made in the generator and mirrored into the current output:

scripts/generate_cli_docs.py — replace the version provenance :::note with a pointer to lstk; remove the now-dead version plumbing (the localstack --version call + unused parameter).
localstack-cli.md — the regenerated note.
lstk.mdx — update the top note and the "difference between lstk and the localstack CLI" FAQ to reflect that lstk now covers lifecycle, monitoring, and storage (snapshot), and that both CLIs work with Cloud Pods (lstk via snapshot, localstack via pod). This supersedes the earlier early-release note (Update the lstk early release note #698); snapshot/Cloud Pods support has since shipped.

Rendered notes:

LocalStack CLI page: lstk is our new Go-based CLI with an interactive terminal UI for lifecycle (start, stop), monitoring (status, logs), storage (snapshot), and more.

lstk page: lstk covers the everyday emulator workflow: lifecycle (start, stop), monitoring (status, logs), storage (snapshot), and more.

Follow-up

Documenting the lstk snapshot command in detail and the terraform/az/setup proxy commands is tracked separately and will land in its own PR.

Fix PRO-312

cloudflare-workers-and-pages · 2026-06-12T11:18:50Z

Deploying localstack-docs with Cloudflare Pages

Latest commit:	`852edee`
Status:	✅ Deploy successful!
Preview URL:	https://6bfa2c0c.localstack-docs.pages.dev
Branch Preview URL:	https://pro-312-mention-lstk-cli-in.localstack-docs.pages.dev

View logs

quetzalliwrites · 2026-06-12T11:34:46Z

cc @mmaureenliu for visibility since she is just now logging tickets for this doc too :)

mmaureenliu · 2026-06-12T16:00:21Z

-Both tools can start, stop, and manage the LocalStack emulator.
-`lstk` is a newer CLI built in Go with a TUI, while the `localstack` CLI is the established Python-based tool with support for Cloud Pods, Extensions, Ephemeral Instances, and other advanced features.
+Both tools can start, stop, and manage the LocalStack emulator, and both work with Cloud Pods — `lstk` via its `snapshot` command and the [`localstack` CLI](/aws/tooling/localstack-cli/) via its `pod` command.
+`lstk` is a newer CLI built in Go with a TUI; the `localstack` CLI is the established Python-based tool that additionally supports Extensions, Ephemeral Instances, and other advanced features `lstk` doesn't cover yet.


@gtsiolis considering that we will deprecate localstack without adding support for things like Extensions and Ephemeral Instances to lstk, do we really want to highlight it?

When we deprecate localstack, we'll update docs to only mention the webapp route of using those features not supported in lstk (e.g. Ephemeral Instance, Extensions) and just don't say anything CLI.

You're right, probably not worth highlighting.

For context, the goal was to make lstk discoverable from the localstack CLI page.

I will remove ephemeral instances and extensions mention next week, but you are also welcome to take this over and push any changes or merge before that.

Removed, see #700 (comment).

quetzalliwrites · 2026-06-15T19:03:38Z

@@ -458,11 +457,11 @@ Restart your shell after persisting completions.

 ### What is the difference between `lstk` and the `localstack` CLI?


hey @gtsiolis, we don't want to have a mention of the soon to be deprecated localstack cli in the lstk doc. We should keep this doc only focused on lstk.

And since we're fully deprecating the LS cli, to me this is another reason we don't need this section moving fwd :)

DEAL. I was aiming to making minimal changes in this PR, removed in 852edee.

The Developer Tools restructure (#691) moved the localstack-cli and lstk pages under /aws/developer-tools/running-localstack/. Update the cross-links in the generated CLI doc, its generator, and the lstk FAQ to match. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Keep the lstk doc focused only on lstk. With the localstack CLI being deprecated, the doc shouldn't compare against it or highlight features (Extensions, Ephemeral Instances) that lstk won't add. Discoverability of lstk still flows from the localstack CLI page note, which is unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

gtsiolis · 2026-06-16T10:15:34Z

Can someone take another look? 👀

mmaureenliu

I did a complete re-read of the entire article and left quite a few comments/questions. None are blocking so I've approved already, but I do want them addressed at some point.

mmaureenliu · 2026-06-16T14:46:37Z

 ## Prerequisites

 - [Docker](https://docs.docker.com/get-docker/) installed and running.
 - A [LocalStack account](https://app.localstack.cloud/sign-up) with a valid [Auth Token](/aws/getting-started/auth-token/).


For lstk purpose, do they really need to know about the auth token? I thought it's not possible to NOT have a personal auth token if you have an account. More relevant here is to have an account and have a license assigned for whichever LocalStack product you want to use.

mmaureenliu · 2026-06-16T14:48:04Z

 lstk
 ```

 Running `lstk` without arguments performs the full startup sequence: resolves your auth token by opening the LocalStack Web Application, pulls the latest image if needed, and starts the LocalStack container.


Again, is it really necessary to mention the auth token? From user perspective they just need to know that lstk handles the authentication flow.

mmaureenliu · 2026-06-16T14:50:02Z

 Running `lstk` without arguments performs the full startup sequence: resolves your auth token by opening the LocalStack Web Application, pulls the latest image if needed, and starts the LocalStack container.
 In an interactive terminal it launches the TUI; in a non-interactive environment it prints plain text output.

 For CI or headless environments, set `LOCALSTACK_AUTH_TOKEN` and use `--non-interactive`:


Here it's actually worth explaining you need a CI auth token and points to the CI auth token section of the auth token page (eventually this will be nearer the top of the doc and we'll de-emphasize personal auth token).

mmaureenliu · 2026-06-16T15:00:33Z

 lstk --config /path/to/config.toml start
 ```

 ### Default configuration


Is this out of date? e.g. type options. Does this get updated when we re-run the generate scripts?

mmaureenliu · 2026-06-16T15:01:12Z


 | Field    | Type     | Default    | Description                                                                                        |
 | :------- | :------- | :--------- | :------------------------------------------------------------------------------------------------- |
 | `type`   | string   | `"aws"`    | Emulator type. Only `"aws"` is supported.                                                          |


Same comment as above.

mmaureenliu · 2026-06-16T15:12:56Z

 | `GATEWAY_LISTEN`        | `:4566,:443`          | Ports the emulator binds inside the container |
 | `MAIN_CONTAINER_NAME`   | `localstack-aws`      | Container name for internal references        |

 The container also gets the Docker socket mounted (if detected) and port mappings for `4566`, `443`, and the service port range `4510-4559`.


service port range only applies to aws emulator?

mmaureenliu · 2026-06-16T15:17:47Z

-
 ### Can I use `lstk` with Docker Compose?

 No. `lstk` manages its own Docker container directly.


Well, if the configs are compatible, you can use lstk to interact with (e.g. view status, view logs, manage snapshots) the localstack instance started with docker-compose, but should leave lifecycle management to docker-compose.

No need to change right now but we do need to have a good think on whether we want to recommend complementing docker-compose with the CLI.

mmaureenliu · 2026-06-16T15:18:24Z


 No. LocalStack uses a single Docker image: `localstack/localstack`.
 There is no separate "community" or "pro" image.
 All plans (including the free Hobby tier) use the same image and require an auth token.


I'd say require a license, not auth token.

mmaureenliu · 2026-06-16T15:20:21Z

 ### Image pull failed

 If `lstk` cannot pull the Docker image, check your network connection and Docker configuration.
 On corporate networks, you may need to configure Docker's proxy settings.


Worth reference the appropriate troubleshooting guide (I think we have one for networking troubleshooting)

mmaureenliu · 2026-06-16T15:22:40Z


 ### Getting help

 If the steps above don't resolve your issue, [contact us](https://localstack.cloud/contact/) or open an issue on the [lstk GitHub repository](https://github.com/localstack/lstk/issues).


The contact form isn't a great format for reporting issues, better point to get help pages.

The lstk GH issues are currently empty, but in case people actually use it, do we actually monitor it?

i.e. since everybody should have a localstack account, can we just ask them to email support?

gtsiolis requested review from HarshCasper, quetzalliwrites and remotesynth as code owners June 12, 2026 11:18

gtsiolis force-pushed the pro-312-mention-lstk-cli-in-localstack-cli-docs branch from 4be89f2 to 83eab98 Compare June 12, 2026 11:27

quetzalliwrites requested a review from mmaureenliu June 12, 2026 11:34

gtsiolis self-assigned this Jun 12, 2026

mmaureenliu reviewed Jun 12, 2026

View reviewed changes

gtsiolis mentioned this pull request Jun 15, 2026

Update LocalStack CLI Documentation #702

Merged

quetzalliwrites reviewed Jun 15, 2026

View reviewed changes

gtsiolis and others added 3 commits June 16, 2026 12:39

Mention the lstk CLI in the localstack CLI docs

2341a91

Align the lstk page note and FAQ with snapshot support

c43d20e

gtsiolis force-pushed the pro-312-mention-lstk-cli-in-localstack-cli-docs branch from 83eab98 to e22353c Compare June 16, 2026 09:43

gtsiolis requested a review from mmaureenliu June 16, 2026 10:15

gtsiolis mentioned this pull request Jun 16, 2026

Expand lstk CLI reference documentation #701

Open

mmaureenliu approved these changes Jun 16, 2026

View reviewed changes

		@@ -458,11 +457,11 @@ Restart your shell after persisting completions.

		### What is the difference between `lstk` and the `localstack` CLI?


		### Can I use `lstk` with Docker Compose?

		No. `lstk` manages its own Docker container directly.


		### Getting help

		If the steps above don't resolve your issue, [contact us](https://localstack.cloud/contact/) or open an issue on the [lstk GitHub repository](https://github.com/localstack/lstk/issues).

Conversation

gtsiolis commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Follow-up

Uh oh!

cloudflare-workers-and-pages Bot commented Jun 12, 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!

quetzalliwrites commented Jun 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quetzalliwrites Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gtsiolis Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gtsiolis commented Jun 16, 2026

Uh oh!

mmaureenliu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gtsiolis commented Jun 12, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jun 12, 2026 •

edited

Loading

quetzalliwrites Jun 15, 2026 •

edited

Loading

gtsiolis Jun 16, 2026 •

edited

Loading