CLI reference

Complete reference for all Lighthouse CLI flags, options, and usage examples.

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