CLI & CI checks

Run the engine locally with har-analyze and post performance diffs on pull requests.

The har-analyze CLI#

har-analyze runs the same deterministic engine as this app, locally and in-process — no API calls, no account, works offline against a pre-captured .har. Anywhere a command takes a HAR file you can pass an http(s) URL instead and it's captured first (that needs a Playwright Chromium installed).

har-analyze capture <url> --out file.har   # record a HAR from a live URL
har-analyze analyze <file.har|url>         # findings + score, as markdown or --out json
har-analyze compare <base> <head>          # before/after diff
har-analyze ci                             # config-driven capture → compare → report

Markdown goes to stdout (redirect it wherever you like); progress and errors go to stderr. There is no AI in the CLI path — it's the pure engine, so output is stable run-to-run.

Catching regressions in CI#

The CI pattern: on each pull request, capture the preview deploy, compare it against the base branch's capture, and post the diff as a PR comment. The comment renderer is the same one the Fixes page uses, so reports look identical whether they come from CI or the app.

har-analyze ci drives it from a config file (har-analyzer.config.json): which URLs to capture, what to compare against, and where to write the report.
In GitHub Actions, install Chromium with playwright-core install --with-deps chromium before capturing — this repo's perf.yml workflow is the reference implementation.
A score drop or payload jump shows up on the PR that caused it — the cheapest possible time to fix a regression. For post-merge tracking, pair CI with monitors.

Push CI runs into your project history#

By default the CLI is fully local. Add an API token and each CI run is also saved to your workspace, so your project timeline, trends, and regression alerts include every pipeline run — not just manual uploads and monitors. Mint one under Settings → CI & API tokens (owners/admins only); the secret is shown once, so store it as a CI secret immediately.

# GitHub Actions
- uses: harpoon-solutions/har-analyzer@main
  with:
    preview-url: ${{ steps.deploy.outputs.url }}
    api-token: ${{ secrets.HARPOON_TOKEN }}   # Settings → CI & API tokens
    project: my-site                           # project name or id; created if missing

# Bare CLI (envs work too: HARPOON_TOKEN / HARPOON_PROJECT / HARPOON_API_URL)
har-analyze ci --token "$HARPOON_TOKEN" --project my-site

The push is fail-soft: if the hosted API is unreachable your build's result still comes from the local deterministic run — CI never goes red because the push failed.
Tokens are deliberately narrow: they can upload, analyze, compare, and read reports/projects — never billing, credentials, monitors, or team settings. Revoking a token (Settings) cuts it off immediately.
The secret is stored hashed; nobody — including us — can read it back. Lost one? Revoke it and mint a fresh token.

Still stuck? Email us or browse all guides.