0
# Command Line Interface
1

2
The Lighthouse CLI provides a comprehensive command-line tool for automated testing, CI/CD integration, and performance monitoring. It offers extensive configuration options and multiple output formats for different use cases.
3

4
## Basic Usage
5

6
### Command Structure
7

8
```bash { .api }
9
lighthouse <url> [options]
10

11
# Examples
12
lighthouse https://example.com
13
lighthouse https://example.com --output=json
14
lighthouse https://example.com --config-path=./custom-config.js
15
```
16

17
### Core Options
18

19
Essential options for basic Lighthouse usage.
20

21
```bash { .api }
22
# Output options
23
--output <format>              # Output format: json, html, csv (default: html)
24
--output-path <path>           # Output file path (without extension)
25
--view                         # Open report in browser after completion
26
--save-assets                  # Save trace and devtools log files
27

28
# Configuration options
29
--config-path <path>           # Path to custom configuration file
30
--preset <preset>              # Quick config preset: perf, desktop, experimental
31
--locale <locale>              # Report locale (default: en-US)
32
--additional-trace-categories <cats> # Additional trace categories (comma-separated)
33

34
# Basic examples
35
lighthouse https://example.com --output=json --output-path=./report
36
lighthouse https://example.com --preset=desktop --view
37
lighthouse https://example.com --config-path=./config.js
38
```
39

40
**Usage Examples:**
41

42
```bash
43
# Generate HTML report (default)
44
lighthouse https://example.com
45

46
# Generate JSON report
47
lighthouse https://example.com --output=json --output-path=./results/audit
48

49
# Generate multiple formats
50
lighthouse https://example.com --output=html --output=json --output-path=./report
51

52
# Use desktop preset
53
lighthouse https://example.com --preset=desktop
54

55
# Open report automatically
56
lighthouse https://example.com --view
57
```
58

59
## Runtime Configuration
60

61
### Chrome Options
62

63
Control Chrome browser behavior and connection settings.
64

65
```bash { .api }
66
# Chrome connection
67
--chrome-flags <flags>         # Chrome command-line flags (space-separated)
68
--port <port>                  # Chrome debugging port (default: 0)
69
--hostname <hostname>          # Chrome debugging hostname (default: 127.0.0.1)
70
--chrome-ignore-default-flags  # Don't use default Chrome flags
71

72
# Chrome behavior  
73
--disable-storage-reset        # Skip clearing storage before run
74
--disable-full-page-screenshot # Disable full page screenshots
75
--enable-error-reporting       # Enable error reporting to Google
76

77
# Examples
78
lighthouse https://example.com --chrome-flags="--headless --no-sandbox"
79
lighthouse https://example.com --port=9223 --hostname=127.0.0.1
80
lighthouse https://example.com --disable-storage-reset
81
```
82

83
### Timeout and Timing Options
84

85
Control navigation timeouts and timing behavior.
86

87
```bash { .api }
88
# Timeout options
89
--max-wait-for-load <ms>       # Max wait for page load (default: 45000)
90

91
# Examples
92
lighthouse https://example.com --max-wait-for-load=60000
93
```
94

95
## Performance Testing Options
96

97
### Throttling Configuration
98

99
Control network and CPU throttling for consistent performance testing.
100

101
```bash { .api }
102
# Throttling method
103
--throttling-method <method>   # Throttling method: provided, devtools, simulate (default: simulate)
104

105
# Network throttling
106
--throttling.rttMs <ms>        # Network round-trip time (default varies by method)
107
--throttling.throughputKbps <kbps>  # Network throughput (default varies)
108
--throttling.requestLatencyMs <ms>  # Request latency
109
--throttling.downloadThroughputKbps <kbps>  # Download throughput
110
--throttling.uploadThroughputKbps <kbps>    # Upload throughput
111

112
# CPU throttling
113
--throttling.cpuSlowdownMultiplier <n>  # CPU slowdown multiplier (default varies)
114

115
# Examples
116
lighthouse https://example.com --throttling-method=devtools
117
lighthouse https://example.com --throttling.rttMs=150 --throttling.throughputKbps=1638
118
lighthouse https://example.com --throttling.cpuSlowdownMultiplier=4
119
```
120

121
**Throttling Presets:**
122

123
```bash
124
# Simulate slow 4G (default)
125
lighthouse https://example.com --throttling-method=simulate
126

127
# Use actual network conditions
128
lighthouse https://example.com --throttling-method=provided
129

130
# Use Chrome DevTools throttling
131
lighthouse https://example.com --throttling-method=devtools
132
```
133

134
### Device Emulation
135

136
Control device emulation and screen settings.
137

138
```bash { .api }
139
# Screen emulation  
140
--screenEmulation.mobile <boolean>      # Enable mobile emulation (default: true)
141
--screenEmulation.width <pixels>        # Screen width (default: 375)
142
--screenEmulation.height <pixels>       # Screen height (default: 667)
143
--screenEmulation.deviceScaleFactor <n> # Device scale factor (default: 2)
144
--screenEmulation.disabled             # Disable screen emulation entirely
145

146
# User agent
147
--emulatedUserAgent <string>           # Custom user agent string
148

149
# Examples  
150
lighthouse https://example.com --screenEmulation.mobile=false --screenEmulation.width=1920
151
lighthouse https://example.com --emulatedUserAgent="Custom Bot 1.0"
152
```
153

154
## Audit Filtering and Selection
155

156
### Category and Audit Filtering
157

158
Control which audits and categories to run.
159

160
```bash { .api }
161
# Category filtering
162
--only-categories <categories>    # Run only specified categories (comma-separated)
163
--skip-categories <categories>    # Skip specified categories (comma-separated)
164

165
# Audit filtering  
166
--only-audits <audits>           # Run only specified audits (comma-separated)
167
--skip-audits <audits>           # Skip specified audits (comma-separated)
168

169
# Examples
170
lighthouse https://example.com --only-categories=performance,accessibility
171
lighthouse https://example.com --skip-audits=uses-http2,render-blocking-resources
172
lighthouse https://example.com --only-audits=first-contentful-paint,largest-contentful-paint
173
```
174

175
### Additional Options
176

177
Other useful CLI options for specialized use cases.
178

179
```bash { .api }
180
# Content and behavior
181
--form-factor <factor>         # mobile or desktop form factor
182
--emulatedUserAgent <ua>       # Custom user agent string  
183
--extra-headers <headers>      # Extra HTTP headers (JSON format)
184
--blocked-url-patterns <patterns> # Block URL patterns during testing
185
--ignore-status-code           # Ignore HTTP error status codes
186

187
# Plugin system
188
--plugins <plugins>            # Run specified plugins (comma-separated)
189

190
# Examples
191
lighthouse https://example.com --form-factor=desktop
192
lighthouse https://example.com --emulatedUserAgent="Custom Bot 1.0"
193
lighthouse https://example.com --extra-headers='{"Authorization":"Bearer token"}'
194
lighthouse https://example.com --blocked-url-patterns=".*\\.ads\\..*,.*analytics.*"
195
```
196

197
**Available Categories:**
198
- `performance` - Performance metrics and opportunities
199
- `accessibility` - Accessibility compliance and best practices
200
- `best-practices` - General web development best practices
201
- `seo` - Search Engine Optimization
202
- `pwa` - Progressive Web App features
203

204
**Common Audit IDs:**
205
```bash
206
# Performance audits
207
--only-audits=first-contentful-paint,largest-contentful-paint,cumulative-layout-shift,total-blocking-time,speed-index
208

209
# Accessibility audits
210
--only-audits=color-contrast,image-alt,label,link-name,meta-viewport
211

212
# Best practices audits
213
--only-audits=uses-https,is-on-https,uses-http2,no-vulnerable-libraries
214
```
215

216
## Advanced Features
217

218
### Gather and Audit Modes
219

220
Separate data gathering from auditing for advanced workflows.
221

222
```bash { .api }
223
# Gather mode - collect artifacts only
224
--gather-mode                  # Only gather artifacts, don't run audits
225
--audit-mode                   # Only run audits on existing artifacts
226

227
# Examples
228
# Step 1: Gather artifacts
229
lighthouse https://example.com --gather-mode
230

231
# Step 2: Run audits on gathered artifacts  
232
lighthouse --audit-mode
233
```
234

235
## Debugging and Logging
236

237
### Logging Options
238

239
Control logging verbosity and debugging output.
240

241
```bash { .api }
242
# Logging levels
243
--quiet                        # Suppress most output
244
--verbose                      # Detailed logging output
245

246
# Debug options
247
--list-all-audits             # List all available audits and exit
248
--list-trace-categories       # List trace categories and exit
249
--list-locales                # List all supported locales and exit
250
--debug-navigation            # Pause after page load for debugging
251
--save-assets                 # Save trace contents and devtools logs
252
--additional-trace-categories <cats> # Additional trace categories to collect
253

254
# Examples
255
lighthouse https://example.com --verbose
256
lighthouse https://example.com --quiet
257
lighthouse --list-all-audits
258
```
259

260
### Chrome Debugging
261

262
Advanced Chrome debugging and connection options.
263

264
```bash { .api }
265
# Chrome debugging
266
--chrome-ignore-default-flags  # Don't use default Chrome flags
267

268
# Manual Chrome connection
269
lighthouse https://example.com --port=9222  # Connect to existing Chrome instance
270
```
271

272
## CI/CD Integration Patterns
273

274
### Basic CI/CD Usage
275

276
```bash
277
# Simple performance check
278
lighthouse https://staging.example.com \
279
  --output=json \
280
  --output-path=./lighthouse-report \
281
  --chrome-flags="--headless --no-sandbox" \
282
  --quiet
283

284
# Check exit code for failures
285
echo "Exit code: $?"
286
```
287

288
### Advanced CI/CD Configuration
289

290
```bash
291
#!/bin/bash
292
# ci-lighthouse.sh
293

294
URL="https://staging.example.com"
295
OUTPUT_DIR="./lighthouse-reports"
296
CONFIG_PATH="./lighthouse-ci-config.js"
297

298
# Ensure clean environment
299
mkdir -p "$OUTPUT_DIR"
300

301
# Run Lighthouse with CI-optimized settings
302
lighthouse "$URL" \
303
  --config-path="$CONFIG_PATH" \
304
  --output=json \
305
  --output=html \
306
  --output-path="$OUTPUT_DIR/report" \
307
  --chrome-flags="--headless --no-sandbox --disable-gpu --disable-dev-shm-usage" \
308
  --max-wait-for-load=60000 \
309
  --throttling-method=simulate \
310
  --log-level=error \
311
  --quiet
312

313
# Check if report was generated successfully
314
if [ $? -eq 0 ]; then
315
  echo "✅ Lighthouse audit completed successfully"
316
  echo "📊 Reports saved to $OUTPUT_DIR/"
317
else
318
  echo "❌ Lighthouse audit failed"
319
  exit 1
320
fi
321
```
322

323
### Performance Threshold Checking
324

325
```bash
326
#!/bin/bash
327
# threshold-check.sh
328

329
REPORT_PATH="./lighthouse-report.json"
330
MIN_PERFORMANCE_SCORE=80
331

332
# Extract performance score from JSON report
333
PERFORMANCE_SCORE=$(cat "$REPORT_PATH" | jq -r '.categories.performance.score * 100 | floor')
334

335
echo "Performance Score: $PERFORMANCE_SCORE"
336

337
if [ "$PERFORMANCE_SCORE" -lt "$MIN_PERFORMANCE_SCORE" ]; then
338
  echo "❌ Performance score $PERFORMANCE_SCORE is below threshold $MIN_PERFORMANCE_SCORE"
339
  exit 1
340
else
341
  echo "✅ Performance score meets threshold"
342
fi
343
```
344

345
### Batch URL Testing
346

347
```bash
348
#!/bin/bash
349
# batch-audit.sh
350

351
URLS=(
352
  "https://example.com"
353
  "https://example.com/about"
354
  "https://example.com/contact"
355
  "https://example.com/products"
356
)
357

358
OUTPUT_DIR="./batch-reports"
359
mkdir -p "$OUTPUT_DIR"
360

361
for URL in "${URLS[@]}"; do
362
  echo "🔍 Auditing: $URL"
363
  
364
  # Clean URL for filename
365
  FILENAME=$(echo "$URL" | sed 's|https://||' | sed 's|/|_|g')
366
  
367
  lighthouse "$URL" \
368
    --output=json \
369
    --output=html \
370
    --output-path="$OUTPUT_DIR/$FILENAME" \
371
    --chrome-flags="--headless --no-sandbox" \
372
    --preset=desktop \
373
    --quiet
374
    
375
  if [ $? -eq 0 ]; then
376
    echo "✅ Completed: $URL"
377
  else
378
    echo "❌ Failed: $URL"
379
  fi
380
done
381

382
echo "📊 Batch audit completed. Reports in $OUTPUT_DIR/"
383
```
384

385
## Configuration File Examples
386

387
### Basic Configuration File
388

389
```javascript
390
// lighthouse.config.js
391
module.exports = {
392
  extends: 'lighthouse:default',
393
  settings: {
394
    onlyCategories: ['performance', 'accessibility'],
395
    throttling: {
396
      rttMs: 40,
397
      throughputKbps: 10240,
398
      cpuSlowdownMultiplier: 1,
399
    },
400
    screenEmulation: {
401
      mobile: false,
402
      width: 1920,
403
      height: 1080,
404
      deviceScaleFactor: 1,
405
    },
406
  },
407
};
408
```
409

410
### CI-Optimized Configuration
411

412
```javascript
413
// ci-config.js
414
module.exports = {
415
  extends: 'lighthouse:default',
416
  settings: {
417
    maxWaitForLoad: 60000,
418
    throttlingMethod: 'simulate',
419
    onlyCategories: ['performance'],
420
    budgets: [{
421
      path: '/*',
422
      timings: [
423
        {metric: 'first-contentful-paint', budget: 2000},
424
        {metric: 'largest-contentful-paint', budget: 4000},
425
      ],
426
      resourceSizes: [
427
        {resourceType: 'script', budget: 500000},
428
        {resourceType: 'image', budget: 1000000},
429
      ],
430
    }],
431
  },
432
};
433
```
434

435
## Error Handling and Troubleshooting
436

437
### Common Exit Codes
438

439
```bash
440
# Exit code meanings:
441
# 0 - Success
442
# 1 - General error
443
# 2 - Configuration error
444
# 3 - Runtime error
445
# 4 - Chrome connection error
446

447
# Check specific errors
448
lighthouse https://example.com || {
449
  case $? in
450
    1) echo "General Lighthouse error" ;;
451
    2) echo "Configuration error - check config file" ;;
452
    3) echo "Runtime error - check URL and Chrome" ;;
453
    4) echo "Chrome connection error - check Chrome setup" ;;
454
  esac
455
}
456
```
457

458
### Debugging Failed Runs
459

460
```bash
461
# Enable verbose logging for debugging
462
lighthouse https://example.com \
463
  --verbose
464

465
# Test Chrome connection
466
lighthouse https://example.com \
467
  --port=9222 \
468
  --chrome-flags="--remote-debugging-port=9222" \
469
  --verbose
470
```