Skip to main content
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.
FlagTypeDefaultDescription
--outputarrayhtmlReporter format(s). Choices: json, html, csv. Accepts multiple values.
--output-pathstring—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.
--viewbooleanfalseOpen the HTML report in your browser after the run.

​
Configuration flags

Control which audits run and how the browser behaves.
FlagTypeDefaultDescription
--presetstring—Use a built-in configuration. Choices: perf, experimental, desktop. Ignored if --config-path is also provided.
--config-pathstring—Path to a custom config file (JS or JSON).
--only-categoriesarray—Run only the specified categories: accessibility, best-practices, performance, seo.
--only-auditsarray—Run only the specified audit IDs.
--skip-auditsarray—Run everything except the specified audit IDs.
--localestring—Locale for the report output (e.g. en, fr, ja).
--pluginsarray—Additional Lighthouse plugins to run.
--save-assetsbooleanfalseSave trace and DevTools log files to disk alongside the report.

​
Throttling flags

FlagTypeDefaultDescription
--throttling-methodstringsimulateThrottling strategy. Choices: devtools, provided, simulate.
--throttling.rttMsnumber—Simulated network round-trip time (TCP layer).
--throttling.throughputKbpsnumber—Simulated network download throughput.
--throttling.cpuSlowdownMultipliernumber—CPU slowdown multiplier for simulated and emulated throttling.
--form-factorstring—mobile or desktop. Use --preset=desktop for a full desktop run.
--screenEmulation.disabledboolean—Disable screen emulation entirely.
--screenEmulation.widthnumber—Emulated screen width in pixels.
--screenEmulation.heightnumber—Emulated screen height in pixels.

​
Chrome flags

FlagTypeDefaultDescription
--chrome-flagsstring""Space-delimited flags passed directly to Chrome (e.g. "--headless --no-sandbox").
--portnumber0DevTools Protocol port. 0 picks a random available port.
--hostnamestringlocalhostDevTools Protocol hostname.

​
Output format examples

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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us