Using the CLI

Run Lighthouse from the command line with full control over configuration, output formats, and the audit lifecycle.

The Lighthouse CLI gives you the most flexibility for configuring runs, automating audits, and integrating Lighthouse into CI pipelines.

Installation

npm install -g lighthouse
# or with yarn:
yarn global add lighthouse

Lighthouse requires Node 22 (LTS) or later.

Run your first audit:

lighthouse https://example.com

By default, Lighthouse writes an HTML report to a file in the current directory named after the URL and date.

Common flags

Output flags

Control where and how Lighthouse writes its results.

Flag	Type	Default	Description
--output	array	html	Reporter format(s). Choices: json, html, csv. Accepts multiple values.
--output-path	string	—	File path for the report. Use stdout to write to standard output. With multiple outputs, the path is used as a base and the appropriate extension is appended.
--view	boolean	false	Open the HTML report in your browser after the run.

Configuration flags

Control which audits run and how the browser behaves.

Flag	Type	Default	Description
--preset	string	—	Use a built-in configuration. Choices: perf, experimental, desktop. Ignored if --config-path is also provided.
--config-path	string	—	Path to a custom config file (JS or JSON).
--only-categories	array	—	Run only the specified categories: accessibility, best-practices, performance, seo.
--only-audits	array	—	Run only the specified audit IDs.
--skip-audits	array	—	Run everything except the specified audit IDs.
--locale	string	—	Locale for the report output (e.g. en, fr, ja).
--plugins	array	—	Additional Lighthouse plugins to run.
--save-assets	boolean	false	Save trace and DevTools log files to disk alongside the report.

Throttling flags

Flag	Type	Default	Description
--throttling-method	string	simulate	Throttling strategy. Choices: devtools, provided, simulate.
--throttling.rttMs	number	—	Simulated network round-trip time (TCP layer).
--throttling.throughputKbps	number	—	Simulated network download throughput.
--throttling.cpuSlowdownMultiplier	number	—	CPU slowdown multiplier for simulated and emulated throttling.
--form-factor	string	—	mobile or desktop. Use --preset=desktop for a full desktop run.
--screenEmulation.disabled	boolean	—	Disable screen emulation entirely.
--screenEmulation.width	number	—	Emulated screen width in pixels.
--screenEmulation.height	number	—	Emulated screen height in pixels.

Chrome flags

Flag	Type	Default	Description
--chrome-flags	string	""	Space-delimited flags passed directly to Chrome (e.g. "--headless --no-sandbox").
--port	number	0	DevTools Protocol port. 0 picks a random available port.
--hostname	string	localhost	DevTools Protocol hostname.

Output format examples

HTML (default)

lighthouse https://example.com
# saves ./<HOST>_<DATE>.report.html

lighthouse https://example.com --output json
# JSON output written to stdout

lighthouse https://example.com --output html --output-path ./report.html
# saves ./report.html

lighthouse https://example.com --output json --output html
# saves ./<HOST>_<DATE>.report.json and ./<HOST>_<DATE>.report.html

lighthouse https://example.com --output json --output html --output-path ./myfile.json
# saves ./myfile.report.json and ./myfile.report.html
# NOTE: the specified extension is ignored for ALL formats when using multiple outputs

lighthouse https://example.com --output-path=~/mydir/foo.out --save-assets
# saves ~/mydir/foo.report.html
# saves ~/mydir/foo-0.trace.json and ~/mydir/foo-0.devtoolslog.json

Gather mode and audit mode

Lighthouse’s run can be split into two separate phases: gather and audit. This is useful for auditing the same artifacts multiple times, or for separating the browser interaction step from analysis.

# -G: launch browser, collect artifacts, save to ./latest-run/, then quit
lighthouse https://example.com -G

# -A: skip browser, load artifacts from ./latest-run/, run audits, generate report
lighthouse https://example.com -A

# -GA: normal run, but also save artifacts to disk for later -A runs
lighthouse https://example.com -GA

# Provide a custom artifacts folder
lighthouse https://gmail.com -GA=./gmailartifacts

Use -GA during development to iterate on audits without re-running the browser each time. Save artifacts once with -GA, then re-audit them with -A as you tweak configuration.

More examples

# Run only performance and SEO categories
lighthouse https://example.com --only-categories=performance,seo

# Use the desktop preset
lighthouse https://example.com --preset=desktop

# Run headless Chrome with no logging
lighthouse https://example.com --quiet --chrome-flags="--headless"

# Disable device emulation and throttling (as measured on your machine)
lighthouse https://example.com --screenEmulation.disabled --throttling-method=provided --no-emulatedUserAgent

# Pass custom HTTP headers
lighthouse https://example.com --extra-headers "{\"Cookie\":\"monster=blue\"}"

# Use a custom config file
lighthouse https://example.com --config-path=./myconfig.js

# Open HTML report in browser after run
lighthouse https://example.com --view

Error reporting

The first time you run the CLI, Lighthouse asks whether it can anonymously report runtime exceptions. The Lighthouse team uses this data to detect regressions. Opting out has no effect on functionality.

You can force the preference at the command line:

# Enable error reporting
lighthouse https://example.com --enable-error-reporting

# Disable error reporting
lighthouse https://example.com --no-enable-error-reporting