Skip to content
Branch: master
Find file Copy path
Find file Copy path
6 contributors

Users who have contributed to this file

@patrickhulce @var-bin @HappyTobi @paulirish @statebait @jzabala
359 lines (271 sloc) 13.7 KB



The CLI is the primary API you'll use when setting up Lighthouse CI. Install the CLI globally to try it out locally.

npm install -g @lhci/cli


yarn global add @lhci/cli


All commands support configuration via a JSON file passed in via --config=./path/to/. Any argument on the CLI can also be passed in via environment variable. For example, --config=foo can be replaced with LH_RC_FILE=foo. Learn more about configuration.


Runs diagnostics to ensure a valid configuration, useful when setting up Lighthouse CI for the first time to test your configuration.

lhci healthcheck --help

Run diagnostics to ensure a valid configuration

  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
  --config   Path to JSON config file
  --fatal    Exit with a non-zero status code when a component fails the status
             check.                                                    [boolean]
  --checks   The list of opt-in checks to include in the fatality check. [array]


lhci healthcheck --fatal --checks=githubToken


Automatically run collect with sensible defaults and assert or upload as specified. Options for individual commands can be set by prefixing the option with the command name.


lhci autorun --config=./lighthouserc.json
lhci autorun --collect.numberOfRuns=5
lhci autorun

Starting a webserver

To allow autorun to automatically start your own webserver, add an npm script named serve:lhci. autorun will execute this script before collection.

example package.json excerpt:

  "scripts": {
    "serve:lhci": "NODE_ENV=production npm run server"

You can also supply the custom server initalization command from collect as a flag directly to autorun:

lhci autorun --collect.startServerCommand="rails server -e production"


Open a local lighthouse report that has been created using collect.


lhci open


Runs an interactive step-by-step wizard to create a new project on the LHCI server.


lhci wizard


Runs Lighthouse n times and stores the LHRs in a local .lighthouseci/ folder.

lhci collect --help

Run Lighthouse and save the results to a local folder

  --help                    Show help                                      [boolean]
  --version                 Show version number                            [boolean]
  --config                  Path to JSON config file
  --method                              [string] [choices: "node"] [default: "node"]
  --headful                 Run with a headful Chrome                      [boolean]
  --additive                Skips clearing of previous collect data        [boolean]
  --url                     A URL to run Lighthouse on.  You can evaluate multiple
                            URLs by adding this flag multiple times.
  --staticDistDir           The build directory where your HTML files to run
                            Lighthouse on are located.
  --chromePath              The path to the Chrome or Chromium executable to use for
  --puppeteerScript         The path to a script that manipulates the browser with
                            puppeteer before running Lighthouse, used for auth.
  --puppeteerLaunchOptions  The path to a script that manipulates the browser with
                            puppeteer before running Lighthouse, used for auth.
  --startServerCommand      The command to run to start the server.
  --startServerReadyPattern String pattern to listen for started server.
                                              [string] [default: "listen|ready"]
  --settings                The Lighthouse settings and flags to use when collecting
  --numberOfRuns, -n        The number of times to run Lighthouse.
                                                           [number] [default: 3]


# Basic usage
lhci collect --numberOfRuns=5 --url=
# Have LHCI start a server before running
lhci collect --start-server-command="yarn serve" --url=http://localhost:8080/
# Have LHCI use the built-in server on a static directory
lhci collect --staticDistDir=./dist
# Have LHCI use the built-in server and audit a specific URL
lhci collect --staticDistDir=./public --url=http://localhost/products/pricing/
# Run on multiple URLs
lhci collect --url= --url=
# Have LHCI start a server and login with puppeteer before running
lhci collect --start-server-command="yarn serve" --url=http://localhost:8080/ --puppeteer-script=./path/to/login-with-puppeteer.js

Using Puppeteer Scripts

NOTE: In order to use puppeteer scripts, you need to install puppeteer yourself, i.e. npm install --save puppeteer. Any version you like that has a .launch method compatible with v1.x or v2.x and works with the Chrome version installed in your environment should work.

When running Lighthouse CI on a page with behind authentication, you'll need to authorize the browser that Lighthouse CI will be using. While there are several different options to accomplish this, --puppeteer-script is one of the most flexible and convenient.

--puppeteer-script accepts a path to a JavaScript file that exports a function that will be invoked by Lighthouse CI before navigating, e.g. a script that will login to your site.

Example puppeteer-script.js

 * @param {puppeteer.Browser} browser
 * @param {{url: string, options: LHCI.CollectCommand.Options}} context
module.exports = async (browser, context) => {
  const page = await browser.newPage();
  await page.goto('http://localhost:8080/login');
  await page.type('#username', 'admin');
  await page.type('#password', 'password');
  await page.waitForNavigation();

Lighthouse CI will then use the browser that this script sets up when running Lighthouse. Note that if you store your credentials in localStorage or anything other than a cookie you might want to pair this option with --settings.disableStorageReset to force Lighthouse to keep the cache state.

For more information on how to use puppeteer, read up on their API docs.


Saves the runs in the .lighthouseci/ folder to desired target and sets a GitHub status check when token is available.

lhci upload --help

Save the results to the server

  --help                    Show help                                  [boolean]
  --version                 Show version number                        [boolean]
  --target                  The type of target to upload the data to. If set to
                            anything other than "lhci", some of the options will
                            not apply.
        [string] [choices: "lhci", "temporary-public-storage"] [default: "lhci"]
  --token                   [lhci only] The Lighthouse CI server token for the
                            project.                                    [string]
  --githubToken             The GitHub token to use to apply a status check.
  --githubAppToken          The LHCI GitHub App token to use to apply a status
                            check.                                      [string]
  --extraHeaders            [lhci only] Extra headers to use when making API
                            requests to the LHCI server.
  --serverBaseUrl           [lhci only] The base URL of the LHCI server where
                            results will be saved.
                                             [default: "http://localhost:9001/"]
  --urlReplacementPatterns  [lhci only] sed-like replacement patterns to mask
                            non-deterministic URL substrings.  [array] [default:


lhci upload --config=./lighthouserc.json
lhci upload --target=temporary-public-storage
lhci upload --serverBaseUrl=
lhci upload --extraHeaders.Authorization='Basic dGVzdDoxMjPCow=='

Build Context

When uploading to the Lighthouse CI server, the CLI will attempt to automatically infer the build context such as git hash, author, message, ancestor, etc. In most cases, there's nothing you need to change about this, but if you're running without a git repo, in a Jenkins environment, a CI provider we haven't documented yet, or are just running into errors, you can control the build context yourself.

The following environment variables override the inferred build context settings.

Name Example Format
LHCI_BUILD_CONTEXT__CURRENT_HASH e7f1b0fa3aebb6ef95e44c0d0b820433ffdd2e63
LHCI_BUILD_CONTEXT__ANCESTOR_HASH 78bafdcaf40e204c0d0b81b90bb76b9aa5834e11
LHCI_BUILD_CONTEXT__COMMIT_TIME 2019-11-29T16:43:39-05:00


Asserts the conditions in the Lighthouse CI config and exits with the appropriate status code if there were any failures. See the assertion docs for more.

lhci assert

Assert that the latest results meet expectations

  --help         Show help                                             [boolean]
  --version      Show version number                                   [boolean]
  --config       Path to JSON config file
  --preset       The assertions preset to extend
                           [choices: "lighthouse:all", "lighthouse:recommended"]
  --assertions   The assertions to use.
  --budgetsFile  The path (relative to cwd) to a budgets.json file.


lhci assert --config=./lighthouserc.json
lhci assert --preset=lighthouse:recommended --assertions.speed-index=off


Starts the LHCI server. This command is unique in that it is likely run on infrastructure rather than in your build process. Learn more about the LHCI server and how to setup your personal LHCI server accessible over the internet.

Run Lighthouse CI server

  --help                                 Show help                     [boolean]
  --version                              Show version number           [boolean]
  --config                               Path to JSON config file
  --logLevel        [string] [choices: "silent", "verbose"] [default: "verbose"]
  --port, -p                                            [number] [default: 9001]
                    [string] [choices: "sqlite", "postgres", "mysql"] [default: "sqlite"]
  --storage.sqlDatabasePath              The path to a SQLite database on disk.
  --storage.sqlConnectionUrl             The connection url to a postgres
  --storage.sqlConnectionSsl             Whether the SQL connection should force
                                         use of SSL   [boolean] [default: false]
  --storage.sqlDangerouslyResetDatabase  Whether to force the database to the
                                         required schema. WARNING: THIS WILL
                                         DELETE ALL DATA
                                                      [boolean] [default: false]


lhci server --storage.sqlDatabasePath=./lhci.db
lhci server --storage.sqlDialect=postgres --storage.sqlConnectionUrl="postgres://user@localhost/lighthouse_ci_db"


Configuring settings for Lighthouse CI is most easily done through a lighthouserc.json file. The file supports configuration for the four major commands, collect, upload, assert, and server. Learn more about configuration.


# Your config file is at `./lighthouserc.json` and will be picked up automatically
lhci <command>

# Specify a config file via command-line flag
lhci <command> --config=path/to/different/rc/file

Example Project Config File

  "ci": {
    "collect": {
      "numberOfRuns": 5
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "offscreen-images": "off",
        "uses-webp-images": "off"
    "upload": {
      "serverBaseUrl": ""

Example Server RC File

  "ci": {
    "server": {
      "port": 9009,
      "storage": {
        "sqlDatabasePath": "/home/lhci/lhci.db"
You can’t perform that action at this time.