sightmap binary is a single authoring toolkit: it drives a Chrome for Testing session over the Chrome DevTools Protocol, layers your .sightmap/ corpus onto the live page, and gives you commands for capturing annotated snapshots, measuring coverage, validating selectors, and interacting with the page. This page covers the conventions shared across the whole surface; the pages linked below document each command group in full.
Not installed yet? See Install the Sightmap CLI. The short version:
npm install -g @sightmap/sightmap or go install github.com/sightmap/sightmap/go/cmd/sightmap@latest.Global conventions
Put flags before positional arguments. The CLI uses Go-style flag parsing, which stops at the first positional argument. Some interaction commands tolerate interspersed flags, butsightmap snapshot --url URL always works and sightmap snapshot URL --url never does — make flags-first a habit. Single-dash (-url) and double-dash (--url) spellings are equivalent.
Run commands from the site directory. Most commands read the corpus from --sightmap-dir, which defaults to .sightmap in the current directory.
A handful of flags recur across the surface:
One session per site, addressed by port and tab.
sightmap browser start launches Chrome with its DevTools endpoint on localhost:7892 and the sightmap HTTP server on port 7891. Every live command dials --addr to reach that session. When more than one content tab is open — the concurrent multi-agent case — page-affecting commands refuse to guess and require --tab with the tab ID that browser start printed. See Browser sessions.
Visible-only counting is the default. Coverage and analysis commands count visible interactive nodes only. Pass --include-hidden to widen the count to hidden and off-screen nodes — deliberately, since doing it unintentionally inflates orphan counts with false failures.
Exit codes
Every command exits0 on success and 1 on any failure — there is no richer exit-code taxonomy. Errors print to stderr as sightmap <command>: <message>.
What counts as failure for the check-style commands:
Command map
Browser sessions
Install Chrome for Testing, start and stop sessions, navigate, evaluate JavaScript, and reset storage.
Page interaction
Click, fill, scroll, and screenshot the live page — targeting elements by component identity.
Capturing pages
snapshot, inspect, and iterate — annotated component trees and the edit-verify loop.Coverage
coverage, multi-coverage, and report — the T1/T2/T3 done-signal for a corpus.View sets
snapshot-novelty, snapshot-prune, and migrate-snapshots — maintain each view’s set of captures.Selector tools
sel-probe, sel-check, suggest, and gap — verify selectors live and offline.Corpus checks
validate, lint, search, and discover — structural and style checks over your YAML, plus URL pattern discovery.Integration
serve-sightmap and skills install — the overlay server and the embedded agent skills.sightmap version prints the build version and exits — see Integrations.
Typical flow
1
Install once
Install the CLI (Install), then
sightmap browser install to download Chrome for Testing.2
Start a session
From the site directory, run
sightmap browser start — Chrome plus the sightmap server, with the overlay extension loaded (Browser sessions).3
Iterate on pages
Capture annotated snapshots and close coverage gaps with
iterate, snapshot, and the selector tools (Capturing pages, Coverage).4
Check corpus health
Finish with
validate, lint --warn-only, and report (Corpus checks, Coverage).