---
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-07-05T10:27:15.328Z"
---

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

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      lighthouse CLI
    </th>
    
    <th>
      unlighthouse CLI
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Package
    </td>
    
    <td>
      <code>
        lighthouse
      </code>
    </td>
    
    <td>
      <code>
        unlighthouse
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Pages per run
    </td>
    
    <td>
      1
    </td>
    
    <td>
      Unlimited
    </td>
  </tr>
  
  <tr>
    <td>
      URL discovery
    </td>
    
    <td>
      Manual
    </td>
    
    <td>
      Automatic
    </td>
  </tr>
  
  <tr>
    <td>
      Interactive UI
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Yes
    </td>
  </tr>
  
  <tr>
    <td>
      Caching
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Yes
    </td>
  </tr>
  
  <tr>
    <td>
      Dynamic sampling
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Yes
    </td>
  </tr>
  
  <tr>
    <td>
      CI/CD ready
    </td>
    
    <td>
      Manual setup
    </td>
    
    <td>
      Built-in
    </td>
  </tr>
</tbody>
</table>

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

<table>
<thead>
  <tr>
    <th>
      Options
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

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

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