0
# CLI Commands
1

2
LocalStack provides a comprehensive command-line interface for managing the LocalStack runtime, configuration, services, and package management. All commands are accessed through the main `localstack` CLI entry point.
3

4
## Capabilities
5

6
### Lifecycle Management
7

8
Core commands for starting, stopping, and managing the LocalStack runtime.
9

10
```python { .api }
11
def main() -> None:
12
    """
13
    Main CLI entry point. Sets LOCALSTACK_CLI=1 environment variable
14
    and processes --profile argument before configuration loading.
15
    
16
    Location: localstack.cli.main.main()
17
    Entry point: /bin/localstack
18
    """
19
```
20

21
#### Start Command
22

23
Start LocalStack runtime with extensive configuration options.
24

25
```bash { .api }
26
localstack start [OPTIONS]
27

28
# Core options:
29
--docker                    # Start in Docker container (default)
30
--host                     # Start directly on host system
31
--no-banner               # Disable LocalStack startup banner
32
-d, --detached            # Start in background mode
33

34
# Docker configuration:
35
--network NETWORK         # Use custom Docker network
36
-e, --env KEY=VALUE       # Set environment variables
37
-p, --publish PORT        # Port mappings (host:container)
38
-v, --volume PATH         # Volume mounts (host:container)
39
--host-dns               # Expose DNS server to host system
40

41
# Stack selection:
42
-s, --stack STACK        # Use specific stack (e.g., localstack:4.5, snowflake)
43
```
44

45
Usage examples:
46

47
```bash
48
# Basic start in Docker
49
localstack start
50

51
# Start with custom environment and ports  
52
localstack start -e DEBUG=1 -e SERVICES=s3,lambda -p 4566:4566
53

54
# Start with custom network and volumes
55
localstack start --network my-network -v /tmp/localstack:/var/lib/localstack
56

57
# Start in detached mode with specific stack
58
localstack start -d -s localstack:4.5
59
```
60

61
#### Stop Command
62

63
Stop the LocalStack runtime.
64

65
```bash { .api }
66
localstack stop
67

68
# Stops container named by MAIN_CONTAINER_NAME (default: localstack-main)
69
```
70

71
#### Restart Command
72

73
Restart LocalStack runtime within the container without stopping the container itself.
74

75
```bash { .api }
76
localstack restart
77
```
78

79
#### Logs Command
80

81
Display and follow LocalStack logs.
82

83
```bash { .api }
84
localstack logs [OPTIONS]
85

86
-f, --follow             # Follow log output (like tail -f)
87
-n, --tail N            # Show last N lines of logs
88
```
89

90
Usage examples:
91

92
```bash
93
# Show recent logs
94
localstack logs -n 100
95

96
# Follow logs in real-time
97
localstack logs -f
98
```
99

100
#### Wait Command
101

102
Wait for LocalStack to be ready and healthy.
103

104
```bash { .api }
105
localstack wait [OPTIONS]
106

107
-t, --timeout N         # Timeout in seconds (default: 60)
108
```
109

110
#### SSH Command
111

112
Get an interactive shell inside the LocalStack container.
113

114
```bash { .api }
115
localstack ssh
116

117
# Opens shell in running LocalStack container for debugging
118
```
119

120
### Status Commands
121

122
Commands for checking LocalStack and service status.
123

124
#### Status Command
125

126
Query LocalStack operational status.
127

128
```bash { .api }
129
localstack status [SUBCOMMAND]
130

131
# Defaults to 'docker' subcommand if no subcommand specified
132
```
133

134
#### Docker Status
135

136
Check Docker container and runtime status.
137

138
```bash { .api }
139
localstack status docker [OPTIONS]
140

141
-f, --format FORMAT     # Output format (table, plain, dict, json)
142
```
143

144
#### Services Status  
145

146
Check health status of individual AWS services.
147

148
```bash { .api }
149
localstack status services [OPTIONS]
150

151
-f, --format FORMAT     # Output format (table, plain, dict, json)
152
```
153

154
Response format example:
155

156
```json
157
{
158
  "services": {
159
    "s3": "running",
160
    "lambda": "running", 
161
    "dynamodb": "available",
162
    "sqs": "starting"
163
  }
164
}
165
```
166

167
### Configuration Commands
168

169
Commands for viewing and validating LocalStack configuration.
170

171
#### Show Configuration
172

173
Display current LocalStack configuration with multiple output formats.
174

175
```bash { .api }
176
localstack config show [OPTIONS]
177

178
-f, --format FORMAT     # Output format: table, plain, dict, json
179
```
180

181
Output includes all environment variables, computed paths, and service settings.
182

183
#### Validate Configuration  
184

185
Validate docker-compose configuration files.
186

187
```bash { .api }
188
localstack config validate [OPTIONS]
189

190
-f, --file FILE         # Path to compose file (default: docker-compose.yml)
191
```
192

193
### Update Commands
194

195
Commands for updating LocalStack components and images.
196

197
#### Update All
198

199
Update both CLI and Docker images to latest versions.
200

201
```bash { .api }
202
localstack update all
203
```
204

205
#### Update CLI
206

207
Update LocalStack CLI package via pip.
208

209
```bash { .api }
210
localstack update localstack-cli
211

212
# Equivalent to: pip install --upgrade localstack-core
213
```
214

215
#### Update Docker Images
216

217
Pull latest LocalStack Docker images.
218

219
```bash { .api }
220
localstack update docker-images
221

222
# Updates: localstack/localstack, localstack/localstack-pro, etc.
223
```
224

225
### Package Management (LPM)
226

227
LocalStack Package Manager for installing additional components and services.
228

229
#### List Packages
230

231
List available packages in the LocalStack package repository.
232

233
```bash { .api }
234
localstack lpm list [OPTIONS]
235

236
-v, --verbose           # Show detailed package information and versions
237
```
238

239
#### Install Packages
240

241
Install one or more packages with configuration options.
242

243
```bash { .api }
244
localstack lpm install PACKAGE [PACKAGE...] [OPTIONS]
245

246
--parallel N           # Number of parallel installers (default: 1)
247
--version VERSION      # Install specific package version  
248
--target TARGET        # Installation target directory
249
```
250

251
Usage examples:
252

253
```bash
254
# Install single package
255
localstack lpm install dynamodb-local
256

257
# Install multiple packages in parallel
258
localstack lpm install --parallel 3 opensearch elasticsearch redis
259

260
# Install specific version
261
localstack lpm install --version 2.0.1 kinesis-mock
262
```
263

264
### Advanced Commands
265

266
Additional utility and integration commands.
267

268
#### Shell Completion
269

270
Generate shell completion scripts for bash, zsh, and fish.
271

272
```bash { .api }
273
localstack completion SHELL
274

275
# Supported shells: bash, zsh, fish
276
```
277

278
Setup examples:
279

280
```bash
281
# Bash completion
282
localstack completion bash > ~/.localstack-completion.bash
283
echo 'source ~/.localstack-completion.bash' >> ~/.bashrc
284

285
# Zsh completion  
286
localstack completion zsh > ~/.localstack-completion.zsh
287
echo 'source ~/.localstack-completion.zsh' >> ~/.zshrc
288

289
# Fish completion
290
localstack completion fish > ~/.config/fish/completions/localstack.fish
291
```
292

293
### Plugin Commands
294

295
Dynamic command loading via the plugin system.
296

297
```python { .api }
298
class LocalstackCliPlugin:
299
    """
300
    Base class for CLI plugins that can add custom commands.
301
    
302
    Namespace: localstack.plugins.cli
303
    """
304
    namespace: str = "localstack.plugins.cli"
305
    
306
    def attach(self, cli) -> None:
307
        """
308
        Attach custom commands to the LocalStack CLI.
309
        
310
        Args:
311
            cli: LocalStack CLI instance
312
        """
313

314
def load_cli_plugins(cli) -> None:
315
    """
316
    Discover and load all CLI plugins from the namespace.
317
    Called automatically during CLI initialization.
318
    """
319
```
320

321
Plugin commands are automatically discovered and loaded from the `localstack.plugins.cli` namespace, allowing extensions to add custom functionality to the CLI.
322

323
## Environment Variables
324

325
Key environment variables that affect CLI behavior:
326

327
```python { .api }
328
# CLI behavior
329
LOCALSTACK_CLI = "1"           # Set automatically when using CLI
330
CONFIG_PROFILE = "profile"     # Active configuration profile
331

332
# Container management  
333
MAIN_CONTAINER_NAME = "localstack-main"  # Default container name
334
MAIN_DOCKER_NETWORK = "bridge"           # Docker network for container
335

336
# Debugging and logging
337
DEBUG = "1"                    # Enable debug mode
338
LS_LOG = "info"               # Logging level (trace, debug, info, warn, error)
339
```
340

341
## Exit Codes
342

343
Standard exit codes returned by CLI commands:
344

345
- `0` - Success
346
- `1` - General error (configuration, runtime error)  
347
- `2` - Command line usage error
348
- `3` - Service startup failure
349
- `130` - Interrupted by user (Ctrl+C)
350

351
## Configuration Files
352

353
CLI respects configuration from multiple sources in order of precedence:
354

355
1. Command line arguments
356
2. Environment variables  
357
3. Profile files (`~/.localstack/profiles/<profile_name>`)
358
4. Default configuration (`~/.localstack/config`)
359

360
Profile loading is handled automatically when `--profile` argument is provided and occurs before general configuration loading.