0
# Command Line Interface
1
2
The reload CLI provides a standalone development server with automatic browser refresh capabilities. It serves static files, watches for changes, and automatically injects reload functionality into HTML pages without requiring code modifications.
3
4
## Capabilities
5
6
### Basic Server Command
7
8
Start a development server with reload functionality.
9
10
```bash { .api }
11
reload [options]
12
```
13
14
**Usage Examples:**
15
16
```bash
17
# Basic usage - serves current directory on port 8080
18
reload
19
20
# Serve specific directory
21
reload -d ./public
22
23
# Custom port
24
reload -p 3000
25
26
# Open browser automatically
27
reload -b
28
```
29
30
### Browser Integration
31
32
Automatically open the application in the default browser.
33
34
```bash { .api }
35
-b, --browser
36
```
37
38
**Usage Examples:**
39
40
```bash
41
# Open browser automatically
42
reload -b
43
44
# Open browser with custom hostname
45
reload -b -n myapp.local
46
47
# Open browser with specific port
48
reload -b -p 3000
49
```
50
51
### Hostname Configuration
52
53
Configure the hostname for browser opening and server binding.
54
55
```bash { .api }
56
-n, --hostname [hostname]
57
```
58
59
**Default:** localhost
60
**Usage:** Customize the hostname used when opening the browser automatically.
61
62
**Usage Examples:**
63
64
```bash
65
# Use custom hostname
66
reload -b -n myapp.local
67
68
# Use IP address
69
reload -b -n 192.168.1.100
70
```
71
72
### Directory Serving
73
74
Configure which directory to serve as the web root.
75
76
```bash { .api }
77
-d, --dir [dir]
78
```
79
80
**Default:** Current working directory
81
**Usage:** Specify the directory containing your HTML, CSS, and JavaScript files.
82
83
**Usage Examples:**
84
85
```bash
86
# Serve public directory
87
reload -d ./public
88
89
# Serve build output
90
reload -d ./dist
91
92
# Serve nested directory
93
reload -d ./src/web
94
```
95
96
### File Watching
97
98
Configure which directory to monitor for file changes.
99
100
```bash { .api }
101
-w, --watch-dir [watch-dir]
102
```
103
104
**Default:** Same as serving directory
105
**Usage:** Watch a different directory than the one being served (useful for compiled assets).
106
107
**Usage Examples:**
108
109
```bash
110
# Watch source directory while serving build directory
111
reload -d ./dist -w ./src
112
113
# Watch multiple levels
114
reload -w ./src/scss
115
```
116
117
### File Extensions
118
119
Configure which file types trigger server restart and browser reload.
120
121
```bash { .api }
122
-e, --exts [extensions]
123
```
124
125
**Default:** html,js,css
126
**Format:** Comma-separated or pipe-separated list
127
**Usage:** Specify which file extensions should be monitored for changes.
128
129
**Usage Examples:**
130
131
```bash
132
# Watch additional file types
133
reload -e "html,js,css,json,md"
134
135
# Watch only specific types
136
reload -e "html,css"
137
138
# Use pipe separator
139
reload -e "html|js|css|ts"
140
```
141
142
### Port Configuration
143
144
Configure the server port.
145
146
```bash { .api }
147
-p, --port [port]
148
```
149
150
**Default:** 8080
151
**Environment Variable:** Can also be set via PORT environment variable
152
**Usage:** Set the port for the HTTP server.
153
154
**Usage Examples:**
155
156
```bash
157
# Custom port
158
reload -p 3000
159
160
# Use environment variable
161
PORT=4000 reload
162
163
# High port number
164
reload -p 8888
165
```
166
167
### Start Page
168
169
Configure the default page to serve and open in the browser.
170
171
```bash { .api }
172
-s, --start-page [start-page]
173
```
174
175
**Default:** index.html
176
**Usage:** Specify the filename to use as the default page.
177
178
**Usage Examples:**
179
180
```bash
181
# Use different start page
182
reload -s main.html
183
184
# Use nested start page
185
reload -s pages/home.html
186
```
187
188
### Fallback Routing
189
190
Enable fallback to the start page for single-page applications.
191
192
```bash { .api }
193
-f, --fallback [fallback]
194
```
195
196
**Default:** false
197
**Usage:** Enable fallback routing for SPAs where all routes should serve the start page.
198
199
**Usage Examples:**
200
201
```bash
202
# Enable fallback routing
203
reload -f
204
205
# Combine with custom start page
206
reload -f -s app.html
207
```
208
209
### Verbose Logging
210
211
Enable detailed logging for debugging.
212
213
```bash { .api }
214
-v, --verbose [verbose]
215
```
216
217
**Default:** false
218
**Usage:** Enable verbose logging on both server and client sides.
219
220
**Usage Examples:**
221
222
```bash
223
# Enable verbose logging
224
reload -v
225
226
# Combine with other options
227
reload -v -b -p 3000
228
```
229
230
### Version Information
231
232
Display the current version of reload.
233
234
```bash { .api }
235
-V, --version
236
```
237
238
**Usage Example:**
239
240
```bash
241
reload --version
242
```
243
244
### Help Information
245
246
Display usage information and available options.
247
248
```bash { .api }
249
-h, --help
250
```
251
252
**Usage Example:**
253
254
```bash
255
reload --help
256
```
257
258
## Complete Usage Examples
259
260
### Basic Static Site Development
261
262
```bash
263
# Serve current directory with browser auto-open
264
reload -b
265
266
# Serve specific directory with custom port
267
reload -b -d ./public -p 3000
268
269
# Watch source files while serving build output
270
reload -b -d ./dist -w ./src -e "html,js,css,scss"
271
```
272
273
### Single Page Application Development
274
275
```bash
276
# Enable fallback routing for SPA
277
reload -b -f -s index.html
278
279
# SPA with custom configuration
280
reload -b -f -s app.html -p 4000 -d ./build
281
```
282
283
### Advanced Development Setup
284
285
```bash
286
# Comprehensive development server
287
reload -b -v -d ./public -w ./src -e "html,js,css,json,md" -p 3000 -n localhost
288
```
289
290
## Server Behavior
291
292
### Static File Serving
293
294
The CLI server provides static file serving with the following features:
295
296
- **Index files**: Automatically serves `index.html` and `index.htm` from directories
297
- **MIME types**: Proper Content-Type headers for common file types
298
- **File extensions**: Automatic `.html` extension resolution for extensionless URLs
299
- **Fallback routing**: Optional SPA-style fallback to start page
300
301
### HTML Injection
302
303
The server automatically injects the reload client script into HTML files:
304
305
```html
306
<!-- Automatically injected by reload -->
307
<script src="/reload/reload.js"></script>
308
<!-- End Reload -->
309
```
310
311
This injection happens for:
312
- `.html` files
313
- Root path requests (`/`)
314
- Extensionless URLs that resolve to `.html` files
315
- Fallback routing responses
316
317
### File Watching
318
319
File watching is handled by the `supervisor` package with the following behavior:
320
321
- **Change detection**: Monitors specified file extensions in the watch directory
322
- **Server restart**: Automatically restarts the server when files change
323
- **Client notification**: WebSocket connection closure triggers browser reload
324
- **Recursive watching**: Watches all subdirectories of the specified watch directory
325
326
### WebSocket Integration
327
328
The CLI server uses the same WebSocket system as the Express integration:
329
330
- **Port**: Uses the same port as the HTTP server
331
- **Protocol**: WebSocket communication for reload signaling
332
- **Reconnection**: Automatic client reconnection after server restart
333
- **Browser compatibility**: Requires WebSocket support in the browser
334
335
## Process Management
336
337
The CLI server is managed by the `supervisor` package:
338
339
```bash
340
# The CLI internally runs something equivalent to:
341
supervisor -e "html,js,css" -w ./src -q -- reload-server.js [args...]
342
```
343
344
This provides:
345
- **Automatic restart**: Server restarts when watched files change
346
- **Quiet mode**: Reduces supervisor output noise
347
- **Extension filtering**: Only watches specified file extensions
348
- **Directory watching**: Monitors specified directories recursively