0
# Command Line Interface
1

2
Command-line utility providing full access to wait-on functionality through CLI arguments and configuration files. Supports time interval parsing and environment-specific options.
3

4
## Capabilities
5

6
### Basic Command Structure
7

8
```bash { .api }
9
wait-on [options] resource1 [resource2 ...]
10
```
11

12
The CLI waits for all specified resources to become available, then exits with code 0 (success) or non-zero (error/timeout).
13

14
**Usage Examples:**
15

16
```bash
17
# Wait for single file
18
wait-on file1
19

20
# Wait for multiple resources
21
wait-on file1 file2 http://localhost:8000
22

23
# Chain with another command
24
wait-on http://localhost:3000 && npm start
25

26
# Wait for service shutdown in reverse mode
27
wait-on -r tcp:8080 && echo "Service stopped"
28
```
29

30
### Command Line Options
31

32
#### Configuration Options
33

34
```bash { .api }
35
# Configuration file (JavaScript or JSON)
36
-c, --config <file>
37

38
# Example usage
39
wait-on --config ./wait-config.js
40
```
41

42
Configuration file format:
43
```javascript
44
module.exports = {
45
  resources: ['http://localhost:3000'],
46
  timeout: 30000,
47
  interval: 1000,
48
  log: true,
49
  // Any other options from the Node.js API
50
};
51
```
52

53
#### Timing Options
54

55
```bash { .api }
56
# Initial delay before checking resources (ms)
57
-d, --delay <ms>
58

59
# Poll interval (supports time units: ms, s, m, h)
60
-i, --interval <time>
61

62
# Overall timeout (supports time units)
63
-t, --timeout <time>
64

65
# Stability window (supports time units), default 750ms
66
# Time that resource needs to have not changed before signaling success
67
# If less than interval, it will be reset to the value of interval
68
# This is only used for files, other resources are considered available on first detection
69
-w, --window <time>
70

71
# HTTP request timeout (ms), default 0 (uses OS default)
72
--httpTimeout <ms>
73

74
# TCP connection timeout (ms), default 300ms
75
--tcpTimeout <ms>
76
```
77

78
**Usage Examples:**
79

80
```bash
81
# Wait 5 seconds before starting, check every 2 seconds
82
wait-on -d 5000 -i 2s http://localhost:3000
83

84
# 30 second timeout with custom intervals
85
wait-on -t 30s -i 500ms tcp:3306
86

87
# File stability window
88
wait-on -w 2s file:/tmp/output.log
89
```
90

91
#### Behavior Options
92

93
```bash { .api }
94
# Enable logging to stdout
95
-l, --log
96

97
# Enable verbose/debug logging
98
-v, --verbose  
99

100
# Reverse mode - wait for resources to become unavailable
101
-r, --reverse
102

103
# Limit concurrent connections
104
-s, --simultaneous <count>
105

106
# Show help
107
-h, --help
108
```
109

110
**Usage Examples:**
111

112
```bash
113
# Verbose logging
114
wait-on -v http://localhost:3000
115

116
# Reverse mode with logging
117
wait-on -r -l tcp:8080
118

119
# Limit to 3 concurrent connections
120
wait-on -s 3 http://api1.com http://api2.com http://api3.com
121
```
122

123
### Time Interval Parsing
124

125
The CLI supports human-readable time intervals for timing options:
126

127
```bash { .api }
128
# Time unit suffixes
129
ms    # milliseconds (default)
130
s     # seconds  
131
m     # minutes
132
h     # hours
133

134
# Examples
135
--timeout 30s      # 30 seconds
136
--interval 2m      # 2 minutes  
137
--delay 500ms      # 500 milliseconds
138
--window 1h        # 1 hour
139
```
140

141
**Usage Examples:**
142

143
```bash
144
# Various time formats
145
wait-on --timeout 5m --interval 10s http://localhost:3000
146
wait-on --delay 30s --window 2m file:/tmp/data.json
147
wait-on -t 1h -i 30s tcp:database:5432
148
```
149

150
### Resource Specification
151

152
Resources can be specified directly as command arguments or in configuration files:
153

154
```bash
155
# Command line resources (take precedence over config file)
156
wait-on resource1 resource2 resource3
157

158
# Resources from config file only
159
wait-on --config myconfig.js
160
```
161

162
### Exit Codes
163

164
```bash { .api }
165
0    # Success - all resources became available
166
1    # Error - timeout, resource unavailable, or other error
167
```
168

169
**Usage Examples:**
170

171
```bash
172
# Use in shell scripts
173
if wait-on -t 30s http://localhost:3000; then
174
  echo "Server is ready"
175
  npm start
176
else
177
  echo "Server failed to start" >&2
178
  exit 1
179
fi
180

181
# Chain commands
182
wait-on tcp:5432 && wait-on http://localhost:8080 && echo "All services ready"
183
```
184

185
### Configuration File Support
186

187
Configuration files provide access to all Node.js API options:
188

189
```javascript
190
// wait-config.js
191
module.exports = {
192
  resources: [
193
    'http://localhost:3000',
194
    'tcp:database:5432'
195
  ],
196
  timeout: 30000,
197
  interval: 1000,
198
  log: true,
199
  
200
  // HTTP-specific options not available via CLI flags
201
  auth: {
202
    username: process.env.API_USER,
203
    password: process.env.API_PASS
204
  },
205
  headers: {
206
    'User-Agent': 'MyApp/1.0'
207
  },
208
  validateStatus: (status) => status < 500
209
};
210
```
211

212
Usage:
213
```bash
214
wait-on --config wait-config.js
215
```
216

217
### Help Output
218

219
```bash { .api }
220
wait-on --help
221
```
222

223
Displays comprehensive usage information including:
224
- Command syntax
225
- All available options  
226
- Resource type descriptions
227
- Time interval format
228
- Exit code information
229
- Configuration file examples
230

231
**Usage Examples:**
232

233
```bash
234
# Complete examples for different scenarios
235

236
# Web application startup
237
wait-on tcp:3306 tcp:6379 && wait-on http://localhost:3000/health && echo "App ready"
238

239
# Microservices orchestration  
240
wait-on http://auth:8080/health http://api:8080/health http://ui:3000 && echo "All services online"
241

242
# File processing pipeline
243
wait-on file:/input/data.csv && process-data && wait-on file:/output/results.json
244

245
# Development workflow
246
wait-on http://localhost:3000 && npm run test:e2e
247

248
# Docker container coordination
249
wait-on tcp:postgres:5432 && wait-on tcp:redis:6379 && npm start
250
```