---
title: "Unlighthouse CLI - Site-Wide Lighthouse · Unlighthouse"
meta:
  "og:description": "Install and run Unlighthouse CLI to scan your entire website with Lighthouse. npm, pnpm, and yarn installation options."
  "og:title": "Unlighthouse CLI - Site-Wide Lighthouse · Unlighthouse"
  description: "Install and run Unlighthouse CLI to scan your entire website with Lighthouse. npm, pnpm, and yarn installation options."
---

**Getting Started**

# **Unlighthouse CLI - Site-Wide Lighthouse**

[Copy for LLMs](https://unlighthouse.dev/guide/getting-started/installation.md)

Stop checking pages one at a time. Run a single command and get Lighthouse scores for your entire site in minutes.

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

> !TIP Generate an Agent Skill for this package using [**skilld**](https://github.com/harlan-zw/skilld):```
npx skilld add unlighthouse
```

That's it. Unlighthouse will crawl your site, find every page, run Lighthouse on each one, and open a dashboard where you can watch results stream in live.

New to Lighthouse? Check the [**Core Web Vitals glossary**](https://unlighthouse.dev/glossary) for what [**LCP**](https://unlighthouse.dev/glossary/lcp), [**CLS**](https://unlighthouse.dev/glossary/cls), and [**INP**](https://unlighthouse.dev/glossary/inp) actually mean.

## [Quick Start](#quick-start)

Pick your package manager:

```
npx unlighthouse --site https://mysite.com
```

```
pnpm dlx unlighthouse --site https://mysite.com
```

```
yarn dlx unlighthouse --site https://mysite.com
```

A browser window opens automatically showing your scan progress. Results appear as each page completes—no waiting for the full scan to finish.

### [What Happens Behind the Scenes](#what-happens-behind-the-scenes)

1. **Discovery** — Unlighthouse reads your sitemap and crawls internal links to find every page
2. **Parallel scanning** — Multiple Chrome instances run Lighthouse audits simultaneously
3. **Live results** — Scores stream to your dashboard as each page completes
4. **Smart sampling** — Similar pages (like blog posts) are sampled to avoid redundant scans

### [Requirements](#requirements)

- **Node.js 20+**
- **Chrome** — Uses your system Chrome. If missing, downloads Chromium automatically.

### [Install Globally (Optional)](#install-globally-optional)

If you scan sites frequently:

```
npm install -g @unlighthouse/cli
unlighthouse --site example.com
```

## [Common First Scan Issues](#common-first-scan-issues)

### [Nothing happening?](#nothing-happening)

Add `--debug` to see what's going on:

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

### [WSL Users](#wsl-users)

Chrome can be tricky in WSL. If you see connection errors, check the [**WSL troubleshooting guide**](https://unlighthouse.dev/guide/guides/common-errors#connect-econnrefused-127001port).

### [Slow scans?](#slow-scans)

Your first scan downloads route data and warms up Chrome. Subsequent scans use caching and are much faster.

## [Configure Your Scan](#configure-your-scan)

Create `unlighthouse.config.ts` in your project root:

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

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    samples: 3, // Run each page 3x and average (more accurate)
    throttle: true, // Simulate real network conditions
    exclude: ['/admin/*', '/api/*'], // Skip these paths
  },
})
```

Now just run `unlighthouse` without flags—it reads your config automatically.

See [**all configuration options**](https://unlighthouse.dev/guide/guides/config).

## [What's Next?](#whats-next)

- **[**CI Integration**](https://unlighthouse.dev/integrations/ci)** — Run scans on every deploy, fail builds on performance regressions
- **[**Large Sites**](https://unlighthouse.dev/guide/recipes/large-sites)** — Scanning thousands of pages efficiently
- **[**Authentication**](https://unlighthouse.dev/guide/guides/authentication)** — Scan pages behind login

## [Get Help](#get-help)

- **[**Discord**](https://discord.gg/275MBUBvgP)** — Quick questions and community help
- **[**GitHub Issues**](https://github.com/harlan-zw/unlighthouse/issues)** — Bug reports and feature requests

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/0.installation.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/getting-started/installation.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/1.guide/1.getting-started/0.installation.md) on GitHub or provide anonymous feedback below.

[**Integrations** Integrate Unlighthouse into your existing build tools, frameworks, and CI/CD pipelines for automated Lighthouse testing.](https://unlighthouse.dev/guide/getting-started/integrations)

**On this page **

- [Quick Start](#quick-start)
- [Common First Scan Issues](#common-first-scan-issues)
- [Configure Your Scan](#configure-your-scan)
- [What's Next?](#whats-next)
- [Get Help](#get-help)