0
# CLI Interface
1

2
Command-line interface for running st as a standalone HTTP server with extensive configuration options and built-in help system.
3

4
## Capabilities
5

6
### Command Line Usage
7

8
The st CLI provides a full-featured HTTP server for serving static files.
9

10
```bash { .api }
11
st [options]
12

13
# Basic usage examples:
14
st                           # Serve current directory on port 1337
15
st -p 8080                   # Serve on port 8080
16
st -d ./public               # Serve ./public directory
17
st -d ./static -u /assets    # Serve ./static at /assets URL
18
```
19

20
**Usage Examples:**
21

22
```bash
23
# Basic server
24
st
25

26
# Custom port and directory
27
st -p 3000 -d ./website
28

29
# Development server with CORS
30
st -p 8080 -d ./dist --cors
31

32
# Production-like server
33
st -p 80 -d /var/www/html --no-dot -a 3600000
34

35
# Local development with custom URL mount
36
st -d ./build -u /app -p 3000 --localhost
37
```
38

39
### Port Configuration
40

41
Configure the HTTP server port.
42

43
```bash { .api }
44
-p, --port PORT     # Listen on PORT (default: 1337)
45
```
46

47
**Usage Examples:**
48

49
```bash
50
# Default port (1337)
51
st
52

53
# Custom port
54
st -p 8080
55
st --port 3000
56

57
# Use environment variable (PORT=8080 st)
58
PORT=8080 st
59
```
60

61
### Host Configuration
62

63
Configure the server bind address.
64

65
```bash { .api }
66
-H, --host HOST     # Bind address HOST (default: * - all interfaces)
67
-l, --localhost     # Same as "--host localhost"
68
```
69

70
**Usage Examples:**
71

72
```bash
73
# Bind to all interfaces (default)
74
st
75

76
# Bind to specific IP
77
st -H 192.168.1.100
78

79
# Bind to localhost only (secure for development)  
80
st -l
81
st --localhost
82

83
# Bind to specific hostname
84
st --host example.local
85
```
86

87
### Directory and URL Configuration
88

89
Configure which directory to serve and URL mount point.
90

91
```bash { .api }
92
-d, --dir DIRECTORY    # Serve the contents of DIRECTORY (default: current working directory)
93
-u, --url /url         # Serve at this mount url (default: /)
94
```
95

96
**Usage Examples:**
97

98
```bash
99
# Serve current directory (default)
100
st
101

102
# Serve specific directory
103
st -d ./public
104
st --dir /var/www/html
105

106
# Serve with URL mount point
107
st -d ./static -u /static
108
st --dir ./assets --url /assets
109

110
# Complex example: serve ./build at /app
111
st -d ./build -u /app -p 3000
112
```
113

114
### Directory Indexing
115

116
Configure directory listing and index file behavior.
117

118
```bash { .api }
119
-i, --index [INDEX]    # Use the specified INDEX filename as the result when a directory 
120
                       # is requested. Set to "true" to turn autoindexing on, or "false" 
121
                       # to turn it off. If no INDEX is provided, then it will turn 
122
                       # autoindexing on. (default: true)
123
-ni, --no-index        # Same as "--index false"
124
```
125

126
**Usage Examples:**
127

128
```bash
129
# Auto-indexing enabled (default)
130
st
131

132
# Use specific index file
133
st -i index.html
134
st --index home.htm
135

136
# Enable auto-indexing explicitly
137
st -i true
138
st --index
139

140
# Disable directory access
141
st -ni
142
st --no-index
143
st --index false
144
```
145

146
### Dot File Access
147

148
Configure access to dot files (hidden files starting with .).
149

150
```bash { .api }
151
-., --dot [DOT]       # Allow .files to be served. Set to "false" to disable.
152
-n., --no-dot         # Same as "--dot false"
153
```
154

155
**Usage Examples:**
156

157
```bash
158
# Block dot files (default)
159
st
160

161
# Allow dot files
162
st -.
163
st --dot
164
st --dot true
165

166
# Explicitly block dot files
167
st -n.
168
st --no-dot
169
st --dot false
170
```
171

172
### CORS Configuration
173

174
Configure Cross-Origin Resource Sharing headers.
175

176
```bash { .api }
177
-co, --cors           # Enable CORS to serve files to any domain
178
```
179

180
**Usage Examples:**
181

182
```bash
183
# No CORS headers (default)
184
st
185

186
# Enable CORS
187
st --cors
188
st -co
189

190
# CORS with other options
191
st -d ./api-docs --cors -p 8080
192
```
193

194
### Cache Configuration
195

196
Configure caching behavior and cache expiration.
197

198
```bash { .api }
199
-nc, --no-cache       # Turn off all caching
200
-a, --age AGE         # Max age (in ms) of cache entries
201
```
202

203
**Usage Examples:**
204

205
```bash
206
# Default caching enabled
207
st
208

209
# Disable all caching
210
st --no-cache
211
st -nc
212

213
# Custom cache age (1 hour = 3600000ms)
214
st -a 3600000
215
st --age 1800000  # 30 minutes
216

217
# Development with no caching
218
st -d ./src --no-cache --cors
219

220
# Production with long cache
221
st -d ./build -a 86400000  # 24 hours
222
```
223

224
### Help and Information
225

226
Display help information and command usage.
227

228
```bash { .api }
229
-h, --help            # Show help information
230
```
231

232
**Usage Examples:**
233

234
```bash
235
# Show help
236
st -h
237
st --help
238

239
# Help output includes:
240
# - Command description
241
# - All available options
242
# - Default values
243
# - Usage examples
244
```
245

246
### Complete Examples
247

248
Real-world usage scenarios combining multiple options.
249

250
**Development Server:**
251

252
```bash
253
# Local development with live reloading-friendly settings
254
st -d ./src -p 3000 --localhost --no-cache --cors
255
```
256

257
**Production Server:**
258

259
```bash
260
# Production server with security and performance optimizations
261
st -d /var/www/html -p 80 --no-dot -a 3600000 -ni
262
```
263

264
**Static Site Hosting:**
265

266
```bash
267
# Host static site with proper indexing
268
st -d ./dist -p 8080 -i index.html
269
```
270

271
**API Documentation Server:**
272

273
```bash
274
# Serve API docs with CORS for external access
275
st -d ./api-docs -p 4000 --cors -i index.html
276
```
277

278
**Asset Server:**
279

280
```bash
281
# Dedicated asset server with long cache times
282
st -d ./assets -u /assets -p 9000 -a 31536000000  # 1 year cache
283
```
284

285
**Secure Local Server:**
286

287
```bash
288
# Secure server for sensitive files
289
st -d ./private --localhost -p 8443 --no-dot --no-index
290
```
291

292
### Environment Variables
293

294
The CLI respects certain environment variables.
295

296
```bash { .api }
297
PORT=1337             # Default port if -p/--port not specified
298
```
299

300
**Usage Examples:**
301

302
```bash
303
# Set default port via environment
304
export PORT=8080
305
st  # Will use port 8080
306

307
# Override environment with flag
308
PORT=8080 st -p 3000  # Will use port 3000
309

310
# Use in Docker/deployment scenarios
311
docker run -e PORT=80 -p 80:80 my-app
312

313
# Temporary environment variable
314
PORT=9000 st -d ./build
315
```
316

317
### Server Information
318

319
The CLI displays connection information when the server starts.
320

321
```bash { .api }
322
# Server startup message format:
323
listening at http://HOST:PORT
324

325
# Examples:
326
listening at http://localhost:1337
327
listening at http://192.168.1.100:8080
328
listening at http://[::1]:3000  # IPv6
329
```
330

331
### Error Handling
332

333
The CLI handles various error conditions with appropriate exit codes and messages.
334

335
**Common Errors:**
336

337
- Invalid port number
338
- Invalid age value
339
- Directory not found
340
- Permission denied
341
- Port already in use
342

343
**Usage Examples:**
344

345
```bash
346
# Invalid port
347
st -p abc
348
# Error: invalid port: abc
349

350
# Invalid age  
351
st -a xyz
352
# Error: invalid age: "xyz"
353

354
# Non-existent directory
355
st -d /nonexistent
356
# Server will fail to start with filesystem error
357
```