Point users at shell completion setup on first start

[joe4dev]

Motivation

Only Homebrew installs get shell completion set up automatically (homebrew_casks.completions). npm and GitHub-release users have to find the docs themselves, so a shipped time-saving feature goes mostly unused.

Solution

Emit one line after the first successful interactive start, pointing at lstk completion [bash|zsh|fish|powershell] and the docs section:

> Tip: Enable tab completion for your shell: lstk completion [bash|zsh|fish|powershell] See https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/#shell-completions

Two deliberate deviations from the ticket: the trigger is the first run, not install (no install path offers a usable hook — npm's package.json is generated, a postinstall that edits a shell rc is hostile and is skipped under --ignore-scripts, and binary installs have no hook), and it is a pointer, not a prompt — lstk never writes to the user's shell config. An automated lstk completion --write was designed and dropped in favour of this because the big complexity (cross-platform, cross-shell, cross-install-method) is not worth maintaining for a small gain.

Needs no new persisted state: firstRun means "config.toml was absent", and that same path creates the config, so the tip cannot repeat. Interactive-only, so CI and --json output are unchanged. Prefix and severity match tipsForType, whose tip renders directly above it.

The wording follows the Verb ...: <command> shape the neighbouring tips already use.

The main_test.go/awsconfig_test.go part of the diff is test plumbing: these tests isolate HOME under t.TempDir() and start a real emulator, whose container writes root-owned files into the bind-mounted volume that Go's TempDir cleanup cannot delete on Linux. awsconfig_test.go already solved this; scheduleVolumeCleanup extracts it so there is one copy rather than two.

Manual testing

make build
export LOCALSTACK_AUTH_TOKEN=<token>
H=$(mktemp -d)

HOME=$H bin/lstk start   # accept AWS at the emulator picker
#   -> last line is the "> Tip: Enable tab completion ..." line above

HOME=$H bin/lstk start   # tip must NOT reappear (config now exists)
HOME=$H bin/lstk stop

HOME=$(mktemp -d) bin/lstk start --json   # envelope must contain no tip

Screenshot from manual testing:

• Tip appears on first launch
• Tip does not appear on subsequent commands

Docs

No documentation change needed — the tip points at the existing "Shell completions" section and adds no command, flag, or env var. Worth knowing that the CLI now links to that section directly, so the #shell-completions anchor should stay stable.

Review

Human review advised — new user-facing output on the shared start path.

Todo

• Manual testing (see above)

Closes DEVX-821

[anisaoshafi]

Thanks for the thorough integration testing, looks robust 👏🏼

[gtsiolis]

Showing two tips side-by-side is a UX regression. ⚠️ Cc @joe4dev @anisaoshafi

Things that can help:

1. Rotating the tip
2. Showing more instructions after DEVX-877

[joe4dev]

Showing two tips side-by-side is a UX regression. ⚠️ Cc @joe4dev @anisaoshafi

Things that can help:

1. Rotating the tip
2. Showing more instructions after DEVX-877

@gtsiolis Should we only show the completion tip upon first launch and suppress the default tip (lstk status); i.e., enforcing max 1 tip?
This only applies to the very first launch of lstk.

[gtsiolis]

Enforcing max one tip would be great, that's why we added the tip rotation. Otherwise we will definitely end up with multiple tips listed as every new thing would race for attention.

I remember opening PRO-245 few months ago specifically for promoting for auto-completion. Options to consider:

1. Detect the shell and show appropriate commands
2. Prompt for adding auto-completion step-by-step as described in the issue
3. Using a short URL is highly recommended for such terminal output

[joe4dev]

Enforcing max one tip would be great, that's why we added the tip rotation.

Good point. I can create a follow-up PR (EDIT: see draft here) and suppress other tips on first launch.

3. Using a short URL is highly recommended for such terminal output

❓ How do we configure such short URLs ? Do we have an example?

Regarding the other options:

1. Detect the shell and show appropriate commands

I started designing such a solution, but reconsidered in favor of a simple approach (completion is also irrelevant for agents):

An automated lstk completion --write was designed and dropped in favour of this because the big complexity (cross-platform, cross-shell, cross-install-method) is not worth maintaining for a small gain.

2. Prompt for adding auto-completion step-by-step as described in the issue

Thanks for sharing PRO-245

That could be a viable middle-ground. We'd need keep it in sync with the docs (https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/#shell-completions) and do further testing (e.g., powershell instructions are missing).

[joe4dev]

@gtsiolis Can you have a look at #495 whether it addresses your UX feedback?
It enforces the max one tip approach (see screenshots in PR).