WebPerf Snippets CLI

Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes and gate CI on real performance budgets.

Why

Lighthouse gives you a score. The DevTools snippets give you the diagnosis, TTFB / Resource Load Delay / Element Render Delay sub-parts, LoAF script attribution, render-blocking resources, and more. The CLI runs the same curated snippets in a headless browser so you can:

• Diagnose LCP regressions in CI without copy-pasting into DevTools.
• Gate pull requests on real performance budgets.
• Automate the snippets you already run by hand.

Install

Playwright is a peer dependency. Install both, then download the Chromium browser:

npm install --save-dev webperf-snippets playwright
npx playwright install chromium

Usage

npx webperf-snippets <url> [options]

Examples

Run the default Core Web Vitals workflow (LCP + CLS, plus LCP-Subparts when LCP exceeds 2.5s):

npx webperf-snippets https://web.dev

JSON output (for piping into jq or CI scripts):

npx webperf-snippets https://web.dev --json

Run a single snippet by alias or by its own name, in any case. Every snippet of the collection runs this way, with or without its category:

npx webperf-snippets https://web.dev --snippet LCP-Subparts
npx webperf-snippets https://web.dev --snippet render-blocking
npx webperf-snippets https://web.dev --snippet fonts
npx webperf-snippets https://web.dev --snippet Compression-Audit
npx webperf-snippets https://web.dev --snippet Interaction/DOM-Size-and-Depth

An unknown name exits with code 2 and lists the closest snippets.

Measure pages behind a login with a Playwright storage state (cookies and localStorage):

# Step 1: sign in once and save the session
npx playwright codegen --save-storage=auth.json https://example.com/login
 
# Step 2: measure an authenticated page
npx webperf-snippets https://example.com/dashboard --storage-state auth.json

The file holds live session cookies. Keep it out of version control (add it to .gitignore) and use a throwaway account when you run it in CI. The CLI exits with code 2 if the path does not exist.

Script the interactions of a page and measure them with --interact-script. The file lists the steps to run after the page loads:

{
  "interactions": [
    { "action": "scroll", "y": 600 },
    { "action": "wait", "ms": 300 },
    { "action": "click", "selector": "#menu" },
    { "action": "type", "selector": "input[name=q]", "text": "shoes" },
    { "action": "hover", "selector": ".product" },
    { "action": "wait", "ms": 500 }
  ]
}

npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
npx webperf-snippets https://web.dev --snippet Interaction/Interactions --interact-script interactions.json

The snippets of the Interaction category, such as Interactions, Input-Latency-Breakdown, LongTask or Forced-Synchronous-Layout, record what happens while the page is used. With a script, the CLI installs them before the first step, runs the steps, and then reads their data, so the result holds what the steps caused. The other snippets run after the steps.

The CLI waits for the browser to report the timing of the last interaction before it reads the snippets. A script that ends right after a click still reads the page before anything the click sets in motion later has happened, such as a request or an animation, so end it with a wait step when you want to measure that.

Compare the measured values with CrUX field data (what real users experience at the 75th percentile):

CRUX_API_KEY=your-key npx webperf-snippets https://web.dev

Field data (CrUX p75, mobile)
  🟡 LCP    2.80s      needs-improvement    (synthetic: 2.10s)
  🟢 CLS    0.0800     good                 (synthetic: 0.0500)
  🟡 INP    220ms      needs-improvement    (synthetic: n/a)

Get a key for the Chrome UX Report API (opens in a new tab) and pass it with --crux-key or the CRUX_API_KEY environment variable; prefer the variable, because a flag ends up in shell history and CI logs. The section appears in the human and markdown output and under crux in the --json output.

• The population follows --viewport: desktop uses desktop data, mobile and tablet use phone data. The heading says which one.
• When the page itself has no data, the CLI looks the origin up instead and labels the section origin-level, so it is not mistaken for page-level data. If the origin has none either, the output says Field data: not available.
• A CrUX error (quota, network, no answer within 10 seconds) only skips the section. It never changes the exit code, and the key is never printed.
• INP shows n/a as the synthetic value unless you run an interaction script.

Send the results to an endpoint after the run with --report-to:

npx webperf-snippets https://example.com --workflow audit \
  --report-to https://reports.example.com/api/report \
  --api-key $REPORT_API_KEY

Without --report-to the CLI makes no external calls. With it, the results are POSTed as JSON once the snippets have finished:

{
  "url": "https://example.com",
  "workflow": "audit",
  "timestamp": "2026-05-06T10:00:00.000Z",
  "navMs": 1240,
  "results": [],
  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "0.5.0" }
}

For a --snippet run, workflow is null and a snippet field carries the name. results is the same list the --json output contains, so it can include URLs and details of the measured page; send it only to an endpoint you trust.

• The URL must be https. http is accepted only for localhost, so a key is never sent in clear text.
• --api-key is sent as Authorization: Bearer <key>. Prefer the PERF_REVIEWS_API_KEY environment variable, because a flag ends up in shell history and CI logs. The key is never printed.
• The exit code never depends on the report. A failed POST (error status, unreachable endpoint, or no answer within 5 seconds) prints a warning and the exit code stays the one the budgets and snippets decide. If the endpoint answers { "ok": false, "regressions": [...] }, the regressions are printed as a warning, again without changing the exit code.

Snippet aliases

Gate CI on performance budgets:

npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1

Run the structural audit workflow:

npx webperf-snippets https://web.dev --workflow audit

The audit runs these checks on one page load. Only an issue of severity error makes the command exit with code 1; warnings and notes appear in the report without changing the exit code.

The steps that make requests of their own run last, so those requests do not change what the earlier steps read.

Run the loading workflow, which measures timing on a real page load:

npx webperf-snippets https://web.dev --workflow loading

It runs these steps on one page load. As in the audit, only an issue of severity error makes the command exit with code 1.

The step that makes requests of its own (cache-strategy reads cache headers with HEAD requests) runs last, so those requests do not change what the earlier steps read.

Run the interaction workflow, which measures what happens while the page is used:

npx webperf-snippets https://web.dev --workflow interaction
npx webperf-snippets https://web.dev --workflow interaction --interact-script interactions.json

It installs the Interaction snippets, runs the interactions, and then reads them. Without --interact-script it scrolls the page, because clicks and typing belong to each site; with the script it runs the steps of the file instead. As in the other workflows, only an issue of severity error makes the command exit with code 1.

interactions and input-latency need a click or a type step. When the interactions have none, they appear as skipped with the reason, and they do not count as errors. When the script has a click but the page records no interaction, they report an error, which tells you the step did not reach an element that responds.

Simulate a mobile viewport (default) or switch to desktop:

npx webperf-snippets https://web.dev --viewport mobile
npx webperf-snippets https://web.dev --viewport desktop

Show all items, including passing checks:

npx webperf-snippets https://web.dev --verbose

Options

Follow-up steps

The results of a run can add steps. They run on the same page load, appear after the steps of the workflow, and show the reason that added them. Each snippet runs once, and a snippet the workflow already ran is not repeated. The results of a follow-up do not add steps of their own.

A follow-up informs: the error issues it reports appear in the report and do not change the exit code. Use the audit workflow, or --snippet with the snippet itself, to gate on them.

Exit codes

Run it from an AI agent

Each snippet page has a Copy prompt button above the code. The prompt asks an AI agent with a terminal to run that snippet with this CLI, pinned to the published version, and to report the result. It includes the install command, the --snippet name, an --interact-script when the snippet needs interactions, and how to read the status, issues and corsLimitedAnalysis fields. The agent asks for the URL if you do not give it one.

The snippets an agent cannot run in a meaningful way have no button: the Fetch & XHR Timeline overrides, which need DevTools Local Overrides, the Long Animation Frames helpers, and Network Bandwidth & Connection Quality, because headless Chromium reports the connection of the machine it runs on. The Back/forward cache prompt says that the result is partial, since the CLI does not navigate back.

CI integration

GitHub Actions example, fail the PR if LCP exceeds 2.5s:

- run: |
    npm install --no-save webperf-snippets playwright
    npx playwright install --with-deps chromium
    npx webperf-snippets https://staging.web.dev --budget-lcp 2500 --budget-cls 0.1

GitHub Action

The repository ships a composite action that installs the CLI and Chromium, runs a workflow and exposes the result as markdown, so any repository can gate on performance budgets without extra setup:

jobs:
  webperf:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: nucliweb/webperf-snippets/.github/actions/webperf-snippets@main
        id: webperf
        with:
          url: https://staging.example.com
          budget-lcp: 2500
          fail-on-budget: "false"
 
      - uses: actions/github-script@v7
        env:
          BODY: ${{ steps.webperf.outputs.markdown }}
        with:
          script: |
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: process.env.BODY,
            });
 
      - if: steps.webperf.outputs.exit-code != '0'
        run: exit 1

The markdown includes text taken from the measured page, so pass it to other steps through an environment variable (env: and process.env) as above, never by interpolating ${{ steps.webperf.outputs.markdown }} inside a script. With fail-on-budget: "false" the action step always succeeds, which lets later steps post the comment before the job fails. Without permissions: pull-requests: write the comment step cannot post on a pull request.

LCP, CLS and INP vary by 15 to 30% on shared runners; prefer the deterministic audit workflow for a gate, or generous budgets.

How it works

1. Launches headless Chromium via Playwright.
2. Pre-registers PerformanceObservers for LCP and layout-shift before navigation.
3. Navigates and waits for the page to settle.
4. Evaluates each snippet’s IIFE in the page context, capturing the returned object.
5. Applies the workflow’s decision tree to enqueue follow-up snippets.
6. Renders results (human-readable or JSON) and exits with the appropriate code.

Known limitations

• Synthetic INP ≠ field INP: --interact-script measures the latency of the steps it scripts. Real INP reflects the worst interaction across real sessions; use RUM for field data.
• CLS in headless is conservative: layout shifts that only happen on scroll are missed unless you script the scroll.
• First navigation only: each invocation runs one URL. SPAs need the post-route URL passed directly.
• Follow-ups see the page as it is: they run after the steps of the workflow on the same page load, so they read what is there when they run, not a fresh load.

Further reading

• GitHub Repository (opens in a new tab), source code and issue tracker
• npm package (opens in a new tab), changelog and releases