|
| 1 | +### `volume` |
| 2 | + |
| 3 | +Manage the emulator volume: the host directory that holds persistent state such as certificates, downloaded tools, and persistence data. |
| 4 | + |
| 5 | +```bash |
| 6 | +lstk volume path |
| 7 | +lstk volume clear [options] |
| 8 | +``` |
| 9 | + |
| 10 | +#### `volume path` |
| 11 | + |
| 12 | +Prints the resolved volume directory for every emulator in your config, one per line. |
| 13 | +With the default config (a single `aws` emulator) it prints one path. |
| 14 | +Each path is the container's configured `volume` value, or the default OS cache location if `volume` is unset (`~/Library/Caches/lstk/volume/localstack-aws` on macOS, `~/.cache/lstk/volume/localstack-aws` on Linux). |
| 15 | + |
| 16 | +```bash |
| 17 | +# Print the volume directory for each configured emulator |
| 18 | +lstk volume path |
| 19 | +``` |
| 20 | + |
| 21 | +#### `volume clear` |
| 22 | + |
| 23 | +Removes all data from the emulator volume directory, resetting cached state. |
| 24 | +It operates on all configured emulators by default, or a single one with `--type`. |
| 25 | +Before clearing, it lists each target as `<emulator>: <path> (<size>)`. |
| 26 | + |
| 27 | +| Option | Description | |
| 28 | +|:----------------|:------------------------------------------| |
| 29 | +| `--force` | Skip the confirmation prompt | |
| 30 | +| `--type <type>` | Clear only the emulator of this type | |
| 31 | + |
| 32 | +```bash |
| 33 | +# Clear all configured emulator volumes (prompts for confirmation) |
| 34 | +lstk volume clear |
| 35 | + |
| 36 | +# Clear only the AWS emulator volume |
| 37 | +lstk volume clear --type aws |
| 38 | + |
| 39 | +# Skip the confirmation prompt |
| 40 | +lstk volume clear --force |
| 41 | + |
| 42 | +# Clear without prompting in a non-interactive environment |
| 43 | +lstk volume clear --type snowflake --force |
| 44 | +``` |
| 45 | + |
| 46 | +In an interactive terminal, `lstk volume clear` prompts `Clear volume data? This cannot be undone` before deleting anything; choosing **NO** or pressing Ctrl+C cancels with no changes. |
| 47 | +In non-interactive mode, `--force` is required, otherwise the command fails with `volume clear requires confirmation; use --force to skip in non-interactive mode`. |
| 48 | + |
| 49 | +:::caution |
| 50 | +If the volume contains files owned by `root` (created by Docker), clearing fails with a permission error. |
| 51 | +Re-run with elevated privileges: |
| 52 | + |
| 53 | +```bash |
| 54 | +sudo lstk volume clear |
| 55 | +``` |
| 56 | +::: |
| 57 | + |
| 58 | +### `login` |
| 59 | + |
| 60 | +Authenticate with LocalStack via a browser-based device authorization flow and store the resulting credential in your system keyring. |
| 61 | +This command requires an interactive terminal. |
| 62 | + |
| 63 | +```bash |
| 64 | +lstk login |
| 65 | +``` |
| 66 | + |
| 67 | +`lstk` opens your default browser to the LocalStack Web Application, shows a one-time code, and waits for you to approve the request. |
| 68 | +If the browser cannot open automatically, `lstk` prints the URL to visit manually. |
| 69 | +On success it stores the **license token** returned by the platform (not the raw browser bearer token). |
| 70 | + |
| 71 | +If you are already authenticated — either `LOCALSTACK_AUTH_TOKEN` is set or a token already exists in storage — `login` prints `You're already logged in` and exits without starting a new flow. |
| 72 | + |
| 73 | +In non-interactive mode (piped output, CI, or `--non-interactive`), `login` fails with `login requires an interactive terminal`. |
| 74 | +The `--config <path>` flag selects which `config.toml` is loaded, which affects `keyring`, `web_app_url`, and `api_endpoint` resolution. |
| 75 | + |
| 76 | +:::note |
| 77 | +If you approve the request in the browser only *after* pressing a key in the terminal, `lstk` reports `auth request not confirmed - please complete the authentication in your browser`. |
| 78 | +Re-run `lstk login` and approve in the browser before continuing. |
| 79 | +::: |
| 80 | + |
| 81 | +The credential is written to the system keyring (service `lstk`, key `lstk.auth-token`). |
| 82 | +When the keyring is unavailable — or `LSTK_KEYRING=file` is set — `lstk` stores it in a file at `<config-dir>/auth-token` (mode `0600`) instead. |
| 83 | + |
| 84 | +Endpoints used by the flow can be overridden via config or environment: |
| 85 | + |
| 86 | +| Config key | Env var | Default | Description | |
| 87 | +|:---------------|:---------------------|:---------------------------------|:-----------------------------------------------------------------------------| |
| 88 | +| `keyring` | `LSTK_KEYRING` | (system keyring) | Set to `file` to force file-based token storage instead of the OS keyring. | |
| 89 | +| `web_app_url` | `LSTK_WEB_APP_URL` | `https://app.localstack.cloud` | Base URL used to build the browser authorization link. | |
| 90 | +| `api_endpoint` | `LSTK_API_ENDPOINT` | `https://api.localstack.cloud` | LocalStack platform API endpoint used for the device flow and license token. | |
| 91 | + |
| 92 | +```bash |
| 93 | +# Force file-based token storage during login |
| 94 | +LSTK_KEYRING=file lstk login |
| 95 | + |
| 96 | +# Use a specific config file |
| 97 | +lstk --config ./.lstk/config.toml login |
| 98 | +``` |
| 99 | + |
| 100 | +### `logout` |
| 101 | + |
| 102 | +Remove stored authentication credentials. |
| 103 | + |
| 104 | +```bash |
| 105 | +lstk logout |
| 106 | +lstk logout --non-interactive |
| 107 | +``` |
| 108 | + |
| 109 | +`logout` deletes the auth token from your system keyring (falling back to the file-based token at `<config-dir>/auth-token` when the keyring is unavailable or `LSTK_KEYRING=file` is set) and removes the cached license file. |
| 110 | +On success it prints `Logged out successfully`. |
| 111 | + |
| 112 | +The outcome depends on how you are authenticated: |
| 113 | + |
| 114 | +| Situation | Behavior | |
| 115 | +|:----------|:---------| |
| 116 | +| A token is stored (from `lstk login`) | The token is deleted from the keyring and file fallback, the cached license is removed, and `lstk` prints `Logged out successfully`. | |
| 117 | +| No stored token, but `LOCALSTACK_AUTH_TOKEN` is set | Nothing is deleted. `lstk` prints a note that you are authenticated via the environment variable and to unset it to log out. | |
| 118 | +| No stored token and no `LOCALSTACK_AUTH_TOKEN` | `lstk` prints `Not currently logged in` and exits successfully. | |
| 119 | + |
| 120 | +:::note |
| 121 | +`logout` never clears the `LOCALSTACK_AUTH_TOKEN` environment variable, and it does not stop running emulators. |
| 122 | +If a LocalStack emulator is still running after logout, `lstk` prints a note reminding you it is running in the background; run `lstk stop` to stop it. |
| 123 | +::: |
| 124 | + |
| 125 | +### `config` |
| 126 | + |
| 127 | +Manage CLI configuration. |
| 128 | +`config` has no behavior of its own; run it with a subcommand. |
| 129 | + |
| 130 | +#### `config path` |
| 131 | + |
| 132 | +Print the resolved path to the active `config.toml`. |
| 133 | + |
| 134 | +```bash |
| 135 | +lstk config path |
| 136 | +``` |
| 137 | + |
| 138 | +This subcommand is read-only: it never creates or initializes a config file. |
| 139 | +If `--config <path>` is set, it prints that path verbatim. |
| 140 | +Otherwise it prints the already-loaded config path, the first existing config in the search order, or the path where a config would be created on first run. |
| 141 | + |
| 142 | +### `update` |
| 143 | + |
| 144 | +Check for and apply updates to the `lstk` CLI itself. |
| 145 | +`lstk` auto-detects how it was installed (Homebrew, npm, or direct binary) and updates using that same method. |
| 146 | +Development builds (version `dev`) are skipped, and updates are checked against the latest [GitHub release](https://github.com/localstack/lstk/releases/latest). |
| 147 | + |
| 148 | +```bash |
| 149 | +lstk update [options] |
| 150 | +``` |
| 151 | + |
| 152 | +| Option | Description | |
| 153 | +|:--------------------|:---------------------------------------------------------------| |
| 154 | +| `--check` | Check for updates without installing them | |
| 155 | +| `--non-interactive` | Use plain output instead of the TUI (update logic unchanged) | |
| 156 | +| `--json` | Emit the result as a JSON envelope (see [Structured output](#structured-output)). With `--check`, `data` reports `currentVersion`/`latestVersion`/`updateAvailable`; after an applied update, `updatedVersion`/`updated`/`method`. | |
| 157 | + |
| 158 | +Examples: |
| 159 | + |
| 160 | +```bash |
| 161 | +# Check for updates without installing |
| 162 | +lstk update --check |
| 163 | + |
| 164 | +# Update to the latest version |
| 165 | +lstk update |
| 166 | + |
| 167 | +# Update with plain (non-TUI) output |
| 168 | +lstk update --non-interactive |
| 169 | +``` |
| 170 | + |
| 171 | +By install method: |
| 172 | + |
| 173 | +- **Homebrew** (binary under a `Caskroom` path): runs `brew upgrade localstack/tap/lstk`. |
| 174 | +- **npm** (binary under `node_modules`): runs `npm install -g @localstack/lstk@latest`. |
| 175 | +- **Binary** (anything else): downloads the release asset for your OS/arch from GitHub, extracts it, and replaces the running executable in place. |
| 176 | + |
| 177 | +With `--check`, `lstk` only reports whether a newer version is available and exits without downloading or installing anything. |
| 178 | + |
| 179 | +:::note |
| 180 | +Set `LSTK_GITHUB_TOKEN` to send an authenticated GitHub request and avoid API rate limits during update checks. |
| 181 | +It is optional; updates also work unauthenticated. |
| 182 | +::: |
| 183 | + |
| 184 | +#### Update notification on start |
| 185 | + |
| 186 | +Separately from `lstk update`, `lstk` checks for a newer version when you run `lstk start` (the default command), using a short timeout that fails silently if GitHub is unreachable. |
| 187 | + |
| 188 | +In an interactive terminal, when an update is available `lstk` prints the new version and a release-notes link, then prompts: |
| 189 | + |
| 190 | +```text |
| 191 | +Update lstk to latest version? |
| 192 | +> Update now [U] |
| 193 | + Remind me next time [R] |
| 194 | + Skip this version [S] |
| 195 | +``` |
| 196 | + |
| 197 | +- **Update now [U]**: downloads and applies the update, then asks you to re-run your command. |
| 198 | +- **Remind me next time [R]**: does nothing; you are reminded on the next run. |
| 199 | +- **Skip this version [S]**: records the version in `config.toml` so you are not prompted about it again. |
| 200 | + |
| 201 | +In non-interactive mode the notification is not a prompt — `lstk` emits a single note (`Update available: <current> → <latest> (run lstk update)`) and continues. |
| 202 | + |
| 203 | +When you choose **Skip this version**, `lstk` writes the skipped version under a `[cli]` table: |
| 204 | + |
| 205 | +```toml |
| 206 | +[cli] |
| 207 | +update_skipped_version = "0.5.0" |
| 208 | +``` |
| 209 | + |
| 210 | +While this value matches the latest available version, the start-time update notification for that version is suppressed. |
| 211 | +This key is managed automatically and is not intended to be edited by hand. |
| 212 | + |
| 213 | +### `completion` |
| 214 | + |
| 215 | +Generate shell completion scripts. |
| 216 | + |
| 217 | +```bash |
| 218 | +lstk completion [bash|zsh|fish|powershell] |
| 219 | +``` |
| 220 | + |
| 221 | +See [Shell completions](#shell-completions) for setup instructions. |
0 commit comments