---
title: "Lighthouse CLI for Entire Sites"
description: "Scan your entire website with Lighthouse from the command line. Alternative to lighthouse CLI that audits all pages automatically."
canonical_url: "https://unlighthouse.dev/integrations/cli"
last_updated: "2026-09-16T04:44:33.191Z"
---

Scan your entire website from the command line with a rich interactive dashboard. Unlike the standard `lighthouse` CLI which tests one page at a time, Unlighthouse automatically discovers and audits all your pages.

## Installation

### Global install (recommended for frequent use)

```bash
npm install -g unlighthouse
```

### One-time run (no install)

```bash
npx unlighthouse --site example.com
```

Unlighthouse wraps the [Lighthouse npm package](https://www.npmjs.com/package/lighthouse) to enable site-wide scanning.

## Unlighthouse CLI vs Lighthouse CLI

| Feature          | lighthouse CLI | unlighthouse CLI |
| ---------------- | -------------- | ---------------- |
| Package          | `lighthouse`   | `unlighthouse`   |
| Pages per run    | 1              | Unlimited        |
| URL discovery    | Manual         | Automatic        |
| Interactive UI   | No             | Yes              |
| Caching          | No             | Yes              |
| Dynamic sampling | No             | Yes              |
| CI/CD ready      | Manual setup   | Built-in         |

### When to use Lighthouse CLI

- Single page audits
- Quick manual checks
- Debugging specific pages

### When to use Unlighthouse CLI

- Full site audits
- Pre-launch checks
- Ongoing monitoring
- CI/CD integration

## Usage

Once installed globally you'll have access to Unlighthouse through the `unlighthouse` binary.

Run the default scan.

```bash
unlighthouse --site example.com --debug
```

Run without caching, throttle the requests and do 3 samples.

```bash
unlighthouse --site example.com --debug --no-cache --throttle --samples 3
```

## Configuration

Configuring the CLI can be done either through the CLI arguments or through a config file.

See the [Configuration](#configuration) section for more details and the guides.

### CLI Options

| Options                           |                                                                                                                                                                            |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-v, --version`                   | Display version number.                                                                                                                                                    |
| `--site <url>`                    | Host URL to scan.                                                                                                                                                          |
| `--root <path>`                   | Define the project root. Useful for changing where the config is read from or setting up sampling.                                                                         |
| `--config-file <path>`            | Path to config file.                                                                                                                                                       |
| `--output-path <path>`            | Path to save the contents of the client and reports to.                                                                                                                    |
| `--cache`                         | Enable the caching.                                                                                                                                                        |
| `--no-cache`                      | Disable the caching.                                                                                                                                                       |
| `--desktop`                       | Simulate device as desktop.                                                                                                                                                |
| `--mobile`                        | Simulate device as mobile.                                                                                                                                                 |
| `--user-agent <user-agent>`       | Specify a top-level user agent all requests will use.                                                                                                                      |
| `--router-prefix <path>`          | The URL path prefix for the client and API to run from.                                                                                                                    |
| `--throttle`                      | Enable the throttling.                                                                                                                                                     |
| `--samples <samples>`             | Specify the amount of samples to run.                                                                                                                                      |
| `--sitemaps <sitemaps>`           | Comma separated list of sitemaps to use for scanning. Providing these will override any in robots.txt.                                                                     |
| `--urls <urls>`                   | Specify explicit relative paths to scan as a comma-separated list, disabling the link crawler.<br />e.g. `unlighthouse --site unlighthouse.dev --urls /guide,/api,/config` |
| `--exclude-urls <urls>`           | Relative paths (string or regex) to exclude as a comma-separated list. <br />e.g. `unlighthouse --site unlighthouse.dev --exclude-urls /guide/.*,/api/.*`                  |
| `--include-urls <urls>`           | Relative paths (string or regex) to include as a comma-separated list. <br />e.g. `unlighthouse --site unlighthouse.dev --include-urls /guide/.*`                          |
| `--enable-javascript`             | When inspecting the HTML wait for the javascript to execute. Useful for SPAs.                                                                                              |
| `--disable-javascript`            | When inspecting the HTML, don't wait for the javascript to execute.                                                                                                        |
| `--enable-i18n-pages`             | Enable scanning pages which use x-default.                                                                                                                                 |
| `--disable-i18n-pages`            | Disable scanning pages which use x-default.                                                                                                                                |
| `--disable-robots-txt`            | Disables the robots.txt crawling.                                                                                                                                          |
| `--disable-sitemap`               | Disables the sitemap.xml crawling.                                                                                                                                         |
| `--disable-dynamic-sampling`      | Disables the sampling of paths.                                                                                                                                            |
| `--extra-headers <headers>`       | Extra headers to send with the request. Example: --extra-headers foo=bar,bar=foo                                                                                           |
| `--cookies <cookies>`             | Cookies to send with the request. Example: --cookies foo=bar;bar=foo                                                                                                       |
| `--auth <auth>`                   | Basic auth to send with the request. Example: --auth username:password                                                                                                     |
| `--default-query-params <params>` | Default query params to send with the request. Example: --default-query-params foo=bar,bar=foo                                                                             |
| `-d, --debug`                     | Debug. Enable debugging in the logger.                                                                                                                                     |
| `-h, --help`                      | Display available CLI options                                                                                                                                              |

### Config File

If you want to configure Unlighthouse, you can create a `unlighthouse.config.ts` file in your cwd.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'example.com',
  debug: true,
  scanner: {
    device: 'desktop',
  },
})
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.