> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sightmap.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Sightmap Browser Commands: Managing Chrome Sessions

> Install Chrome for Testing, start and stop sightmap sessions, navigate, evaluate JavaScript, and reset storage from the command line.

`sightmap browser` manages the Chrome for Testing session used by live commands. Sightmap records the session in `.sightmap/.session`. By default, Chrome exposes its DevTools endpoint on `localhost:7892`; `browser start` also runs the Sightmap HTTP server on port `7891` for the overlay extension.

<Note>
  This page covers session management. See [Page interaction](/cli/interaction) for `click`, `fill`, `screenshot`, `bounds`, and tab management. See [Capturing pages](/cli/capture) for annotated component trees. Page commands also accept `--addr` and `--tab`; see the [shared conventions](/cli/overview).
</Note>

***

### `browser install`

Downloads the latest stable Chrome for Testing into `~/.sightmap/browsers/` and prints the path to the installed binary. Idempotent: if the current stable version is already installed, it prints the path and exits `0`. Takes no flags.

```bash theme={null}
sightmap browser install
```

```text theme={null}
Resolving latest Chrome for Testing (Stable)...
  version: 151.0.7922.47  platform: mac-arm64
Downloading https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.47/mac-arm64/chrome-mac-arm64.zip
    5%  8 / 178 MB     25%  44 / 178 MB     50%  89 / 178 MB     75%  133 / 178 MB    100%  178 / 178 MB
Extracting...
Installed: /Users/you/.sightmap/browsers/chrome-151.0.7922.47/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing
/Users/you/.sightmap/browsers/chrome-151.0.7922.47/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing
```

The final line is the binary path on stdout, so scripts can capture it; progress goes to stderr.

***

### `browser start`

`start` launches Chrome, starts the Sightmap HTTP server, and loads the overlay extension. The extension is embedded in the binary and extracted to `~/.sightmap/extension/` when needed. The server recompiles the corpus after YAML changes under `.sightmap/`. `start` runs in the foreground until you press Ctrl-C, which stops Chrome and the server.

The `start` daemon owns the session: it is the only way to launch Chrome for sightmap, and every live command attaches to it. It also runs the console/network **collector** that buffers browser activity for the [`console` and `network`](/cli/devtools) commands, so those need a running `start` session.

Run it from the site directory (the one containing `.sightmap/`), typically in a second terminal or as a background job. `start` creates `.sightmap/` if it is absent and records the session at `.sightmap/.session`; if it cannot persist that file it fails loudly rather than running sessionless. Every other command finds the session through this file, keyed by `--sightmap-dir` — so with no session file a command falls back to the default CDP port and **warns**, since a session answering there may belong to a different corpus or agent. Pass `--addr` to target a specific session explicitly.

| Flag             | Default                                          | Description                                                                       |
| ---------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
| `--port`         | `7891`                                           | Sightmap HTTP server port (`0` = auto-allocate)                                   |
| `--cdp-port`     | `7892`                                           | Chrome remote debugging port (`0` = auto-allocate)                                |
| `--sightmap-dir` | `.sightmap`                                      | Path to the corpus directory                                                      |
| `--extensions`   | embedded overlay                                 | Comma-separated extension paths to load instead of the embedded overlay extension |
| `--url`          | none                                             | Navigate here after launch                                                        |
| `--profile`      | per-site directory under `~/.sightmap/profiles/` | Chrome user data dir                                                              |
| `--headless`     | off                                              | Run Chrome headless                                                               |
| `--wait`         | `0`                                              | Seconds to wait after navigation                                                  |

```bash theme={null}
cd sites/shop.example.com/
sightmap browser start --url 'https://shop.example.com'
```

```text theme={null}
[serve-sightmap] listening on http://:7891
● ready  port=7891  cdp=7892  pid=84210  tab=8A3F0C7D2B1E4F6A9C8D7E5B3A2F1E0D
  Addr: --addr localhost:7892
  Tab:  --tab 8A3F0C7D2B1E4F6A9C8D7E5B3A2F1E0D  (pass this on commands once other agents open tabs here)
  Press Ctrl-C to stop.
```

<Note>
  If Chrome is already running for this site, `start` opens a new tab in the existing session and prints that tab's ID:

  ```text theme={null}
  ● tab    cdp=7892  tab=F2B71D9E4C8A2B5F0E3D6C1A9B8E7F4A
    Chrome was already running for this site; opened a NEW tab for you.
    Pass --tab F2B71D9E4C8A2B5F0E3D6C1A9B8E7F4A on EVERY command this session — other tabs belong to other agents.
  ```

  Pass that ID as `--tab` on every subsequent page command.
</Note>

***

### `browser stop`

Stops the session's Chrome process group. If needed, it finds remaining processes by profile directory. It removes the session file after Chrome stops. Takes no flags.

```bash theme={null}
sightmap browser stop
```

```text theme={null}
stopping Chrome (pgid 84210, port 7892)...
stopped
```

With no session running it prints `no active session` and exits `0`.

***

### `browser status`

Reports session health by probing the CDP endpoint and lists each open content tab with its `--tab` value. If Chrome is gone, it prints `✗ unreachable`, removes the stale session file, and tells you to run `browser start` again.

| Flag    | Default | Description                        |
| ------- | ------- | ---------------------------------- |
| `--tab` | none    | Mark this tab in the status output |

```bash theme={null}
sightmap browser status
```

```text theme={null}
● running  cdp=7892  pid=84210
  profile: /Users/you/.sightmap/profiles/shop.example.com
  tabs (2):
    --tab 8A3F0C7D2B1E4F6A9C8D7E5B3A2F1E0D  https://shop.example.com/
    --tab F2B71D9E4C8A2B5F0E3D6C1A9B8E7F4A  https://shop.example.com/cart
  multiple tabs open — pass --tab <ID> on page commands to avoid crosstalk.
```

With no session it prints `○ no session`. If a Chrome process for the site's profile is still alive without a session file, it reports `⚠ orphan` and points you at `browser stop` to reap it.

***

### `browser navigate`

Navigates the session to a URL and waits for the page to load. The URL is a positional argument. After a redirect — server-side or client-side (an SPA auth guard bouncing `/login → /`, or `/ → /workspace`) — `navigate` prints the requested and final URLs, so you know where you actually landed.

| Flag     | Default              | Description   |
| -------- | -------------------- | ------------- |
| `--addr` | `localhost:7892`     | CDP address   |
| `--tab`  | the lone content tab | Target tab ID |

```bash theme={null}
sightmap browser navigate 'https://shop.example.com/deals'
```

```text theme={null}
navigated to https://shop.example.com/deals
  (redirected to https://shop.example.com/offers)
```

<Warning>
  `browser navigate` takes a positional URL. It has no `--url` flag; that flag belongs to `browser start`. `sightmap browser navigate --url 'https://...'` treats `--url` as the URL and fails.
</Warning>

***

### `browser eval`

Evaluates a JavaScript expression in the page context. The script is a positional argument. The command pretty-prints JSON objects and arrays.

Only JSON-serializable values can be returned. A DOM element reference such as `document.querySelector(...)` cannot be returned by value; extract a property such as `document.querySelector('h1')?.textContent`.

| Flag     | Default              | Description   |
| -------- | -------------------- | ------------- |
| `--addr` | `localhost:7892`     | CDP address   |
| `--tab`  | the lone content tab | Target tab ID |

```bash theme={null}
sightmap browser eval '({url: location.href, title: document.title})'
```

```text theme={null}
{
  "title": "Example Shop — Home",
  "url": "https://shop.example.com/"
}
```

***

### `browser inject`

Injects a script into the page. Where `eval` runs once in the current document, `inject --persist` registers the script with the session daemon so it re-runs at the start of **every new document, in every tab, for the life of the session** — surviving navigations. It is backed by CDP `Page.addScriptToEvaluateOnNewDocument`, held on the daemon's session-lifetime connection (a script added over a per-command connection would be dropped the moment that command exits). Handy for polyfills, overlays, and instrumentation or experimentation bundles that must outlive a multi-page flow.

Provide the source as an inline positional argument or with `--file`. `--persist` also runs the script once in the currently-loaded document (best-effort), since `addScriptToEvaluateOnNewDocument` only affects future documents.

| Flag        | Default              | Description                                                       |
| ----------- | -------------------- | ----------------------------------------------------------------- |
| `--file`    | —                    | Read the script source from this file instead of an inline arg    |
| `--persist` | `false`              | Re-inject on every new document and new tab for the whole session |
| `--remove`  | —                    | Remove a previously-persisted script by its id                    |
| `--list`    | `false`              | List the scripts currently persisted for this session             |
| `--addr`    | `localhost:7892`     | CDP address (one-shot run)                                        |
| `--tab`     | the lone content tab | Target tab ID (one-shot run)                                      |

`--persist`, `--remove`, and `--list` require a running `browser start` session, since the registry lives in its daemon.

```bash theme={null}
# Register a bundle that re-applies on every navigation, and print its id.
sightmap browser inject --file ./runtime.js --persist
# inject: persisted as inj-1 — re-injected on every new document; remove with 'browser inject --remove inj-1'

sightmap browser inject --list
sightmap browser inject --remove inj-1
```

***

### `browser mcp`

Enumerate and call the [WebMCP](https://webmachinelearning.github.io/webmcp/) tools a page exposes. A page can declare callable actions to an in-browser agent through `document.modelContext` (`getTools()` / `executeTool()`); `mcp list` reads them and `mcp call` invokes one — so you can call a named action instead of driving the UI blind.

`mcp list` distinguishes three states: **native** WebMCP (a browser-provided `document.modelContext`), a **polyfilled** one (provided by a page script), and **absent**. When absent it fails loudly with the Chrome flags that enable native WebMCP. One tool runs at a single point in time; WebMCP has no cross-navigation tool responses, so if a tool triggers a client-side navigation, re-run `mcp list` on the new view. Any guidance the tool returns (e.g. a hint toward the next tool) is part of its result.

Native WebMCP is behind Chrome flags; start the session with them:

```bash theme={null}
sightmap browser start \
  --chrome-flag=--enable-blink-features=ModelContext,ModelContextTesting \
  --chrome-flag=--enable-features=DevToolsWebMCPSupport
```

| Command           | Flags                                  | Description                                                                                                                                                                                                                    |
| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mcp list`        | `--json`                               | Enumerate exposed tools (name, description, input schema). `--json` emits the full schemas.                                                                                                                                    |
| `mcp call <tool>` | `--args JSON`, `--param k=v`, `--json` | Invoke a tool via `executeTool` and print its result. Supply arguments as a JSON object (`--args`) and/or repeatable `--param key=value` pairs (each value parsed as JSON when possible, else a string) layered over `--args`. |

Tools return the standard WebMCP `CallToolResult` envelope (`{ content, isError }`). `mcp call` unwraps it — rendering the text/structured content (and any guidance the tool includes) as itself rather than a stringified blob — and **exits non-zero when the tool reports `isError`**, so it is scriptable. `--json` prints the raw envelope verbatim.

```bash theme={null}
sightmap browser mcp list
# WebMCP (polyfilled) — 1 tool(s):
#   search — Search flights by route

sightmap browser mcp call search --args '{"query": "ATL to LHR"}'
sightmap browser mcp call search --param query="ATL to LHR"   # equivalent
```

Both accept `--addr` and `--tab` like the other page commands.

***

### `browser clear-storage`

Clears all cookies, including `httpOnly` cookies, and clears storage for one origin. Origin storage includes localStorage, IndexedDB, service workers, and caches.

| Flag       | Default              | Description                   |
| ---------- | -------------------- | ----------------------------- |
| `--addr`   | `localhost:7892`     | CDP address                   |
| `--tab`    | the lone content tab | Target tab ID                 |
| `--origin` | current page origin  | Origin whose storage to clear |

```bash theme={null}
sightmap browser clear-storage
```

```text theme={null}
clear-storage: ✓ httpOnly cookies cleared
clear-storage: ✓ origin storage cleared (https://shop.example.com)
clear-storage: done — navigate to homepage and wait before accessing protected pages
```

## Typical flow

<Steps>
  <Step title="Install the browser once">
    `sightmap browser install` downloads Chrome for Testing to `~/.sightmap/browsers/`.
  </Step>

  <Step title="Start the session">
    From the site directory, run `sightmap browser start`. Note the `--addr` and `--tab` values it prints.
  </Step>

  <Step title="Check health">
    `sightmap browser status` confirms `● running` and lists open tabs.
  </Step>

  <Step title="Navigate and work">
    `sightmap browser navigate 'https://...'`, then capture and interact ([Capturing pages](/cli/capture), [Page interaction](/cli/interaction)).
  </Step>

  <Step title="Stop when done">
    Ctrl-C in the `start` terminal, or `sightmap browser stop` from anywhere in the site directory.
  </Step>
</Steps>