0
# Command-Line Interface
1

2
Command-line interface for running WireMock as a standalone service with comprehensive configuration options including server ports, SSL settings, proxy configuration, recording capabilities, and performance tuning.
3

4
## Capabilities
5

6
### WireMockServerRunner Class
7

8
Main server runner class providing lifecycle management for standalone WireMock instances.
9

10
```java { .api }
11
/**
12
 * Main server runner for standalone WireMock instances
13
 */
14
class WireMockServerRunner {
15
    /** Default constructor */
16
    WireMockServerRunner();
17
    
18
    /** Start WireMock server with command-line arguments */
19
    void run(String... args);
20
    
21
    /** Stop the running server */
22
    void stop();
23
    
24
    /** Check if server is currently running */
25
    boolean isRunning();
26
    
27
    /** Get the port number server is listening on */
28
    int port();
29
}
30
```
31

32
**Usage Examples:**
33

34
```java
35
// Programmatic server control
36
WireMockServerRunner runner = new WireMockServerRunner();
37
runner.run("--port", "8080", "--https-port", "8443");
38

39
// Server is now running
40
assertTrue(runner.isRunning());
41
assertEquals(8080, runner.port());
42

43
// Stop when done
44
runner.stop();
45
assertFalse(runner.isRunning());
46
```
47

48
### Run Class (Main Entry Point)
49

50
Main class for standalone JAR execution extending WireMockServerRunner.
51

52
```java { .api }
53
/**
54
 * Main entry point for standalone JAR execution
55
 */
56
class Run extends WireMockServerRunner {
57
    /** Main method for command-line execution */
58
    static void main(String... args);
59
}
60
```
61

62
**Usage Examples:**
63

64
```bash
65
# Basic server startup
66
java -jar wiremock-standalone-3.13.1.jar
67

68
# Server with specific port
69
java -jar wiremock-standalone-3.13.1.jar --port 8089
70

71
# Server with HTTPS
72
java -jar wiremock-standalone-3.13.1.jar --port 8080 --https-port 8443
73
```
74

75
### CommandLineOptions Class
76

77
Comprehensive command-line options parser implementing the full Options interface.
78

79
```java { .api }
80
/**
81
 * Command-line options parser and configuration manager
82
 */
83
class CommandLineOptions implements Options {
84
    /** Parse command-line arguments into configuration */
85
    CommandLineOptions(String... args);
86
    
87
    // Help and Version
88
    /** Check if help was requested */
89
    boolean help();
90
    
91
    /** Check if version info was requested */
92
    boolean version();
93
    
94
    /** Get formatted help text */
95
    String helpText();
96
    
97
    // Logging and Output
98
    /** Check if verbose logging is enabled */
99
    boolean verboseLoggingEnabled();
100
    
101
    /** Check if startup banner is disabled */
102
    boolean bannerDisabled();
103
    
104
    // Recording and Proxy
105
    /** Check if mapping recording is enabled */
106
    boolean recordMappingsEnabled();
107
    
108
    /** Check if proxy URL was specified */
109
    boolean specifiesProxyUrl();
110
    
111
    /** Get configured proxy URL */
112
    String proxyUrl();
113
    
114
    // Port Configuration (Runtime)
115
    /** Set actual HTTP port after server startup */
116
    void setActualHttpPort(int port);
117
    
118
    /** Set actual HTTPS port after server startup */
119
    void setActualHttpsPort(int port);
120
    
121
    // Inherits all Options interface methods (70+ configuration options)
122
}
123
```
124

125
### Command-Line Arguments Reference
126

127
Complete reference for all supported command-line arguments.
128

129
#### Server Configuration
130

131
```bash
132
# Port Configuration
133
--port <port>                    # HTTP port (default: 8080)
134
--https-port <port>             # HTTPS port
135
--bind-address <address>        # Bind address (default: 0.0.0.0)
136
--container-threads <count>     # Container thread pool size
137
--jetty-acceptor-threads <count> # Jetty acceptor threads
138
--jetty-accept-queue-size <size> # Jetty accept queue size
139
--jetty-header-buffer-size <size> # HTTP header buffer size
140
--async-response-enabled        # Enable asynchronous responses
141
--async-response-threads <count> # Async response thread pool size
142

143
# Protocol Configuration  
144
--disable-http                  # Disable HTTP protocol
145
--require-https                 # Require HTTPS for admin API
146
```
147

148
#### HTTPS and SSL Configuration
149

150
```bash
151
# Keystore Configuration
152
--https-keystore <path>         # Keystore file path
153
--keystore-password <password>  # Keystore password
154
--keystore-type <type>         # Keystore type (JKS, PKCS12)
155
--key-manager-password <password> # Key manager password
156

157
# Truststore Configuration
158
--https-truststore <path>       # Truststore file path
159
--truststore-password <password> # Truststore password
160
--truststore-type <type>        # Truststore type
161

162
# Client Authentication
163
--https-require-client-cert     # Require client certificates
164
```
165

166
#### Proxy Configuration
167

168
```bash
169
# Basic Proxy Settings
170
--proxy-all <url>               # Proxy all unmatched requests to URL
171
--proxy-via <host:port>         # Proxy via intermediate proxy
172
--preserve-host-header          # Preserve original host header
173
--proxy-pass-through           # Enable proxy pass-through mode
174

175
# Proxy Security
176
--trust-all-proxy-targets      # Trust all proxy target hosts
177
--trusted-proxy-targets <hosts> # Comma-separated trusted hosts
178
--ca-keystore <path>           # CA keystore for proxy SSL
179
--ca-keystore-password <pwd>   # CA keystore password
180
--ca-keystore-type <type>      # CA keystore type
181
```
182

183
#### File and Storage Configuration
184

185
```bash
186
# Directory Configuration
187
--root-dir <path>              # Root directory for files
188
--mappings-dir <path>          # Directory for stub mappings
189
--files-dir <path>             # Directory for response files
190

191
# File Behavior
192
--no-request-journal           # Disable request journaling
193
--max-request-journal-entries <count> # Limit journal entries
194
--record-mappings              # Record proxy mappings to files
195
--match-headers <headers>      # Headers to record for matching
196
```
197

198
#### Extension and Advanced Configuration
199

200
```bash
201
# Extensions
202
--extensions <class1,class2>   # Load extension classes
203
--extension-scan-enabled       # Enable classpath extension scanning
204

205
# Template Configuration
206
--global-response-templating   # Enable global response templating
207
--local-response-templating    # Enable per-stub templating
208
--max-template-cache-entries <count> # Template cache size
209

210
# Performance and Behavior
211
--disable-gzip                 # Disable gzip compression
212
--disable-request-logging      # Disable request logging
213
--enable-stub-cors            # Enable CORS for stub responses
214
--disable-optimize-xml-factories # Disable XML factory optimization
215
--disable-strict-http-headers  # Disable strict HTTP header validation
216
```
217

218
#### Recording and Monitoring
219

220
```bash
221
# Recording Configuration
222
--record-mappings              # Enable mapping recording
223
--match-headers <headers>      # Headers to include in recorded mappings
224
--proxy-all <target-url>       # Record from existing API
225

226
# Monitoring and Debugging
227
--verbose                      # Enable verbose logging
228
--print-all-network-traffic   # Log all network traffic
229
--no-banner                   # Disable startup banner
230
```
231

232
#### Authentication and Security
233

234
```bash
235
# Admin API Authentication
236
--admin-api-username <user>    # Admin API username
237
--admin-api-password <pass>    # Admin API password
238
--admin-api-require-https     # Require HTTPS for admin API
239
```
240

241
### Command-Line Usage Examples
242

243
```bash
244
# Basic standalone server
245
java -jar wiremock-standalone-3.13.1.jar --port 8080
246

247
# HTTPS-enabled server with custom keystore
248
java -jar wiremock-standalone-3.13.1.jar \
249
  --port 8080 \
250
  --https-port 8443 \
251
  --https-keystore /path/to/keystore.jks \
252
  --keystore-password secret123 \
253
  --keystore-type JKS
254

255
# Proxy mode with recording
256
java -jar wiremock-standalone-3.13.1.jar \
257
  --port 8080 \
258
  --proxy-all https://api.example.com \
259
  --record-mappings \
260
  --match-headers Accept,Content-Type,Authorization
261

262
# High-performance configuration
263
java -jar wiremock-standalone-3.13.1.jar \
264
  --port 8080 \
265
  --container-threads 50 \
266
  --jetty-acceptor-threads 4 \
267
  --jetty-accept-queue-size 500 \
268
  --async-response-enabled \
269
  --async-response-threads 10
270

271
# Custom file locations
272
java -jar wiremock-standalone-3.13.1.jar \
273
  --port 8080 \
274
  --root-dir /opt/wiremock \
275
  --mappings-dir /opt/wiremock/mappings \
276
  --files-dir /opt/wiremock/__files
277

278
# Security-focused setup
279
java -jar wiremock-standalone-3.13.1.jar \
280
  --port 8080 \
281
  --https-port 8443 \
282
  --require-https \
283
  --admin-api-username admin \
284
  --admin-api-password secret \
285
  --https-require-client-cert \
286
  --https-keystore server.jks \
287
  --keystore-password serverpass \
288
  --https-truststore truststore.jks \
289
  --truststore-password trustpass
290

291
# Development mode with extensions
292
java -jar wiremock-standalone-3.13.1.jar \
293
  --port 8080 \
294
  --verbose \
295
  --global-response-templating \
296
  --extensions com.example.CustomTransformer \
297
  --extension-scan-enabled \
298
  --print-all-network-traffic
299

300
# Proxy with custom settings
301
java -jar wiremock-standalone-3.13.1.jar \
302
  --port 8080 \
303
  --proxy-all https://backend.example.com \
304
  --proxy-via proxy.company.com:3128 \
305
  --preserve-host-header \
306
  --trusted-proxy-targets backend.example.com,api.example.com \
307
  --ca-keystore ca-certs.jks \
308
  --ca-keystore-password capass
309

310
# Help and version information
311
java -jar wiremock-standalone-3.13.1.jar --help
312
java -jar wiremock-standalone-3.13.1.jar --version
313
```
314

315
### Configuration File Support
316

317
While primarily command-line focused, WireMock supports configuration through:
318

319
```bash
320
# Environment variables (example)
321
WIREMOCK_PORT=8080
322
WIREMOCK_HTTPS_PORT=8443
323
java -jar wiremock-standalone-3.13.1.jar
324

325
# System properties
326
java -Dwiremock.port=8080 -Dwiremock.https-port=8443 \
327
  -jar wiremock-standalone-3.13.1.jar
328

329
# Property files and JSON configuration (when using file-based mappings)
330
# Mappings directory structure:
331
# /mappings/
332
#   ├── mapping1.json
333
#   ├── mapping2.json
334
# /__files/
335
#   ├── response1.json
336
#   ├── response2.xml
337
```
338

339
### Integration with Process Management
340

341
```bash
342
# Systemd service example
343
[Unit]
344
Description=WireMock API Mock Server
345
After=network.target
346

347
[Service]
348
Type=simple
349
User=wiremock
350
WorkingDirectory=/opt/wiremock
351
ExecStart=/usr/bin/java -jar /opt/wiremock/wiremock-standalone-3.13.1.jar \
352
  --port 8080 \
353
  --https-port 8443 \
354
  --root-dir /opt/wiremock/data
355
Restart=always
356
RestartSec=10
357

358
[Install]
359
WantedBy=multi-user.target
360

361
# Docker usage
362
docker run -it --rm \
363
  -p 8080:8080 \
364
  -p 8443:8443 \
365
  -v $PWD/mappings:/home/wiremock/mappings \
366
  -v $PWD/__files:/home/wiremock/__files \
367
  wiremock/wiremock:3.13.1 \
368
  --port 8080 \
369
  --https-port 8443 \
370
  --global-response-templating
371
```
372

373
### Exit Codes and Error Handling
374

375
```bash
376
# Exit codes
377
# 0 - Success
378
# 1 - General error (invalid arguments, startup failure)
379
# 2 - Invalid arguments or configuration
380
# 130 - Interrupted (Ctrl+C)
381

382
# Error scenarios
383
java -jar wiremock-standalone-3.13.1.jar --invalid-option
384
# Returns exit code 2 with error message
385

386
java -jar wiremock-standalone-3.13.1.jar --port 80
387
# May return exit code 1 if port binding fails (requires root)
388
```