---
title: "Lighthouse CLI for Entire Sites · Unlighthouse"
canonical_url: "https://unlighthouse.dev/integrations/cli"
last_updated: "2026-06-08T03:03:02Z"
meta:
  description: "Scan your entire website with Lighthouse from the command line. Alternative to lighthouse CLI that audits all pages automatically."
  "og:description": "Scan your entire website with Lighthouse from the command line. Alternative to lighthouse CLI that audits all pages automatically."
  "og:title": "Lighthouse CLI for Entire Sites · Unlighthouse"
---

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Integrations**

# **Lighthouse CLI for Entire Sites**

[Copy for LLMs](https://unlighthouse.dev/integrations/cli.md)

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',
  },
})
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/0.cli.md)

[Markdown For LLMs](https://unlighthouse.dev/integrations/cli.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/0.cli.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CI Integration**](https://unlighthouse.dev/integrations/ci) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Core Web Vitals Guide**](https://unlighthouse.dev/glossary)

[**SPAs** Configure Unlighthouse to scan single-page applications (SPAs) with client-side routing like React, Vue, and Angular apps.](https://unlighthouse.dev/guide/recipes/spa) [**CI/CD** Run unlighthouse-ci on every deploy. Auto-discovers every URL, runs Lighthouse on all of them in parallel, enforces a single budget. Works in GitHub Actions, GitLab CI, any pipeline.](https://unlighthouse.dev/integrations/ci)

**On this page **

- [Installation](#installation)
- [Unlighthouse CLI vs Lighthouse CLI](#unlighthouse-cli-vs-lighthouse-cli)
- [Usage](#usage)
- [Configuration](#configuration)