@sightmap/cli

The sightmap command-line tool validates, lints, and queries a .sightmap/ directory. It’s the day-to-day check on your work — what runs in CI, what the Claude Code plugin shells out to, what you reach for when an agent’s edit produced something suspicious.

The CLI ships as part of @sightmap/sightmap — a single npm package containing both the bin and the library. See @sightmap/core for the programmatic API.

Install

pnpm add -D @sightmap/sightmap

Or run on demand without installing:

npx sightmap validate

Commands

Command	What it does
`sightmap validate [path]`	Schema-validate every YAML file under `path` (default `.sightmap`).
`sightmap lint [path]`	Quality checks beyond schema — duplicate routes, route shadowing, unknown sources, selector syntax.
`sightmap check [path]`	Combined validate + lint. Powers the plugin’s PostToolUse hook.
`sightmap match <url> [path]`	Resolve a URL against the sightmap; print the view, components, requests, and merged memory an agent would see.
`sightmap explain <query> [path]`	Find every entry tied to a name or source path.
`sightmap check-conventions [path]`	Validate repo-level filename conventions for SEPs and conformance fixtures. Operates on a repo root, not a `.sightmap/` directory.

Every command supports --json for machine-readable output and --cwd <dir> to invoke from outside the project root.

Common workflows

Validate after an agent edit

sightmap check

Returns 0 on success, 1 on any error. Run this after Claude Code, Cursor, or any other agent has written to .sightmap/. The plugin does this automatically via PostToolUse.

Drive a URL like an agent would

sightmap match /list/abc123

Prints the matched view, every applicable component (with selectors), and the aggregated memory. This is exactly what the runtime sees when an agent calls match(). Useful for sanity-checking that a route resolves the way you expect.

Find everything tied to a file

sightmap explain 'src/components/Foo.tsx'

Returns every view, component, and request entry that references that source path. Run this before refactoring — it tells you what will break.

CI gate

sightmap check --strict

--strict upgrades warnings (duplicate routes, merge collisions, unknown sources) to errors. Pair with sightmap-react gen --check to catch source drift in the same step.

Flags

--json — machine-readable envelope. Every command emits the same shape: { ok, command, diagnostics, result }. Agents dispatch on command.
--cwd <dir> — run as if invoked from <dir>. Necessary when a host agent (MCP server, plugin) is calling sightmap from outside the target project.
--strict (lint, check) — treat warnings as errors.
--require-view (match) — exit 1 if no view matched. Useful in tests.
--require-hit (explain) — exit 1 if zero hits.

Exit codes

0 — success.
1 — logical failure: validation error, --strict warning, --require-* miss.
2 — usage error.

JSON envelope

{
  "ok": true,
  "command": "match",
  "diagnostics": [],
  "result": { "view": "...", "components": [] }
}

diagnostics use a stable shape with kebab-case codes (duplicate-route, route-shadowing, unknown-source, etc.). The full code table lives in the package README on GitHub.