The reference

Ten commands, no guesswork

Two of them do almost everything: init once, then check forever. The rest are there for the days something is wrong, or CI needs to work differently.

npx norma-scope init

Nothing to install first — npx fetches it on the first run. Node 18 or newer is the whole list of requirements.

10: commands
1: config file
0: accounts

A terminal running npx norma-scope compare with the --json and --strict flags. It prints one line per frame — 0.3% aligned with 5.6% unaligned, SSIM 99 and two drifted sections for the first, 0.0% for the other two — then reports where the report and summary were saved, and that --strict is exiting 1 because one frame is above the threshold. — One real run. **Every command prints like this** — one line per page, the numbers that matter, and exactly where it put the files.

Grouped by what they do

Setup2Capture2Compare3Share2AI1Utility1

Start here

Answer three questions,
get a working config

This writes a real .bridge/config.json and the exact commands to run with it. Copy it into your project and it works.

1 · What are you comparing against?

A Figma fileDesigns live in FigmaA folder of PNGsSketch, Penpot, or a file someone sent youAnother URLStaging vs productionNothing — no designerJust tell me when something changes

2 · Can Normascope reach your app?

Yes, it runs at a URLLocally or on staging — capture for meNo, I'll capture by handNot runnable yet, or curated shots

3 · What should CI do when a frame drifts?

Flag it, don't blockThe default — CI stays greenFail the buildOpt in with --strict

.bridge/config.json

{
  "threshold": 5,
  "source": { "type": "images", "dir": "designs" },
  "app": { "baseUrl": "http://localhost:3000" },
  "frames": [
    {
      "label": "Pricing",
      "screenshot": "pricing.png",
      "route": "/pricing",
      "viewport": { "width": 1440, "height": 900 }
    }
  ]
}

then run

$ npx norma-scope init

$ npx norma-scope doctor

# start your app, then:

$ npx norma-scope check

$ open .bridge/reports/report.html

No token, no network, no account — the reference is already in your repo.

Every command

Pick one to see what it does

Setup

Once per project, or again if you switch design sources

Asks for your design file and token, then lists the frames in it so you can pick the ones you care about.
Saves each frame's real design dimensions — capturing your app at a different size than the design is the number one cause of a scary score that means nothing.
Creates the .bridge/ folders, adds the throwaway ones to .gitignore, and installs a pre-commit hook (backing up any existing hook first).
Prints the exact filename and pixel size it expects for every screenshot.
Figma-first, but you can hand-edit the config afterwards to point at an image folder or a URL instead.

Capture

Compare

Utility

Setup

Capture

Compare

Utility

Once per project, or again if you switch design sources

Asks for your design file and token, then lists the frames in it so you can pick the ones you care about.
Saves each frame's real design dimensions — capturing your app at a different size than the design is the number one cause of a scary score that means nothing.
Creates the .bridge/ folders, adds the throwaway ones to .gitignore, and installs a pre-commit hook (backing up any existing hook first).
Prints the exact filename and pixel size it expects for every screenshot.
Figma-first, but you can hand-edit the config afterwards to point at an image folder or a URL instead.

Reads: your answers, the design source's API
Writes: .bridge/config.json, the .bridge/ folders, .gitignore entries, a pre-commit hook

At a glance

What each one reads and writes

Command	Reads	Writes
init	your answers, the design source's API	.bridge/config.json, the .bridge/ folders, .gitignore entries, a pre-commit hook
doctor	config, token, design file, your app URL	nothing — diagnosis only
auto	config + your running app	.bridge/screenshots/*.png
compare	.bridge/screenshots/ + the reference your source points at	.bridge/diff/, report.html, and summary.json with --json
compare --target	the mock PNG and the --url you pass	screenshot, diff, report.html, and summary.json — always
check	—	everything auto and compare write
baseline	.bridge/screenshots/	.bridge/baseline/ plus a manifest — commit it
snapshot	the design file	.bridge/design/ — commit it
comment	.bridge/reports/summary.json	markdown on stdout
explain	screenshots, diffs, captured DOM context, your API key	findings in the terminal and in the report
clean	—	empties screenshots/, diff/, reports/ and the cache

Flags

The ones worth knowing

--json: Also write summary.json (schema v2, published and validated)
--full: Embed full-resolution images in the report
--fresh: Bypass the design cache and refetch
--strict: Exit 1 on a measured regression — the only way a job turns red
--all: Explain every compared frame, not just the flagged ones
--deep: Use the stronger, more expensive model
--check: On snapshot: has the live design drifted from the committed one?
--selector: On target mode: capture one element instead of the full page

Which do I want?

Start from the problem

“Just tell me if this page matches this picture.”

compare --target x.png --url …

“Do that for five pages, on every commit.”

init, then check

“Nothing loaded, or it says skipped.”

doctor

“There's no designer — I just don't want surprises.”

mode: "baseline", then baseline

“CI shouldn't need a design token.”

snapshot, and commit .bridge/design/

“Fail the build on a regression.”

compare --strict

“But why did it move?”

explain

Worth knowing

Three things that trip people up

Start your app first

Normascope photographs a running app; it doesn't start one. Run your dev server, then run the command.

Nothing is ever blocked

A bad score is information. The git hook always succeeds and CI stays green unless you explicitly ask for the opposite.

Name the file after the page

The screenshot filename is what ties your design, your capture and the difference together. Keep them the same and everything lines up.

Every command ships with --help, and doctor explains anything that’s misconfigured in your project rather than making you go and look it up.

All of that runs on one machine, for one person.

The moment a second person needs to see a result, or you need to know whether a page has been drifting, you need somewhere to put it.

See what it adds

What the report looks like