@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/sightmap validate

Commands

Command	What it does
`sightmap init`	Zero-to-one installer. Detects framework + coding-agent harness + Sightmap-aware vendor MCP, runs framework setup, and writes MCP config or prints plugin-install instructions.
`sightmap fmt [path]`	Canonical-format every YAML file under `path`. `--check` exits `1` on non-canonical (CI-ready); `--write` rewrites in place. Comment-preserving.
`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.

Initialize a new project

sightmap init is the zero-to-one installer. It detects your framework (React Router 7, Next.js, Vite, plain Node), your coding-agent harness (Claude Code, Codex, Cursor, OpenCode), and any Sightmap-aware vendor MCP already on the machine, then walks you through the choices it can’t infer.

There are two install paths:

Plugin path — when a supported harness is present, init prints the marketplace /plugin marketplace add and /plugin install commands and stops. The plugin owns MCP and hooks.
Manual path — writes (or merges) a .mcp.json for @sightmap/mcp, pinning the version from the plugin’s compatibleMcpVersion field, and sets SIGHTMAP_PLUGIN_VERSION on the spawned env. Framework setup (codegen, provider codemod) runs in this path too.

npx @sightmap/sightmap init --yes --host claude-code

Flags: --yes (accept all defaults), --plugin / --manual (force install path), --host <names> (comma-separated host list), --with-browser / --curate-only (force browser-tools mode), --no-codegen / --no-provider (skip framework setup steps).

Format a corpus

sightmap fmt canonicalizes the YAML in .sightmap/ so every commit lands in the same shape regardless of who wrote it — human, codegen, or MCP adapter. The formatter follows the canonical YAML rules and preserves comments.

sightmap fmt              # print diff, exit 0
sightmap fmt --check      # CI mode: exit 1 if anything is non-canonical
sightmap fmt --write      # rewrite files in place

Pair --check with sightmap check --strict in CI to gate both shape and content. The MCP and React adapters call the same formatter internally, so files they emit are already canonical.

The formatter canonicalizes dependencies[] arrays by lexicographic sort + deduplication and positions the dependencies key after source per the canonical key order. $ref entries round-trip unchanged.

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'
sightmap explain --by path 'src/hooks/useChecklist.ts'

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

--by path also consults every entry’s dependencies[] globs, not just the exact source field. Hits report a matchedBy value in --json output — "source" for direct binding, "dependencies" for a glob match — so callers can distinguish primary from supplementary attribution.

CI gate

sightmap check --strict

--strict upgrades warnings (duplicate routes, merge collisions, unknown sources) to errors. This validates .sightmap/ against itself — schema, key ordering, cross-file references, duplicates. It does not compare against React source; static source-vs-yaml drift detection is intentionally absent (see the workflow concepts page).

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.

init-specific flags

--yes — accept all defaults, non-interactive.
--plugin / --manual — force install path.
--host <names> — comma-separated host list (claude-code, codex, cursor, opencode).
--with-browser / --curate-only — force browser-tools mode.
--no-codegen / --no-provider — skip framework setup steps.

fmt-specific flags

--check — verify-only; exit 1 if any file is non-canonical.
--write — rewrite files in place.

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": { "name": "ListView" },
    "views": [
      { "name": "ListView", "dependencies": ["src/hooks/useChecklist.ts"] }
    ],
    "components": []
  }
}

match --json carries both the singular view and a plural views[] array (additive — old consumers reading view keep working). Each entry in views[] is a ResolvedView, and components[] entries are ResolvedComponents; both surface an optional dependencies field reflecting the entry-level setting.

diagnostics use a stable shape with kebab-case codes. The plug-in check command adds five codes in 0.11.0 + 0.12.0:

Code	Severity	Triggered when
`dependencies.self-redundant`	warning	An entry’s `dependencies[]` resolves to a path that equals its own `source`.
`dependencies.overlaps-entry`	warning	An entry’s `dependencies[]` resolves to a path that is the `source` of another entry.
`unknown-source` (narrowed)	warning	A glob in `dependencies[]` matches zero files. The existing code’s vocabulary now also covers `dependencies[]` globs.
`ref-unresolved`	error	A `$ref` value does not name a registered file-root component.
`ref-circular`	error	A `$ref` chain, after expansion, is self-referential.

The full code table lives in the package README on GitHub.