@responsivejs/cli — the rjs command line

The zero-setup surface of r$: point it at any URL and get the full oracle — constraints, aesthetic score, a11y — as console output, JSON, or SARIF. Exit codes make it CI- and agent-loop-ready: 0 pass, 1 violations, 2 usage/run error.

rjs analyze <url>              sweep + oracle (constraints + score + a11y)
rjs audit <url>                one-shot HTML report with screenshots
rjs verify <contract> <url>    execute a design contract against a live page
rjs record <contract> <url>    measure and pin baseline curves into the contract
rjs init <url>                 generate a contract from the page's r$ constructs
rjs snippet                    emit the injectable browser bundle (--bookmarklet)
rjs doctor                     check drivers and environment readiness

Options

Option	Meaning	Default
-d, --driver	auto | playwright | agent-browser	auto
-w, --widths	comma-separated widths (320,768,1280)	contract / built-in sweep
-s, --selectors	comma-separated selectors (analyze)	landmark set
-f, --format	console | json | sarif (contract SARIF carries each rule's authored intent)	console
-o, --out	write the report (or recorded contract) to a file	stdout
--height	viewport height	900
--touch-min	touch-target minimum px (analyze)	24 (WCAG AA; platform is 44–48)
--scroll	scroll-sweep below-the-fold content	off
--no-a11y	skip axe (analyze)	axe runs when available
--strict	fail on warnings too (analyze)	errors only
--headed	show the browser window (playwright)	headless
--vs <url>	audit a second site side by side (audit)	—
--crawl	follow same-origin links (audit)	off
--max-pages <n>	crawl limit (audit)	5
--screenshots <dir>	also write the per-width PNGs to a directory (audit)	embedded only

Drivers

• playwright — chromium via the optional playwright / @playwright/test peer. The CI driver.
• agent-browser — Vercel's agent-browser CLI, found on PATH (or via AGENT_BROWSER_BIN). Zero npm install in the target project: the oracle runs through the CLI's eval, with oversized injections (axe) chunked automatically. The driver uses an isolated --session.
• auto — playwright if installed, else agent-browser, else a clear install hint.

rjs doctor probes all of the above — node version, playwright + chromium, agent-browser — one line per check with the exact install command for anything missing, and tells you which driver auto will pick. Exit 0 = at least one driver usable, 1 = none.

audit — the report you hand to someone

rjs audit <url> is analyze packaged as a deliverable: full oracle + per-width screenshots, rendered into one self-contained HTML file (rjs-audit.html by default) — images embedded, violation rectangles drawn as overlays from the measured rects, apply-verbatim fixes tabled, provenance owners named. Nothing to install for the reader.

• --crawl walks same-origin links breadth-first up to --max-pages (default 5); pages discovered but not audited are reported, never silently dropped.
• --vs <url> audits a competitor too — the report leads with a side-by-side table (errors, warnings, checks, aesthetic score).
• --screenshots <dir> additionally saves the raw PNGs (<host-path>-<width>.png).
• Screenshots need a driver with the screenshot seam (playwright and agent-browser both have it). Without one the report says so and ships without images; passing --screenshots explicitly in that case is an error.
• Exit codes as analyze: 0 all pages pass, 1 violations, --strict gates on clean.

init — the free regression net

On a page that runs @responsivejs/runtime, the constructs declare their behavior in the provenance manifest. rjs init <url> -o app.contract.json turns those declarations into rules the oracle verifies: numeric fluid on a measurable prop → monotonic + continuous

• a baseline; ratio bounds → proportion; the page's r$.breakpoints → the viewport widths — plus the noOverflow default. What can't be expressed yet (geometry, sync, tokens, element-driven fluids) is listed on stderr, never dropped silently. Then rjs record pins today's curves and rjs verify in CI holds the page to its own declarations. Exits 2 when the page has no manifest.

snippet — the oracle without a terminal

rjs snippet emits the browser-global bundle (window.rjs, ~52 kB) ready to inject:

• default — a paste-ready <script> block that mounts the <rjs-overlay> badge;
• --bookmarklet — a javascript: URL: save it as a bookmark, click it on any page you're looking at, and the overlay appears with live violation counts, grouped findings and element highlighting. Everything is inline — nothing hosted, nothing phoned home.
• -o <file> writes instead of printing.

The overlay measures at the current viewport and says so — the CLI commands remain the full-sweep truth.

verify and record

The sweep is derived from the contract itself: selectors from rule args, widths from viewport (plus bp±1 for breakpointSafe). record fills baselines[].curve from measurements and writes the contract back (--out to write elsewhere) — the record-then-assert flow:

rjs record home.contract.json https://staging.example.com   # pin today's geometry
rjs verify home.contract.json https://pr-42.example.com     # regressions fail with exit 1

Programmatic use

Everything the binary does is exported: main(argv, io?) (inject CliIo for testing), resolveDriver, DEFAULT_SELECTORS.