Using the Unlighthouse CLI is the primary way to scan entire production sites.


npx unlighthouse --site <your-site># OR pnpm dlx unlighthouse --site <your-site>

Chromium Dependency

Unlighthouse aims to keep the installation size small, for this reason it depends natively on your locally installed chrome.

If you get errors about puppeteer or chrome not being available, the easiest way to resolve it is with the unlighthouse-puppeteer binary.

unlighthouse-puppeteer --site

You will need to use unlighthouse-puppeteer anywhere it says unlighthouse.


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

Do a the default scan.

unlighthouse --site --debug

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

unlighthouse --site --debug --no-cache --throttle --samples 3


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

See the Configuration section for more details and the guides.

CLI Options

-v, --versionDisplay version number.
--site <url>Host URL to scan.
--root <path>Define the project root.
--config-file <path>Path to config file.
--output-path <path>Path to save the contents of the client and reports to.
--cacheEnable the caching.
--no-cacheDisable the caching.
--desktopSimulate device as desktop.
--mobileSimulate device as mobile.
--throttleEnable the throttling.
--samplesSpecify the amount of samples to run.
--urlsSpecify explicit relative URLs as a comma-seperated list.
e.g. unlighthouse --site --urls /guide,/api,/config
--enable-javascriptWhen inspecting the HTML wait for the javascript to execute. Useful for SPAs.
--disable-javascriptWhen inspecting the HTML, don't wait for the javascript to execute.
--enable-i18n-pagesEnable scanning pages which use x-default.
--disable-i18n-pagesDisable scanning pages which use x-default.
-d, --debugDebug. Enable debugging in the logger.
-h, --helpDisplay available CLI options

Config File

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

export default {  site: '',  debug: true,  scanner: {    device: 'desktop'  }}