Sightmap CLI: Integration Tools Reference

sightmap atlas finds and installs corpora published in the community atlas. sightmap serve-sightmap serves the compiled corpus as JSON and recompiles it when YAML changes. sightmap skills install extracts the bundled agent skills. sightmap version prints the binary version.

sightmap browser start runs the same HTTP server alongside Chrome. Use serve-sightmap when you need the corpus endpoint without a managed browser session. See Browser for session management.

`sightmap atlas`

Three verbs over the community atlas (sightmap.org/atlas), the catalog of corpora other people have published:

Command	What it does
`sightmap atlas find QUERY`	Search by domain, name, category, or description
`sightmap atlas list`	Browse the whole catalog
`sightmap atlas add SLUG`	Install one corpus into `.sightmap/`
`sightmap atlas validate [FILE]`	Check a catalog before publishing it

They are grouped under atlas because a bare sightmap add would be ambiguous in a tool for authoring corpora, where adding a view or a component is the other thing it could mean. The index and the archives both come from sightmap.org/atlas, not from the atlas git repo. A takedown rebuilds the gallery, so an entry the atlas removes stops being findable and stops being installable in the same publish. --index and --source override the defaults, which is how mirrors and private corpora work.

`sightmap atlas find`

Start here when you have a URL. An exact domain match ranks above everything else, and each hit prints the command that installs it:

sightmap atlas find squareup.com

square-pos  Square POS
  Point-of-sale checkout, catalog, and order history.
  squareup.com, app.squareup.com · payments, commerce · 12 views, 48 components, 23 requests · verified 2026-07-14
  sightmap atlas add square-pos

1 match.

A query that matches nothing exits 0. Asking whether the atlas has a site is a question, and “no” is an answer. The message names every constraint that was applied, so a --category with nothing filed under it does not read as an empty atlas:

No atlas entry matches "stripe.com".
Run sightmap atlas list to see everything published, browse https://sightmap.org/atlas, or map the site yourself with sightmap init.

Matching is case-insensitive substring containment: a field that contains your query matches, so pos finds square-pos. Slugs and domains match the other way round too, so square-pos-terminal finds square-pos — those are the strings you paste a longer real-world form of. Names, categories, and descriptions match forwards only, because a three-letter category read in reverse makes position tracking a hit for every point-of-sale corpus in the atlas. Results are ordered by how they matched (exact domain, exact slug, domain, slug, name, category, description), with ties broken alphabetically. Flags:

Flag	Default	Description
`--category`	none	Keep only entries in a matching category
`--index`	`https://sightmap.org/atlas/index.json`	Atlas `index.json` URL (for mirrors and private catalogs)
`--json`	off	Print results as JSON
`--limit`	`10`	Show at most N results (`0` shows all)
`--refresh`	off	Re-fetch the index instead of using the cached copy

--json gives an agent everything a hit has, install command included:

sightmap atlas find squareup.com --json

{
  "query": "squareup.com",
  "total": 1,
  "shown": 1,
  "results": [
    {
      "slug": "square-pos",
      "name": "Square POS",
      "description": "Point-of-sale checkout, catalog, and order history.",
      "domains": [
        "squareup.com",
        "app.squareup.com"
      ],
      "categories": [
        "payments",
        "commerce"
      ],
      "stats": {
        "views": 12,
        "components": 48,
        "requests": 23
      },
      "last_verified": "2026-07-14",
      "matched_on": "exact domain",
      "install": "sightmap atlas add square-pos"
    }
  ],
  "index": {
    "source": "https://sightmap.org/atlas/index.json",
    "fetched_at": "2026-08-06T15:07:41Z",
    "cached": true
  }
}

The catalog is cached at ~/.sightmap/atlas/index.json for 24 hours, next to the browser cache at ~/.sightmap/browsers. A cached read says so, and --refresh skips it:

2 matches.
Catalog cached 2026-08-06 15:07 UTC. Pass --refresh to re-fetch.

`sightmap atlas list`

The same code path with an empty query, for browsing rather than searching. Takes --category, --limit, --json, --index, and --refresh.

sightmap atlas list --category commerce

acme-shop  Acme Shop
  Storefront, cart, and checkout for the Acme demo store.
  shop.acme.test · commerce · 3 views, 11 components, 6 requests · verified 2026-05-20
  sightmap atlas add acme-shop

square-pos  Square POS
  Point-of-sale checkout, catalog, and order history.
  squareup.com, app.squareup.com · payments, commerce · 12 views, 48 components, 23 requests · verified 2026-07-14
  sightmap atlas add square-pos

2 matches.

`sightmap atlas validate`

For whoever runs the atlas, not whoever reads it. Checks an index.json for the problems every shipped sightmap would hit, reporting all of them in one run so a publisher does not fix one entry per build:

sightmap atlas validate index.json

  entry 1: duplicate slug "square-pos"
  entry 2: slug "../escape" contains a path separator
  entry 3 (acme-shop): control character or invalid UTF-8 in Acme\x1b]0;pwned\x07

Exits 0 when the catalog is clean and 1 when it is not. Reads stdin for - or no argument. It runs against the bytes as published, which is the point: find escapes that text as it parses, so no reader ever sees the raw byte and only the publisher can fix it. A duplicate slug is the same shape of problem — the second entry silently shadows the first at install time, and only a whole-catalog check sees both.

`sightmap atlas add`

Installs one published corpus into --target (default .sightmap). The archive’s .sightmap/ prefix is stripped as files land, so the target may be named anything. Flags work before or after SLUG. Flags:

Flag	Default	Description
`--source`	`https://sightmap.org/atlas/{slug}.tar.gz`	Archive URL template, with `{slug}` substituted (for mirrors and private corpora)
`--target`	`.sightmap`	Directory to install the corpus into

sightmap atlas add square-pos

  wrote  .sightmap/components.yaml
  wrote  .sightmap/config.yaml
  wrote  .sightmap/views/checkout.yaml

Installed square-pos: 3 files → .sightmap. Next:
  sightmap validate

add fetches one archive from the URL template above and never reads the index. An index outage or a schema change cannot stop an install, and the atlas can add index fields without waiting for a CLI release. Installing from a private corpus store. --source is a whole URL template, so a team that publishes its own corpora serves them wherever it likes and points add at them:

sightmap atlas add toast-pos --source https://internal.corp/{slug}.tar.gz

Everything below still applies to that host: HTTPS only, the caps, the path rules, and the load check before the rename. --index does the same for a private catalog, so find and add can both run against an internal atlas. A slug the atlas does not publish is a failed action, so it exits 1 and points at the two ways to find the right one:

sightmap atlas: no corpus published for this slug: "no-such-thing" — browse https://sightmap.org/atlas, or search for the site: sightmap atlas find <domain>

A non-empty target is refused, and there is no --force. Deleting a directory that holds your work is your call. The refusal is decided before anything is fetched, so it reads the same offline:

sightmap atlas: install target already exists and is not empty: .sightmap — delete it and run this again to install over it

What add guarantees. A --index or --source URL you were handed by a stranger is untrusted input, and so is everything inside what it serves:

Guarantee	What it covers
HTTPS only	The index and the archive are both fetched over `https://`. Plain `http://` is refused except for loopback hosts (`localhost`, `127.0.0.1`, `::1`), so local mirrors and tests still work. The check runs again on every redirect hop, so a `302` cannot downgrade a fetch to plaintext after the scheme was approved. Chains stop after 5 redirects.
Bounded archives	8 MiB on the wire, 32 MiB decompressed, 4 MiB per file, and 512 members. The decompressed cap is the one that stops a gzip bomb, which is a few hundred KB on the wire and gigabytes on disk.
Fail-closed paths	Every archive member must be a regular file or a directory under `.sightmap/`. An absolute path, a `..` segment, a backslash, a symlink, or a control character (including `ESC`, the terminal-escape injection vector) refuses the whole install, and the joined path is re-checked for containment before anything is written.
Atomic install	The archive is extracted into a temporary directory beside the target and renamed into place. Until that rename the target does not exist, and the rename is one syscall. A 404, a broken entry, or a full disk leaves the target as it was.
A corpus that loads	The staged corpus is loaded before the rename. One that does not load is reported as a defect in the atlas entry, and nothing is installed.
Escaped output	Names, descriptions, domains, and categories are printed straight off the index, so every one is rendered terminal-safe. An entry whose slug could not be installed is never offered with an install command.

What add does not do is vet the corpus’s content. It proves the YAML loads and refuses paths that would escape the target. It does not check that the selectors are right, that the entry belongs to whoever the name suggests, or that anyone reviewed it. A corpus is data rather than code sightmap executes, but its description: and memory: text is read by your agent, so treat an unfamiliar atlas or --source host the way you would treat any other package source. Run sightmap validate and read the YAML before you trust it.

`sightmap serve-sightmap`

Compiles the .sightmap/ corpus and serves it over HTTP on port 7891 by default. Two endpoints:

Endpoint	Returns
`GET /sightmap`	The compiled corpus JSON: `site`, `version`, `views` (name and route), `globals`, and `viewComponents` keyed by route
`GET /sightmap/version`	A version-only response for polling clients: `{"version":"..."}`

The version value is a Unix-millisecond timestamp created with each compile. Both endpoints set Access-Control-Allow-Origin: *. The server watches .yaml and .yml files under .sightmap/ and recompiles 200 ms after the last filesystem event. It excludes the snapshots/ and review/ directories, so writing captures does not change the corpus version. The bundled browser extension fetches the corpus for its side panel and DevTools integration. browser start extracts the extension to ~/.sightmap/extension/ when it is missing or its bundled version has changed. Flags:

Flag	Default	Description
`--port`	`7891`	HTTP port to listen on
`--sightmap-dir`	`.sightmap`	Path to the `.sightmap/` directory

sightmap serve-sightmap

[serve-sightmap] listening on http://:7891

After a YAML change, the server logs [serve-sightmap] recompiled (v1753208412345) with the new version value. Fetch the compiled corpus:

curl -s localhost:7891/sightmap

{
  "site": "example-shop",
  "version": "1753208412345",
  "views": [
    { "name": "plp", "route": "/b/**" },
    { "name": "pdp", "route": "/p/**" }
  ],
  "globals": [
    {
      "name": "SiteHeader",
      "selector": "header[data-testid=\"site-header\"]",
      "parentChain": [],
      "properties": []
    }
  ],
  "viewComponents": {
    "/b/**": [
      {
        "name": "ProductPod",
        "selector": "[data-testid=\"product-pod\"]",
        "parentChain": [],
        "properties": [
          { "name": "label", "extract": "h3" }
        ]
      }
    ],
    "/p/**": []
  }
}

site is the basename of the directory the server was started in. Each component carries its name, a comma-joined selector string, a parentChain (always an array, empty for top-level components), and its properties.

The properties entries reflect property extraction (properties: on components), which the CLI implements as a draft extension — it is not part of spec v1 and may change.

`sightmap skills install`

Extracts the two agent skills embedded in the binary, each into its own subdirectory of the target directory:

sightmap-authoring: the corpus authoring playbook, including the edit-verify loop, coverage tiers, selector rules, and quality checks.
sightmap-browser: instructions for reading annotated snapshots and interacting with a live browser by component query.

The default target is ~/.agents/skills/. The command removes any existing directory for each bundled skill before extracting the new copy. Flags:

Flag	Default	Description
`--target`	`~/.agents/skills`	Directory to install skills into (each skill becomes a subdirectory)

sightmap skills install

installed 2 sightmap skill(s) → /Users/you/.agents/skills
  sightmap-authoring
  sightmap-browser
  version: 0.13.1

The skills are embedded in the binary. Run sightmap skills install again after upgrading the CLI.

`sightmap version`

Prints the version and exits. No flags.

sightmap version

sightmap version 0.13.1

Releases are published on GitHub Releases; see Install for the npm and go install paths.

Typical flow

Install the skills

Run sightmap skills install to extract sightmap-authoring and sightmap-browser under ~/.agents/skills/.

Start from a published corpus, if there is one

Run sightmap atlas find <domain> for the site you are mapping. If a corpus exists, the result prints the sightmap atlas add command that installs it; run sightmap validate and read the YAML before building on it.

Serve the corpus

Start a full session with sightmap browser start (the server is included), or run sightmap serve-sightmap standalone when you only need the HTTP endpoint.

Consume the endpoints

Point your tooling at GET /sightmap for the compiled corpus and poll GET /sightmap/version to detect changes. The overlay extension does exactly this.

Edit YAML and let it reload

Save a .yaml or .yml file under a watched corpus directory. The server recompiles 200 ms after the last filesystem event and changes the version value. Polling clients can then fetch the new corpus.

Overview

Browser

Capture and coverage

Selectors and corpus

Integrations

Sightmap CLI: Integration Tools Reference

`sightmap atlas`

`sightmap atlas find`

`sightmap atlas list`

`sightmap atlas validate`

`sightmap atlas add`

`sightmap serve-sightmap`

`sightmap skills install`

`sightmap version`

Typical flow

​sightmap atlas

​sightmap atlas find

​sightmap atlas list

​sightmap atlas validate

​sightmap atlas add

​sightmap serve-sightmap

​sightmap skills install

​sightmap version

​Typical flow

`sightmap atlas`

`sightmap atlas find`

`sightmap atlas list`

`sightmap atlas validate`

`sightmap atlas add`

`sightmap serve-sightmap`

`sightmap skills install`

`sightmap version`

Typical flow