--- title: "Lighthouse CLI: Run Lighthouse from the Command Line" description: "Install the lighthouse npm package, run audits from your terminal, save JSON, HTML, or CSV reports, and choose between the Lighthouse CLI, LHCI, and Unlighthouse." canonical_url: "https://unlighthouse.dev/learn-lighthouse/lighthouse-cli" last_updated: "2026-11-05" --- > Index of every page on this site: [llms.txt](https://unlighthouse.dev/llms.txt) The Lighthouse CLI is the `lighthouse` [npm](https://npmjs.com) package from Google. It runs one Lighthouse audit per URL in a local Chrome and writes an HTML, JSON, or CSV report. ```bash 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](https://nodejs.org) 22.19 or later and a Chrome or Chromium install. Run it once with `npx`, or install it globally: ```bash 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: ```bash 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. ```bash # 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](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse) 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 | Flag | What it does | | --------------------------------- | ------------------------------------------------------------------------------------------- | | `--output=json` | Report format: `html` (default), `json`, or `csv`. Repeat the flag for more than one format | | `--output-path=./report.html` | File or directory for the report. Use `stdout` to print it | | `--view` | Open the HTML report in your browser | | `--only-categories` | Run only the named categories | | `--only-audits` / `--skip-audits` | Run or skip single audits by ID. `--list-all-audits` prints the IDs | | `--preset=desktop` | Desktop screen, user agent, and throttling settings | | `--throttling-method` | `simulate` (default), `devtools`, or `provided` (no throttling) | | `--chrome-flags` | Flags passed to Chrome, for example `"--headless=new"` | | `--extra-headers` | JSON string or JSON file of request headers, for example a cookie | | `--blocked-url-patterns` | Block requests that match a pattern, such as a third-party script | | `--config-path` | Load a custom Lighthouse config file | | `--url-file` | Audit each URL in a newline-delimited file | | `--save-assets` | Save the trace and DevTools log next to the report | Read [the Lighthouse throttling docs](https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md) 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: ```bash 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`: ```bash 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](https://unlighthouse.dev/tools/lighthouse-report-viewer). ## Audit a list of URLs Put one URL per line in a file, and pass a directory as the output path: ```bash 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. ```bash 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. | | Lighthouse CLI | [Lighthouse CI (LHCI)](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) | [Unlighthouse](https://unlighthouse.dev/integrations/cli) | | ------------ | -------------------------- | ------------------------------------------------------- | --------------------------------------- | | Package | `lighthouse` | `@lhci/cli` | `unlighthouse` | | URLs | One URL, or a file of URLs | URLs you list in `lighthouserc` | Finds pages from your sitemap and links | | Repeat runs | One run per URL | `numberOfRuns` per URL | `--samples` per page | | Fail a build | No threshold flag | Assertions and budgets | `unlighthouse-ci --budget` | | Results | HTML, JSON, or CSV files | Upload to storage or an LHCI server | Site-wide report UI and exports | Use the Lighthouse CLI to debug one page or to get the raw JSON report. Use [LHCI](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) 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](https://unlighthouse.dev/learn-lighthouse/lhci-vs-unlighthouse) guide compares the last two. ## Sources - [Lighthouse on GitHub: Using the Node CLI](https://github.com/GoogleChrome/lighthouse#using-the-node-cli) - [lighthouse on npm](https://www.npmjs.com/package/lighthouse) - [Lighthouse throttling docs](https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md) - [Lighthouse CI on GitHub](https://github.com/GoogleChrome/lighthouse-ci) ## Sitemap See the full [sitemap](https://unlighthouse.dev/sitemap.md) for all pages.