> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/GoogleChrome/lighthouse/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Complete reference for all Lighthouse CLI flags, options, and usage examples. The Lighthouse CLI is the most flexible way to run audits. It exposes all configuration options as command-line flags and supports multiple output formats. ## Installation ```bash theme={null} npm install -g lighthouse # or yarn global add lighthouse ``` ## Basic usage ```bash theme={null} lighthouse [options] ``` ```bash theme={null} lighthouse https://example.com # saves ./example.com_.report.html by default ``` *** ## Logging flags | Flag | Type | Default | Description | | ----------- | ------- | ------- | ------------------------------------------------ | | `--verbose` | boolean | `false` | Displays verbose logging during the run. | | `--quiet` | boolean | `false` | Suppresses all progress, debug logs, and errors. | *** ## Configuration flags | Flag | Type | Default | Description | | ------------------------------------- | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `--save-assets` | boolean | `false` | Save the trace contents and devtools logs to disk alongside the report. | | `--list-all-audits` | boolean | `false` | Print a list of all available audits and exit. | | `--list-trace-categories` | boolean | `false` | Print a list of all required trace categories and exit. | | `--additional-trace-categories` | string | — | Additional Chrome trace categories to capture, comma-delimited. | | `--config-path` | string | — | Path to a custom config JS file. Overrides `--preset` when both are provided. | | `--preset` | string | — | Use a built-in configuration preset. Choices: `perf`, `experimental`, `desktop`. | | `--chrome-flags` | string | `""` | Space-delimited flags to pass to Chrome on launch. Uses `CHROME_PATH` env var if set. | | `--port` | number | `0` | Debugging protocol port. Use `0` for a random port. | | `--hostname` | string | `"localhost"` | Hostname for the debugging protocol. | | `--form-factor` | string | — | Affects scoring and skips mobile-only audits when set to `desktop`. Choices: `mobile`, `desktop`. For desktop audits, prefer `--preset=desktop`. | | `--screenEmulation` | — | — | Sets screen emulation parameters. Use `--screenEmulation.disabled` to disable, or set individual sub-flags (see below). | | `--screenEmulation.mobile` | boolean | — | Emulate a mobile viewport. | | `--screenEmulation.width` | number | — | Emulated viewport width in pixels. | | `--screenEmulation.height` | number | — | Emulated viewport height in pixels. | | `--screenEmulation.deviceScaleFactor` | number | — | Emulated device scale factor. | | `--screenEmulation.disabled` | boolean | — | Disable all screen emulation. | | `--emulatedUserAgent` | string | — | Override the user agent string sent with requests. | | `--max-wait-for-load` | number | — | Milliseconds to wait before considering the page done loading. High values can cause instability. | | `--enable-error-reporting` | boolean | — | Enable anonymous error reporting. Use `--no-enable-error-reporting` to opt out. | | `--gather-mode`, `-G` | string/boolean | — | Collect and save artifacts to disk, then quit. Optionally provide a folder path. | | `--audit-mode`, `-A` | string/boolean | — | Load saved artifacts from disk and run audits only. Defaults to `./latest-run/`. | | `--only-audits` | array | — | Run only the specified audit IDs. | | `--only-categories` | array | — | Run only the specified categories. Available: `accessibility`, `best-practices`, `performance`, `seo`. | | `--skip-audits` | array | — | Skip the specified audit IDs. | | `--disable-full-page-screenshot` | boolean | — | Skip full-page screenshot collection, which can be large. | `--gather-mode` and `--audit-mode` can be combined as `-GA` to run the full audit while also saving artifacts to disk for later re-analysis. *** ## Output flags | Flag | Type | Default | Description | | --------------- | ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `--output` | array | `["html"]` | Output format(s). Choices: `json`, `html`, `csv`. Accepts multiple values. | | `--output-path` | string | — | File path for the report. Use `stdout` for console output. When multiple formats are specified, the standard extension is appended to the base path. | | `--view` | boolean | `false` | Open the HTML report in a browser after the run. | ### Output path behavior | Command | Output | | -------------------------------------------------------------------------- | ----------------------------------------------------------- | | `lighthouse ` | `_.report.html` | | `lighthouse --output json` | JSON sent to stdout | | `lighthouse --output html --output-path ./report.html` | `./report.html` | | `lighthouse --output json --output html --output-path ./myfile.json` | `./myfile.report.json` and `./myfile.report.html` | | `lighthouse --output json --output html` | `_.report.json` and `_.report.html` | *** ## Other flags | Flag | Type | Default | Description | | ------------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------- | | `--version` | boolean | — | Print the Lighthouse version and exit. | | `--help` | boolean | — | Show the help text and exit. | | `--cli-flags-path` | string | — | Path to a JSON file containing default CLI flags. Command-line flags take priority over file-based ones. | | `--locale` | string | — | Locale for the report output (e.g. `en-US`, `fr`). | | `--blocked-url-patterns` | array | — | Block network requests matching these URL patterns. | | `--disable-storage-reset` | boolean | — | Skip clearing the browser cache and storage APIs before the run. | | `--throttling-method` | string | — | Throttling implementation to use. Choices: `devtools`, `provided`, `simulate`. | | `--throttling.rttMs` | number | — | Simulated network RTT at the TCP layer (ms). | | `--throttling.throughputKbps` | number | — | Simulated network download throughput (Kbps). | | `--throttling.requestLatencyMs` | number | — | Emulated network RTT at the HTTP layer (ms). | | `--throttling.downloadThroughputKbps` | number | — | Emulated network download throughput (Kbps). | | `--throttling.uploadThroughputKbps` | number | — | Emulated network upload throughput (Kbps). | | `--throttling.cpuSlowdownMultiplier` | number | — | CPU slowdown multiplier for simulated and emulated throttling. | | `--extra-headers` | string | — | JSON string or path to a JSON file of additional HTTP headers to send with requests. | | `--precomputed-lantern-data-path` | string | — | Path to a file with precomputed Lantern simulation data, overriding observed estimates. | | `--lantern-data-output-path` | string | — | Path to write Lantern simulation data for reuse in future runs. | | `--plugins` | array | — | Names of Lighthouse plugins to run. | | `--channel` | string | `"cli"` | Identifies the run channel for internal tracking. | | `--chrome-ignore-default-flags` | boolean | `false` | Ignore Lighthouse's default Chrome flags. | *** ## Usage examples ```bash theme={null} # Open HTML report in a browser after the run lighthouse https://example.com --view # Run with a custom config file lighthouse https://example.com --config-path=./myconfig.js # Save trace and named JSON report lighthouse https://example.com --output=json --output-path=./report.json --save-assets # Disable device emulation and throttling lighthouse https://example.com --screenEmulation.disabled --throttling-method=provided --no-emulatedUserAgent # Launch Chrome with a specific window size lighthouse https://example.com --chrome-flags="--window-size=412,660" # Run headless with quiet logging lighthouse https://example.com --quiet --chrome-flags="--headless" # Send custom HTTP headers lighthouse https://example.com --extra-headers "{\"Cookie\":\"session=abc\", \"x-api-key\":\"secret\"}" # Load headers from a file lighthouse https://example.com --extra-headers=./headers.json # Run only performance and SEO categories lighthouse https://example.com --only-categories=performance,seo ``` *** ## Lifecycle (gather/audit) mode Separate the gather and audit phases to reuse collected artifacts or integrate with external tools. ```bash theme={null} # Gather artifacts only, save to ./latest-run/ lighthouse https://example.com -G # Audit pre-collected artifacts from ./latest-run/ lighthouse https://example.com -A # Gather and audit, also saving artifacts lighthouse https://example.com -GA # Use a custom folder for artifacts lighthouse -GA=./my-artifacts https://example.com ``` When using `-A` (audit-only mode), Lighthouse skips the browser entirely and reads artifacts from disk. The URL argument is still required for report metadata but no network request is made. *** ## Connecting to an existing Chrome instance To audit a page that requires authentication or a specific browser state, launch Chrome manually with `chrome-debug` (installed globally alongside the CLI), log in, then point Lighthouse at the running instance. ```bash theme={null} # 1. Start a Chrome instance with an open debugging port chrome-debug # logs: "Debugging on port 9222" # 2. In a separate terminal, run Lighthouse against the port lighthouse https://mysite.com --port=9222 ``` *** ## Real device testing Disable emulation when auditing against a real connected Android device via ADB port forwarding. ```bash theme={null} adb forward tcp:9222 localabstract:chrome_devtools_remote lighthouse https://example.com \ --port=9222 \ --screenEmulation.disabled \ --throttling.cpuSlowdownMultiplier=1 \ --throttling-method=provided ```