# WebPerf Snippets CLI > Source: 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: ```bash copy npm install --save-dev webperf-snippets playwright npx playwright install chromium ``` ## Usage ```bash copy npx webperf-snippets [options] ``` ### Examples Run the default Core Web Vitals workflow (LCP + CLS, plus LCP-Subparts when LCP exceeds 2.5s): ```bash copy npx webperf-snippets https://web.dev ``` JSON output (for piping into `jq` or CI scripts): ```bash copy 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: ```bash copy 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): ```bash copy # 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: ```json copy { "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 } ] } ``` ```bash copy 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): ```bash copy 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](https://developer.chrome.com/docs/crux/api) 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`: ```bash copy 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: ```json { "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 `. 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 | Alias | Snippet | Category | | ------------------ | ------------------------------------------------ | --------------- | | `LCP` | Largest Contentful Paint | Core Web Vitals | | `CLS` | Cumulative Layout Shift | Core Web Vitals | | `INP` | Interaction to Next Paint | Core Web Vitals | | `LCP-Subparts` | LCP Subparts breakdown | Core Web Vitals | | `fonts` | Fonts Preloaded, Loaded, and Used Above The Fold | Loading | | `render-blocking` | Find render-blocking resources | Loading | | `resource-hints` | Resource Hints Validation | Loading | | `preload-scripts` | Validate Preload / Async / Defer Scripts | Loading | | `priority-hints` | Priority Hints Audit | Loading | | `critical-css` | Critical CSS Detection | Loading | | `ttfb` | TTFB Sub-Parts | Loading | | `script-parties` | First and Third-Party Script Info | Loading | | `script-loading` | Script Loading | Loading | | `lazy-atf` | Above-the-fold lazy-loaded images | Loading | | `lazy-conflict` | Images with `lazy` + `fetchpriority` conflict | Loading | | `eager-below-fold` | Non-lazy images outside viewport | Loading | Gate CI on performance budgets: ```bash copy npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1 ``` Run the structural audit workflow: ```bash copy 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. | Step | Checks | | -------------------- | --------------------------------------------------------------------------------------- | | `render-blocking` | Render-blocking CSS and scripts | | `resource-hints` | Preload, preconnect and dns-prefetch hints that nothing uses, and origins that need one | | `preload-scripts` | Scripts that combine preload with `async` or `defer` | | `priority-hints` | `fetchpriority` on the images that matter | | `critical-css` | Critical CSS inlined in the head | | `ttfb` | Time to first byte split into its sub-parts | | `script-parties` | First-party and third-party scripts | | `script-loading` | Loading strategy of every script | | `compression` | Text resources sent without compression | | `inline-scripts` | Size and parser blocking of inline scripts | | `inline-css` | Size and weight of inline CSS | | `webfonts` | Web fonts that fail, never load or weigh too much | | `content-visibility` | Offscreen sections that could use `content-visibility` | | `prefetch` | Prefetch hints for files the page already uses, and their total size | | `lazy-atf` | Lazy-loaded images above the fold | | `lazy-conflict` | Images with both `loading="lazy"` and `fetchpriority="high"` | | `eager-below-fold` | Images below the fold that load eagerly | | `video` | Poster, preload, autoplay and dimensions of `