The Lighthouse CLI is the most flexible way to run audits. It exposes all configuration options as command-line flags and supports multiple output formats.
Installation
npm install -g lighthouse
# or
yarn global add lighthouse
Basic usage
lighthouse <url> [options]
lighthouse https://example.com
# saves ./example.com_<date>.report.html by default
Logging flags
| Flag | Type | Default | Description |
|---|
--verbose | boolean | false | Displays verbose logging during the run. |
--quiet | boolean | false | Suppresses all progress, debug logs, and errors. |
Configuration flags
| Flag | Type | Default | Description |
|---|
--save-assets | boolean | false | Save the trace contents and devtools logs to disk alongside the report. |
--list-all-audits | boolean | false | Print a list of all available audits and exit. |
--list-trace-categories | boolean | false | Print a list of all required trace categories and exit. |
--additional-trace-categories | string | — | Additional Chrome trace categories to capture, comma-delimited. |
--config-path | string | — | Path to a custom config JS file. Overrides --preset when both are provided. |
--preset | string | — | Use a built-in configuration preset. Choices: perf, experimental, desktop. |
--chrome-flags | string | "" | Space-delimited flags to pass to Chrome on launch. Uses CHROME_PATH env var if set. |
--port | number | 0 | Debugging protocol port. Use 0 for a random port. |
--hostname | string | "localhost" | Hostname for the debugging protocol. |
--form-factor | string | — | Affects scoring and skips mobile-only audits when set to desktop. Choices: mobile, desktop. For desktop audits, prefer --preset=desktop. |
--screenEmulation | — | — | Sets screen emulation parameters. Use --screenEmulation.disabled to disable, or set individual sub-flags (see below). |
--screenEmulation.mobile | boolean | — | Emulate a mobile viewport. |
--screenEmulation.width | number | — | Emulated viewport width in pixels. |
--screenEmulation.height | number | — | Emulated viewport height in pixels. |
--screenEmulation.deviceScaleFactor | number | — | Emulated device scale factor. |
--screenEmulation.disabled | boolean | — | Disable all screen emulation. |
--emulatedUserAgent | string | — | Override the user agent string sent with requests. |
--max-wait-for-load | number | — | Milliseconds to wait before considering the page done loading. High values can cause instability. |
--enable-error-reporting | boolean | — | Enable anonymous error reporting. Use --no-enable-error-reporting to opt out. |
--gather-mode, -G | string/boolean | — | Collect and save artifacts to disk, then quit. Optionally provide a folder path. |
--audit-mode, -A | string/boolean | — | Load saved artifacts from disk and run audits only. Defaults to ./latest-run/. |
--only-audits | array | — | Run only the specified audit IDs. |
--only-categories | array | — | Run only the specified categories. Available: accessibility, best-practices, performance, seo. |
--skip-audits | array | — | Skip the specified audit IDs. |
--disable-full-page-screenshot | boolean | — | Skip full-page screenshot collection, which can be large. |
--gather-mode and --audit-mode can be combined as -GA to run the full audit while also saving artifacts to disk for later re-analysis.
Output flags
| Flag | Type | Default | Description |
|---|
--output | array | ["html"] | Output format(s). Choices: json, html, csv. Accepts multiple values. |
--output-path | string | — | File path for the report. Use stdout for console output. When multiple formats are specified, the standard extension is appended to the base path. |
--view | boolean | false | Open the HTML report in a browser after the run. |
Output path behavior
| Command | Output |
|---|
lighthouse <url> | <HOST>_<DATE>.report.html |
lighthouse <url> --output json | JSON sent to stdout |
lighthouse <url> --output html --output-path ./report.html | ./report.html |
lighthouse <url> --output json --output html --output-path ./myfile.json | ./myfile.report.json and ./myfile.report.html |
lighthouse <url> --output json --output html | <HOST>_<DATE>.report.json and <HOST>_<DATE>.report.html |
Other flags
| Flag | Type | Default | Description |
|---|
--version | boolean | — | Print the Lighthouse version and exit. |
--help | boolean | — | Show the help text and exit. |
--cli-flags-path | string | — | Path to a JSON file containing default CLI flags. Command-line flags take priority over file-based ones. |
--locale | string | — | Locale for the report output (e.g. en-US, fr). |
--blocked-url-patterns | array | — | Block network requests matching these URL patterns. |
--disable-storage-reset | boolean | — | Skip clearing the browser cache and storage APIs before the run. |
--throttling-method | string | — | Throttling implementation to use. Choices: devtools, provided, simulate. |
--throttling.rttMs | number | — | Simulated network RTT at the TCP layer (ms). |
--throttling.throughputKbps | number | — | Simulated network download throughput (Kbps). |
--throttling.requestLatencyMs | number | — | Emulated network RTT at the HTTP layer (ms). |
--throttling.downloadThroughputKbps | number | — | Emulated network download throughput (Kbps). |
--throttling.uploadThroughputKbps | number | — | Emulated network upload throughput (Kbps). |
--throttling.cpuSlowdownMultiplier | number | — | CPU slowdown multiplier for simulated and emulated throttling. |
--extra-headers | string | — | JSON string or path to a JSON file of additional HTTP headers to send with requests. |
--precomputed-lantern-data-path | string | — | Path to a file with precomputed Lantern simulation data, overriding observed estimates. |
--lantern-data-output-path | string | — | Path to write Lantern simulation data for reuse in future runs. |
--plugins | array | — | Names of Lighthouse plugins to run. |
--channel | string | "cli" | Identifies the run channel for internal tracking. |
--chrome-ignore-default-flags | boolean | false | Ignore Lighthouse’s default Chrome flags. |
Usage examples
# Open HTML report in a browser after the run
lighthouse https://example.com --view
# Run with a custom config file
lighthouse https://example.com --config-path=./myconfig.js
# Save trace and named JSON report
lighthouse https://example.com --output=json --output-path=./report.json --save-assets
# Disable device emulation and throttling
lighthouse https://example.com --screenEmulation.disabled --throttling-method=provided --no-emulatedUserAgent
# Launch Chrome with a specific window size
lighthouse https://example.com --chrome-flags="--window-size=412,660"
# Run headless with quiet logging
lighthouse https://example.com --quiet --chrome-flags="--headless"
# Send custom HTTP headers
lighthouse https://example.com --extra-headers "{\"Cookie\":\"session=abc\", \"x-api-key\":\"secret\"}"
# Load headers from a file
lighthouse https://example.com --extra-headers=./headers.json
# Run only performance and SEO categories
lighthouse https://example.com --only-categories=performance,seo
Lifecycle (gather/audit) mode
Separate the gather and audit phases to reuse collected artifacts or integrate with external tools.
# Gather artifacts only, save to ./latest-run/
lighthouse https://example.com -G
# Audit pre-collected artifacts from ./latest-run/
lighthouse https://example.com -A
# Gather and audit, also saving artifacts
lighthouse https://example.com -GA
# Use a custom folder for artifacts
lighthouse -GA=./my-artifacts https://example.com
When using -A (audit-only mode), Lighthouse skips the browser entirely and reads artifacts from disk. The URL argument is still required for report metadata but no network request is made.
Connecting to an existing Chrome instance
To audit a page that requires authentication or a specific browser state, launch Chrome manually with chrome-debug (installed globally alongside the CLI), log in, then point Lighthouse at the running instance.
# 1. Start a Chrome instance with an open debugging port
chrome-debug
# logs: "Debugging on port 9222"
# 2. In a separate terminal, run Lighthouse against the port
lighthouse https://mysite.com --port=9222
Real device testing
Disable emulation when auditing against a real connected Android device via ADB port forwarding.
adb forward tcp:9222 localabstract:chrome_devtools_remote
lighthouse https://example.com \
--port=9222 \
--screenEmulation.disabled \
--throttling.cpuSlowdownMultiplier=1 \
--throttling-method=provided
