Show one tip on first start, document completion setup in the CLI

[joe4dev]

Motivation

#484 introduced a UX regression by rendering two tips on the first lstk startup (shell completion + rotation tip). Furthermore, the review also flagged the long docs URL as poor terminal UX.

Solution

One tip per run, enforced structurally rather than by convention.

• selectTip (new internal/container/tips.go) is the only place that decides which tip to show, and it returns one string, not a list. The first-run completion tip outranks the rotating per-emulator tips: first run happens once per install, while the rotating tips come back on every later start.
• container.Start is the only place that emits it. Its body moved to an unexported start, leaving the public entry point a thin wrapper around the single emit. emitPostStartPointers no longer emits a tip, and internal/ui no longer emits one either — RunOptions.CompletionTip is replaced by StartOptions.FirstRun.

Adding a tip now means ranking it inside selectTip; there is nowhere else to put it. The rule is written up under "Post-start tips" in CLAUDE.md.

The tip names a command instead of linking to docs.

> Tip: Set up tab completion: lstk completion

A URL in terminal output can't be clicked, rots, and drifts from an already-shipped binary. So lstk completion now carries the setup instructions itself; the per-shell subcommands forward to it, and lstk docs renders it, which makes the CLI the source and the docs site the follower.

User-visible change: a first interactive start shows the completion tip and nothing else. Every other run is unchanged, rotation included.

Shell completion

Bare lstk completion (and lstk completion --help) now prints:

Generate shell completion scripts for lstk.

To load completions:

Bash:

  # Load in current session
  eval "$(lstk completion bash)"

  # Load in new sessions (Linux)
  echo 'eval "$(lstk completion bash)"' >> ~/.bashrc

  # Load in new sessions (macOS)
  echo 'eval "$(lstk completion bash)"' >> ~/.bash_profile

Zsh:

  # Load in current session
  autoload -Uz compinit && compinit
  source <(lstk completion zsh)

  # Load in new sessions (Linux, macOS)
  echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
  echo 'source <(lstk completion zsh)' >> ~/.zshrc

Fish:

  # Load in current session
  lstk completion fish | source

  # Load in new sessions (Linux, macOS)
  lstk completion fish > ~/.config/fish/completions/lstk.fish

PowerShell:

  # Load in current session
  lstk completion powershell | Out-String | Invoke-Expression

  # Load in new sessions (Windows, Linux, macOS)
  if (!(Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }
  lstk completion powershell | Out-File -Append -Encoding utf8 $PROFILE

Every recipe is the same shape: the current-session command, or that same command appended to the shell's startup file.

Optional alternatives considered and dropped

Verified on macOS 15 / Apple Silicon.

Dropped option	Why
Zsh: lstk completion zsh > "${fpath[1]}/_lstk"	fpath[1] is root-owned on stock macOS (/usr/local/share/zsh/site-functions), so a normal user gets permission denied. It doesn't exist on stock macOS yielding zsh: no such file or directory. Under oh-my-zsh it is a plugin directory. On my private mac, it points to ~/.docker/completions
Zsh: lstk completion zsh > $(brew --prefix)/share/zsh/site-functions/_lstk	Silently does nothing on macOS's built-in zsh — that directory is not on the default $fpath (default fpath[1] is the Intel prefix while Homebrew sits at /opt/homebrew). It needs Homebrew's own zsh, or FPATH="$(brew --prefix)/share/zsh/site-functions:${FPATH}" before compinit.
Bash: lstk completion bash > /etc/bash_completion.d/lstk and the $(brew --prefix)/etc/bash_completion.d/lstk variant	Both need the bash-completion package, which the eval form does not — lstk's script ships its own _get_comp_words_by_ref fallback (DEVX-950). They only buy lazy loading on first Tab instead of sourcing at every shell start.
Guarding the startup-file lines, e.g. [[ $commands[lstk] ]] && source <(lstk completion zsh)	Would avoid command not found: lstk in every new shell after an uninstall, but roughly doubles the length of each line. Happy to add it to bash and zsh if reviewers prefer.

Two things that look optional but are not:

• The zsh compinit line is required. Cobra's generated script calls compdef on line 2, and compdef does not exist until compinit has run — without it you get compdef: command not found and nothing registers. A duplicate compinit (oh-my-zsh already runs one) is harmless. Sourcing costs ~8 ms per shell start.
• PowerShell uses Out-File -Encoding utf8 rather than >>, which writes UTF-16LE on PowerShell 5.1 and leaves a profile the shell cannot parse.

Docs

The CLI is now the source of truth for shell-completion setup, and the docs site should follow it rather than the reverse.

Handled in localstack/localstack-docs#937, which rewrites the Shell completions section to match lstk completion — the page currently recommends ${fpath[1]} and the Homebrew site-functions path for zsh (neither works on stock macOS — see the table above), omits the required compinit step, and has no PowerShell instructions. The same section is duplicated on the Azure page; that PR updates both.

No new command, flag, or env var. The first-start tip no longer links to the docs, so the #shell-completions anchor is no longer referenced from the CLI.

Manual Testing

First startup tip

No more docs link and adjusted message:

Shell Completions

• @joe4dev I tested Bash, Zsh, Fish, PowerShell on macOS and PowerShell on Windows
• @dfangl Bash and Zsh on Linux (Fish and PS should be the same as macOS)

Review

Human review advised — it changes user-facing output and help text on the shared start path, and @gtsiolis raised the original concern on #484, so it's worth confirming this is the resolution he had in mind.

Related

Towards DEVX-821

Docs PR with synchronized shell completion changes: localstack/localstack-docs#937

• Preview: https://devx-821-lstk-shell-completi.localstack-docs.pages.dev/aws/developer-tools/running-localstack/lstk/#shell-completions

[gtsiolis]

Thanks for tackling this, @joe4dev! Left some comments, let me know what you think!

[gtsiolis]

Nearly perfect, adding a latest screenshot of the current state for reference. 🏁