Allow permanently disabling lstk update checks

[joe4dev]

Motivation

lstk asks to update on every start with no way to turn it off. With weekly releases, "skip this version" buys a few days — the reporter sees the prompt almost daily.

It is also wrong when another tool owns the binary. mise, nix, asdf, scoop and chocolatey manage the version themselves; replacing it desynchronises them, and on nix the store is read-only so the update fails after a full download.

Solution

[cli] update_check, also LSTK_UPDATE_CHECK:

mode	behaviour
prompt	today's blocking prompt (default)
notify	one non-blocking line
off	no check, no output, no network request

Externally-managed installs default to notify and name the manager rather than advising lstk update. lstk update refuses on them (--force overrides); an explicit lstk update and lstk update --check are never gated by the setting.

Prompt: before / after

Before	After
[S] Skip this version — per-version, buys days	[N] Never ask again — persists update_check = "notify"

[S] is removed rather than kept alongside [N]: it is the option the ticket says does not solve the problem, it was the third way to say "no" on one prompt, and it was the only per-version persisted state — a stale skip silenced even notify mode. cli.update_skipped_version goes with it; a leftover key is inert.

Docs

Docs needed

New user-facing surface to document:

• [cli] update_check config key and the LSTK_UPDATE_CHECK environment variable (prompt / notify / off), and that neither gates an explicit lstk update.
• Externally-managed installs (mise, nix, guix, asdf, scoop, chocolatey) default to notify and are not updated in place; lstk update --force overrides.
• --json gains the UPDATE_EXTERNALLY_MANAGED error code (docs/structured-output.md updated in this PR).
• The update prompt loses [S] Skip this version and gains [N] Never ask again.

Manual testing (using fish shell) — 13 scenarios, all passing

Covered: each of the three modes; env var overriding config; an invalid value rejected rather than coerced; a mise install naming the manager in its note; lstk update refusing on mise and nix (plain and --json); a read-only install directory refused; update --check still working under off; [N] persisting update_check = 'notify' and the next run only noting; the first-run prompt omitting [N]; and a mise install refusing to prompt even under an explicit prompt.

To replicate. Build a version-stamped binary (a dev build skips the check entirely) and point Docker at nothing, so start emits the update output and then fails at the health check without starting an emulator:

set SMOKE (mktemp -d)
go build -ldflags "-X github.com/localstack/lstk/internal/version.version=0.0.1" -o $SMOKE/bin/lstk .
set -x DOCKER_HOST tcp://localhost:1
printf '[[containers]]\ntype = "aws"\ntag  = "latest"\nport = "4566"\n\n[cli]\n' > $SMOKE/config.toml
set M $SMOKE/mise/.local/share/mise/installs/github-localstack-lstk/latest
mkdir -p $M; cp $SMOKE/bin/lstk $M/

# modes
HOME=$SMOKE $SMOKE/bin/lstk --config $SMOKE/config.toml start --non-interactive        # note
HOME=$SMOKE LSTK_UPDATE_CHECK=off $SMOKE/bin/lstk --config $SMOKE/config.toml start --non-interactive   # silent
HOME=$SMOKE LSTK_UPDATE_CHECK=quiet $SMOKE/bin/lstk --config $SMOKE/config.toml start --non-interactive # rejected

# externally managed
HOME=$SMOKE $M/lstk --config $SMOKE/config.toml start --non-interactive   # note names mise
HOME=$SMOKE $M/lstk update                                                # refuses
HOME=$SMOKE $M/lstk update --json                                         # UPDATE_EXTERNALLY_MANAGED

# interactive (needs a TTY)
HOME=$SMOKE $SMOKE/bin/lstk --config $SMOKE/config.toml start             # [U] / [R] / [N]

Pressing [U] performs a real download; set LSTK_UPDATE_GITHUB_API_ENDPOINT and LSTK_UPDATE_GITHUB_DOWNLOAD_ENDPOINT to a dead address to make it inert.

Open questions

Where the update prompt sits in the start flow. NotifyUpdate runs as the first action of the start goroutine, ahead of the Docker health check, auth, and the emulator picker. On a genuine first run config.toml does not exist yet — the picker creates it — so [N] has nowhere to persist and is omitted rather than offered and silently dropped:

The trade-off: moving the notification after the picker would make [N] available on every run, but prompting early is worth more — a user on an old or broken CLI should be offered the update before the CLI attempts real work, and a late prompt would be preempted by exactly the Docker failure an update might fix. The gap is narrow, since a first run almost always means a fresh install already on the latest version. Deliberately left as is; flagging it for a second opinion.

Review

Worth a human review. New user-facing surface (config key, env var, flag, error code) and a changed prompt, plus one behaviour change that is not opt-in: a detected mise/nix/asdf install silently defaults to notify.

Automatic detection of externally managed (e.g., mise package installer) provides convenience by default, but add a bunch of complexity. The alternative would be solely relying on manual configuration.

Openspec preview: https://github.com/localstack/lstk/tree/7838fda1ee900535f4375f612919153606c1684b/openspec/changes/add-update-check-config

Related

#465 was an earlier, independent attempt at the same design, closed 2026-08-25.

#482 extending updates for extensions

Closes DEVX-1029

[joe4dev]

@gtsiolis What's your thought regarding the open question (see Section "Open questions")? Do you see a UX issue in having the [N] Never ask again option skipped at the first run?

[joe4dev]

@carillan81 What's your suggestion on how update notifications for bundled extensions work in this context (e.g., externally-managed lstk)? Do we to treat lstk and lstk extension updates separately? Happy to discuss.
⚠️ I think we should align #482 and this PR to avoid unintended interactions.

[carillan81]

Extensions are only updated when lstk is updated. They are a package and there is no way to update extensions right now if they are not updated with lstk. That specific PR is specific to include extensions in the update process of a manually installed lstk. I don't see any need of notifications.

[joe4dev]

Extensions are only updated when lstk is updated. They are a package and there is no way to update extensions right now if they are not updated with lstk. That specific PR is specific to include extensions in the update process of a manually installed lstk. I don't see any need of notifications.

Great, thank you for the clarification @carillan81 👍

Then, our PRs complement each other nicely ✨