har-trace-viewer

Command-line tool that analyzes a HAR file, and optionally a Chrome DevTools trace, and shows the page load in the terminal, writes it as a self-contained HTML report, or writes it as JSON for other tools and AI agents.

npx har-trace-viewer <file.har[.gz]> [<trace.json[.gz]>] [-o <dir|file.html|file.json>] [--format tui|html|json|findings] [--select <id|text>] [--region default|cn]
npx har-trace-viewer --page <name> --har <file.har[.gz]> [--trace <file.json[.gz]>] [--page <name> ...] [--compare | --compare-with <file.har[.gz]>] [options]

Install it globally with npm i -g har-trace-viewer to get the htv command. A HAR can be given on its own (htv page.har), followed by its Chrome trace (htv page.har trace.json.gz); files are told apart by extension, so a HAR saved with another extension needs --har.

The destination picks the format. Without --output, the report opens in the terminal with five tabs: Findings (what to fix, grouped by severity, with the metric it affects, what to do and the resources that show it), Overview (the metrics summary), Steps (the diagram's steps with the route, metrics and resources of each), Hosts and Cache & network (the cache and network reports and their recommendations, with the resources they name); 1–5 or Tab switch tabs, ←/→ walk the steps on the Steps tab and the pages of a multi-page flow elsewhere (p/P next and previous page too), ↑/↓ and PgUp/PgDn scroll, a/b pick the side of a comparison and q quits. It needs an interactive terminal. --output report.html writes a single self-contained HTML file with the interactive diagram, inlined JavaScript, CSS and fonts, which opens offline. --output report.json writes the full analysis as JSON ({ "htvVersion", "kind": "flow", "flow" }, or "kind": "comparison" with "a" and "b"), and --format json without --output prints it to stdout, to pipe into another tool or an AI agent. --format findings writes only the findings of each page (a stable rule id, severity, affected metric, one-sentence summary, recommendation, confidence and evidence) with its metrics as numbers, to stdout or a .json --output; the document links to its JSON schema, dist/findings.schema.json in this package. The HTML report shows the same findings behind its Findings button. Any other --output is a directory that receives an index.html and its assets (--bundle inlines them). htv --help prints the full usage and htv --version the installed version.

Pass --page once per page you want in the report, each followed by its --har and optional --trace. A HAR recorded across several navigations (several entries in log.pages) is expanded into one flow page per navigation, named after the page titles (prefixed with the --page name when given), and its --trace is attached to the page whose document URL matches the trace.

--select <value> narrows the preceding --har when it holds several pages, as a WebPageTest export does (runs and first/repeat views). The value is a page id (page_1_0_1), a comma-separated list of ids, or text matched case-insensitively against page id, title and URL (--select "Run 1, First"; a regular expression also works). An unknown selection exits with an error listing the available pages. --list-pages prints the pages of each --har (id, entry count, title) and exits without generating. WebPageTest pages are named Run 1 · First view and Run 1 · Repeat view.

--compare turns a report into a comparison of its two pages: the first page is A (drawn on top), the second B (drawn below), and the flow must have exactly two pages. A WebPageTest first view against its repeat view, i.e. without and with cache, is --har wpt.har --select page_1_0_1,page_1_1_1 --compare; two separate recordings are --page "Cold" --har cold.har --page "Warm" --har warm.har --compare. --compare-with <file.har> compares the flow (one page) with another HAR instead, with --compare-trace <file> for its trace and --compare-select <value> to pick one page of a multi-page HAR (as --select); a single-page HAR is named after its file. The comparison report steps through both diagrams with one track, pairing steps of the same kind (a side without that step keeps its previous one, dimmed), shows both sides' step metrics with the B − A delta, and its Deltas panel compares the metrics summary and every host's requests and TTFB.

--region sets where the client browser sits on the network. default (used when the flag is absent) draws the browser talking directly to the CDN or origin. cn places it in China behind the Great Firewall: the diagram adds a GFW inspection node between the browser and the first server, and an Akamai edge without a visible PoP is shown in Hong Kong. Any other value exits with an error. When the latencies of the first page look compatible with GFW routing (document DNS above 80 ms or a TCP connect above 300 ms) and --region is absent, the CLI prints a note suggesting --region cn; a slow or mobile network produces the same latencies, so the topology never changes without the flag.

--budget <metric>=<value>[,...] and --fail-on critical|warning check every page (both sides of a comparison) for CI: ttfb, server-wait, fcp, lcp, dcl, onload and inp in ms (2500, 2500ms, 2.5s), cls, requests, transfer in bytes (500kb, 1.5mb) and the minimums cdn-hit-ratio and cache-hit-ratio (0.9 or 90%). htv prints one pass/FAIL line per budget per page, and one per finding at the --fail-on severity or worse (a recommendation, or a Core Web Vital or TTFB rated poor, critical, or in need of improvement, warning), to stderr after the report, or to stdout without --output (no terminal report opens, so it runs without a TTY). A metric the page lacks (LCP without a trace) passes as n/a unless --budget-strict. Exit codes: 0 all checks passed, 2 a check failed (the report is still written), 1 usage or input errors.

The report covers network requests, resource timing, and Core Web Vitals-related metrics derived from the trace, and it groups requests into the steps of the page flow.

Source code and issues: https://github.com/nucliweb/har-trace-viewer