CLI quickstart

Install Lighthouse globally and run your first audit from the command line.

The Lighthouse CLI gives you full control over audit configuration and output. Use it for one-off audits, automated scripts, or CI pipelines.

Lighthouse requires Node.js 22 (LTS) or later. Run node --version to check.

1. Install Lighthouse

   Install the lighthouse package globally using npm or Yarn.

   npm

   npm install -g lighthouse
   

   yarn global add lighthouse
   

   Verify the installation:

   lighthouse --version
   
2. Run your first audit

   Point Lighthouse at any URL. Chrome launches automatically, loads the page, collects data, and exits.

   lighthouse https://example.com
   

   By default, Lighthouse audits all four categories (Performance, Accessibility, SEO, Best Practices) using simulated mobile throttling.

   Add --view to automatically open the HTML report in your browser as soon as the audit finishes.
3. View the HTML report

   Unless you specify otherwise, Lighthouse saves an HTML report to a file in the current directory:

   example.com_<DATE>.report.html
   

   Open this file in any browser to see your scores, metric values, and actionable recommendations for every failing audit.

   You can also upload any .report.json file to the Lighthouse Viewer to view and share reports online.

4. Try JSON output

   Use the --output flag to change the report format. Lighthouse supports html, json, and csv.

   lighthouse https://example.com --output json
   

   JSON output goes to stdout by default. Redirect it to a file with --output-path:

   lighthouse https://example.com --output json --output-path ./report.json
   

   You can request multiple formats in a single run:

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

   Other output examples:

   # Save to a specific HTML file
   lighthouse https://example.com --output html --output-path ./report.html
   
   # Save named files for both formats
   lighthouse https://example.com --output json --output html --output-path ./myfile.json
   # saves ./myfile.report.json and ./myfile.report.html
   

Common flags

Flag	Description
--view	Open the HTML report in a browser after the run completes
--output	Report format: html, json, or csv (repeatable)
--output-path	File path for the report output
--only-categories	Comma-separated list of categories to audit
--preset	Use a built-in config: perf, desktop, or experimental
--quiet	Suppress progress and log output
--chrome-flags	Pass custom flags to the Chrome process

Use --only-categories=performance to skip Accessibility, SEO, and Best Practices audits. This significantly reduces run time when you only need performance metrics.

lighthouse https://example.com --only-categories=performance

Run lighthouse --help to see all available options.