Lighthouse CLI: Run Lighthouse from the Command Line

The Lighthouse CLI is the lighthouse npm package from Google. It runs one Lighthouse audit per URL in a local Chrome and writes an HTML, JSON, or CSV report.

npx lighthouse https://example.com --view

This guide uses Lighthouse 13.6.0, the current release on npm in November 2026. Check your version with lighthouse --version. Flags change between major versions, so lighthouse --help is the reference for your install.

Install

The package needs Node.js 22.19 or later and a Chrome or Chromium install. Run it once with npx, or install it globally:

npm install -g lighthouse
lighthouse --version

Lighthouse finds Chrome stable or Chrome Canary on its own. If you want a specific binary, set the CHROME_PATH environment variable:

CHROME_PATH=/usr/bin/chromium lighthouse https://example.com

Run an audit

With no flags, Lighthouse runs every category with mobile emulation and simulated throttling, then writes an HTML report to the working directory. The file name comes from the URL and the date.

# Open the HTML report when the run ends
lighthouse https://example.com --view

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

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

# Run headless with no progress logs
lighthouse https://example.com --quiet --chrome-flags="--headless=new"

Category IDs for --only-categories in Lighthouse 13 are performance, accessibility, best-practices, seo, and agentic-browsing.

The results are lab data from one run on your machine. Your CPU, network, and browser extensions change the Lighthouse Performance score between runs. PageSpeed Insights runs Lighthouse on Google's servers and can add Chrome UX Report (CrUX) field data, so its numbers differ from a local run.

Common flags

Read the Lighthouse throttling docs before you change --throttling-method. The three methods give different metric values for the same page.

Save JSON, HTML, and CSV reports

JSON goes to stdout by default. HTML and CSV go to a file. To write more than one format, repeat --output and give a base path:

lighthouse https://example.com \
  --output=json --output=html \
  --output-path=./reports/home

This writes reports/home.report.json and reports/home.report.html. The directory must already exist.

The JSON report holds every audit result. Read a category score with jq:

lighthouse https://example.com --output=json --quiet \
  --chrome-flags="--headless=new" \
  | jq '.categories.performance.score'

Category scores in the JSON are between 0 and 1. The HTML report shows them out of 100. To read a saved JSON report in the browser, open it in the Lighthouse Report Viewer.

Audit a list of URLs

Put one URL per line in a file, and pass a directory as the output path:

mkdir -p reports
lighthouse --url-file=urls.txt --output=json --output-path=./reports/

Lighthouse audits the URLs one after another and names each report from its URL and time. Add --fail-fast to stop at the first run that fails. You still write the URL list yourself.

Exit codes and CI

The CLI exits with a nonzero code when the run fails, for example when the page returns a 404 or Chrome cannot start. A low score does not fail the run. Lighthouse has no score threshold flag.

lighthouse https://example.com/missing --output=json
# Exit code 1. The report has runtimeError.code ERRORED_DOCUMENT_REQUEST

lighthouse https://example.com/missing --output=json --ignore-status-code
# Report written with a warning, exit code 0

To fail a CI build on a score or a resource budget, you need extra code that reads the JSON report, or a tool built for CI. Most CI runners need the headless flag. Container runners often also need --no-sandbox in --chrome-flags.

Lighthouse CLI, LHCI, and Unlighthouse

All three use Lighthouse. They differ in which URLs they test and what they do with the results.

Use the Lighthouse CLI to debug one page or to get the raw JSON report. Use LHCI to assert budgets on a fixed set of URLs in every build. Use Unlighthouse to scan every page of a site without a URL list. The LHCI vs Unlighthouse guide compares the last two.

Sources

• Lighthouse on GitHub: Using the Node CLI
• lighthouse on npm
• Lighthouse throttling docs
• Lighthouse CI on GitHub