Getting Started

Unlighthouse CLI - Site-Wide Lighthouse

Copy for LLMs

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

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 for what LCP, CLS, and INP actually mean.

Quick Start

Pick your package manager:

npx 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

  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

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

Install Globally (Optional)

If you scan sites frequently:

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

Common First Scan Issues

Nothing happening?

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

npx unlighthouse --site example.com --debug

WSL Users

Chrome can be tricky in WSL. If you see connection errors, check the WSL troubleshooting guide.

Slow scans?

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

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.

What's Next?

Get Help

Edit this page
Markdown For LLMs
Did this page help you?

Integrations

Integrate Unlighthouse into your existing build tools, frameworks, and CI/CD pipelines for automated Lighthouse testing.