> ## 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.

# Using the CLI

> Run Lighthouse from the command line with full control over configuration, output formats, and the audit lifecycle.

The Lighthouse CLI gives you the most flexibility for configuring runs, automating audits, and integrating Lighthouse into CI pipelines.

## Installation

```bash theme={null}
npm install -g lighthouse
# or with yarn:
yarn global add lighthouse
```

<Note>
  Lighthouse requires Node 22 (LTS) or later.
</Note>

Run your first audit:

```bash theme={null}
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.

| Flag            | Type    | Default | Description                                                                                                                                                      |
| --------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--output`      | array   | `html`  | Reporter format(s). Choices: `json`, `html`, `csv`. Accepts multiple values.                                                                                     |
| `--output-path` | string  | —       | 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. |
| `--view`        | boolean | `false` | Open the HTML report in your browser after the run.                                                                                                              |

### Configuration flags

Control which audits run and how the browser behaves.

| Flag                | Type    | Default | Description                                                                                                            |
| ------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--preset`          | string  | —       | Use a built-in configuration. Choices: `perf`, `experimental`, `desktop`. Ignored if `--config-path` is also provided. |
| `--config-path`     | string  | —       | Path to a custom config file (JS or JSON).                                                                             |
| `--only-categories` | array   | —       | Run only the specified categories: `accessibility`, `best-practices`, `performance`, `seo`.                            |
| `--only-audits`     | array   | —       | Run only the specified audit IDs.                                                                                      |
| `--skip-audits`     | array   | —       | Run everything except the specified audit IDs.                                                                         |
| `--locale`          | string  | —       | Locale for the report output (e.g. `en`, `fr`, `ja`).                                                                  |
| `--plugins`         | array   | —       | Additional Lighthouse plugins to run.                                                                                  |
| `--save-assets`     | boolean | `false` | Save trace and DevTools log files to disk alongside the report.                                                        |

### Throttling flags

| Flag                                 | Type    | Default    | Description                                                           |
| ------------------------------------ | ------- | ---------- | --------------------------------------------------------------------- |
| `--throttling-method`                | string  | `simulate` | Throttling strategy. Choices: `devtools`, `provided`, `simulate`.     |
| `--throttling.rttMs`                 | number  | —          | Simulated network round-trip time (TCP layer).                        |
| `--throttling.throughputKbps`        | number  | —          | Simulated network download throughput.                                |
| `--throttling.cpuSlowdownMultiplier` | number  | —          | CPU slowdown multiplier for simulated and emulated throttling.        |
| `--form-factor`                      | string  | —          | `mobile` or `desktop`. Use `--preset=desktop` for a full desktop run. |
| `--screenEmulation.disabled`         | boolean | —          | Disable screen emulation entirely.                                    |
| `--screenEmulation.width`            | number  | —          | Emulated screen width in pixels.                                      |
| `--screenEmulation.height`           | number  | —          | Emulated screen height in pixels.                                     |

### Chrome flags

| Flag             | Type   | Default     | Description                                                                         |
| ---------------- | ------ | ----------- | ----------------------------------------------------------------------------------- |
| `--chrome-flags` | string | `""`        | Space-delimited flags passed directly to Chrome (e.g. `"--headless --no-sandbox"`). |
| `--port`         | number | `0`         | DevTools Protocol port. `0` picks a random available port.                          |
| `--hostname`     | string | `localhost` | DevTools Protocol hostname.                                                         |

## Output format examples

<CodeGroup>
  ```sh HTML (default) theme={null}
  lighthouse https://example.com
  # saves ./<HOST>_<DATE>.report.html
  ```

  ```sh JSON to stdout theme={null}
  lighthouse https://example.com --output json
  # JSON output written to stdout
  ```

  ```sh HTML to a specific path theme={null}
  lighthouse https://example.com --output html --output-path ./report.html
  # saves ./report.html
  ```

  ```sh Multiple formats theme={null}
  lighthouse https://example.com --output json --output html
  # saves ./<HOST>_<DATE>.report.json and ./<HOST>_<DATE>.report.html
  ```

  ```sh Multiple formats with base path theme={null}
  lighthouse https://example.com --output json --output html --output-path ./myfile.json
  # saves ./myfile.report.json and ./myfile.report.html
  # NOTE: the specified extension is ignored for ALL formats when using multiple outputs
  ```

  ```sh Save trace and assets theme={null}
  lighthouse https://example.com --output-path=~/mydir/foo.out --save-assets
  # saves ~/mydir/foo.report.html
  # saves ~/mydir/foo-0.trace.json and ~/mydir/foo-0.devtoolslog.json
  ```
</CodeGroup>

## 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.

```sh theme={null}
# -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
```

<Tip>
  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.
</Tip>

## More examples

```sh theme={null}
# 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:

```sh theme={null}
# Enable error reporting
lighthouse https://example.com --enable-error-reporting

# Disable error reporting
lighthouse https://example.com --no-enable-error-reporting
```