|
1 | 1 | # lstk |
2 | 2 |
|
3 | | -lstk is a command-line interface for LocalStack built in Go with a modern terminal UI, and native CLI experience for managing and interacting LocalStack deployments. 👾 |
| 3 | +**A command-line interface for LocalStack**. Built with a modern terminal UI and native CLI experience for managing and interacting LocalStack deployments. 👾 |
4 | 4 |
|
5 | | -## Features |
6 | 5 |
|
7 | | -- **Start / stop** LocalStack emulators with a single command |
8 | | -- **Interactive TUI** — a Bubble Tea-powered terminal UI when run in an interactive shell |
9 | | -- **Plain output** for CI/CD and scripting (auto-detected in non-interactive environments) |
10 | | -- **Log streaming** — tail emulator logs in real-time with `--follow` |
11 | | -- **Browser-based login** — authenticate via browser and store credentials securely in the system keyring |
12 | | -- **Shell completions** — bash, zsh, and fish completions included |
| 6 | +```bash |
| 7 | +npm install -g @localstack/lstk |
| 8 | +``` |
| 9 | + |
| 10 | +See [installation](#installation) below. |
| 11 | + |
| 12 | +> [!IMPORTANT] |
| 13 | +> This project is under active development, currently using [ZeroVer](https://0ver.org/) (`0.MINOR.PATCH`). Expect breaking changes as we march toward a stable 1.0.0 release. |
| 14 | +
|
| 15 | + |
| 16 | +## Prerequisites |
| 17 | + |
| 18 | +- [Docker](https://docs.docker.com/get-docker/) — required as a container engine. |
| 19 | +- [LocalStack account](https://app.localstack.cloud) — required for credentials, the CLI will guide you through authentication. |
13 | 20 |
|
14 | 21 | ## Installation |
15 | 22 |
|
16 | | -### Homebrew (macOS / Linux) |
| 23 | +### 1. Homebrew (macOS / Linux) |
17 | 24 |
|
18 | 25 | ```bash |
19 | 26 | brew install localstack/tap/lstk |
20 | 27 | ``` |
21 | 28 |
|
22 | | -### NPM |
| 29 | +### 2. NPM |
23 | 30 |
|
24 | 31 | ```bash |
25 | 32 | npm install -g @localstack/lstk |
26 | | -lstk start |
27 | 33 | ``` |
28 | 34 |
|
29 | | -### Manual (binary download) |
| 35 | +Pre-built binaries are also available from [GitHub Releases](https://github.com/localstack/lstk/releases). 📦 |
| 36 | + |
| 37 | +## Quick Start |
| 38 | + |
| 39 | +```sh |
| 40 | +lstk |
| 41 | +``` |
| 42 | + |
| 43 | +Running `lstk` will automatically handle configuration setup and start LocalStack. |
| 44 | + |
| 45 | +## Features |
| 46 | + |
| 47 | +- **Start / stop** LocalStack emulators with a single command |
| 48 | +- **Interactive TUI** — a Bubble Tea-powered terminal UI when run in an interactive shell |
| 49 | +- **Plain output** for CI/CD and scripting (auto-detected in non-interactive environments) |
| 50 | +- **Log streaming** — tail emulator logs in real-time with `--follow` |
| 51 | +- **Browser-based login** — authenticate via browser and store credentials securely in the system keyring |
| 52 | +- **Shell completions** — bash, zsh, and fish completions included |
| 53 | + |
| 54 | +## Authentication |
| 55 | + |
| 56 | +The CLI supports multiple auth workflows. `lstk` resolves your auth token in this order: |
| 57 | + |
| 58 | +1. **System keyring** — a token stored by a previous `lstk login` |
| 59 | +2. **`LOCALSTACK_AUTH_TOKEN` environment variable** |
| 60 | +3. **Browser login** — triggered automatically in interactive mode when neither of the above is present |
| 61 | + |
| 62 | +> [!NOTE] |
| 63 | +> If a keyring token exists, it takes precedence over `LOCALSTACK_AUTH_TOKEN`. Setting or changing the environment variable will have no effect until the keyring token is removed. Run `lstk logout` to clear the stored keyring token, after which the env var will be used. |
| 64 | +
|
30 | 65 |
|
31 | | -Download the latest release for your platform from the [GitHub Releases](https://github.com/localstack/lstk/releases) page. Binaries are available for: |
| 66 | +## Configuration |
32 | 67 |
|
33 | | -- `linux/amd64`, `linux/arm64` |
34 | | -- `darwin/amd64`, `darwin/arm64` (macOS) |
35 | | -- `windows/amd64`, `windows/arm64` |
| 68 | +`lstk` uses a TOML config file, created automatically on first run. |
36 | 69 |
|
37 | | -## Requirements |
| 70 | +Config lookup order: |
| 71 | +1. `./lstk.toml` (project-local) |
| 72 | +2. `$HOME/.config/lstk/config.toml` |
| 73 | +3. `os.UserConfigDir()/lstk/config.toml` |
38 | 74 |
|
39 | | -- [Docker](https://docs.docker.com/get-docker/) must be running |
40 | | -- A [LocalStack Account](https://app.localstack.cloud) |
| 75 | +To see which config file is currently in use: |
41 | 76 |
|
| 77 | +```bash |
| 78 | +lstk config path |
| 79 | +``` |
42 | 80 |
|
43 | 81 | ## Usage |
44 | 82 |
|
@@ -68,36 +106,6 @@ lstk config path |
68 | 106 | lstk version |
69 | 107 | ``` |
70 | 108 |
|
71 | | -## Authentication |
72 | | - |
73 | | -`lstk` resolves your auth token in this order: |
74 | | - |
75 | | -1. **System keyring** — a token stored by a previous `lstk login` |
76 | | -2. **`LOCALSTACK_AUTH_TOKEN` environment variable** |
77 | | -3. **Browser login** — triggered automatically in interactive mode when neither of the above is present |
78 | | - |
79 | | -> **Note:** If a keyring token exists, it takes precedence over `LOCALSTACK_AUTH_TOKEN`. Setting or changing the environment variable will have no effect until the keyring token is removed. Run `lstk logout` to clear the stored keyring token, after which the env var will be used. |
80 | | -
|
81 | | -## Configuration |
82 | | - |
83 | | -`lstk` uses a TOML config file, created automatically on first run. |
84 | | - |
85 | | -Config lookup order: |
86 | | -1. `./lstk.toml` (project-local) |
87 | | -2. `$HOME/.config/lstk/config.toml` |
88 | | -3. `os.UserConfigDir()/lstk/config.toml` |
89 | | - |
90 | | -To see which config file is currently in use: |
91 | | - |
92 | | -```bash |
93 | | -lstk config path |
94 | | -``` |
95 | | - |
96 | | -## Versioning |
97 | | - |
98 | | -`lstk` uses [ZeroVer](https://0ver.org/) (`0.MINOR.PATCH`). The project is in active development and has not reached a stable 1.0 release. |
99 | | - |
100 | | - |
101 | 109 | ## Reporting bugs |
102 | | -Feedback is welcome! Use the repository issue tracker for bug reports or feature requests. |
103 | 110 |
|
| 111 | +Feedback is welcome! Use the repository issue tracker for bug reports or feature requests. |
0 commit comments