sightmap CLI drives Chrome for Testing over the Chrome DevTools Protocol (CDP). Its commands apply .sightmap/ to the live page, capture annotated snapshots, measure coverage, validate selectors, and interact with page elements. This page covers conventions shared across command groups.
In the standard authoring workflow, the sightmap-authoring and sightmap-browser skills run these commands for the agent; this reference documents the surface they drive. You can also run any command directly.
See Install the Sightmap CLI for all install options. To install directly, run
npm install -g @sightmap/sightmap or go install github.com/sightmap/sightmap/go/cmd/sightmap@latest.Global conventions
Put flags before positional arguments. Most commands use Go-style flag parsing, which stops at the first positional argument. Interaction commands accept flags in either position, but putting them first works consistently:-url) and double-dash (--url) spellings. browser navigate and browser eval parse --addr and --tab directly, so use the double-dash form shown in this reference.
Run commands from the site directory. Most commands read the corpus from --sightmap-dir, which defaults to .sightmap in the current directory.
Several flags appear in multiple command groups:
Address sessions by port and tab.
sightmap browser start launches Chrome with its DevTools endpoint on localhost:7892 and the Sightmap HTTP server on port 7891. Live commands use --addr to reach the session. When more than one content tab is open, page commands require --tab with the tab ID printed by browser start. See Browser sessions.
browser start is the only launcher. Live commands attach to a session you started; there is no auto-launch. When none is running they stop with Start a session first: sightmap browser start. That single owner also hosts the console/network collector behind the devtools commands.
Vocabulary. A sightmap view is a route-scoped definition in the corpus; a browser tab is a live page in the session. They are different things — the glossary disambiguates
view, tab, and related terms.--include-hidden to include hidden and off-screen nodes. These nodes can increase the orphan count, so enable the flag only when you intend to audit them.
Exit codes
Commands exit0 on success and 1 when command execution returns an error. Errors print to stderr as sightmap <command>: <message>.
What counts as failure for the check-style commands:
A page with no interactive nodes renders the
∅ mark (rather than ✓/✗) in the coverage line.
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 by component identity.
Snapshot & capture
Use
snapshot to observe component trees, capture to persist them, and inspect for the raw DOM.Coverage
Use
coverage, multi-coverage, and report to measure T1, T2, and T3 coverage.View sets
Use
capture-novelty and capture-prune to maintain each view’s captures.Selector tools
Verify selectors with
sel-probe, sel-check, suggest, and gap.Corpus checks
Check YAML structure and style, count what the corpus holds, search it, and discover URL patterns.
Devtools
Read captured
console messages and network requests from the running session.Integration
Find and install corpora with
atlas, run the overlay server, and install the bundled agent skills.sightmap version prints the build version and exits. See Integration.
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. It launches Chrome, the Sightmap server, and the overlay extension (Browser sessions).3
Iterate on pages
Observe annotated snapshots and close coverage gaps with
snapshot --coverage, then persist captures with capture and the selector tools (Snapshot & capture, Coverage).4
Check corpus health
Run
validate, lint, and report (Corpus checks, Coverage).