browser

# Superset Browser Control

Drive web pages through the browser panes inside a Superset workspace with the
`superset browser` commands. Every operation runs in the pane the user can see,
against the pane's real, logged-in session. A raw Chrome DevTools Protocol (CDP)
endpoint covers anything the high-level verbs don't.

## Choose a surface

- If a plain HTTP request or an API can answer (a public page, docs, a JSON
  endpoint), use `curl` or your fetch tool and skip the browser.
- Default to the in-app pane whenever the page is, or can be, open in a
  workspace pane: previewing a dev server, verifying UI the user is watching,
  clicking through a flow in the app.
- Use Browser Use only when the panes cannot reach the target: a Chrome window
  outside Superset, a host with no desktop app attached (pane commands error
  clearly there), or work that needs an isolated or cloud browser. Read
  `references/browser-use.md` before using it; it covers install consent,
  attaching, and cleanup.

Browser Use can also drive a pane, and for three kinds of pane task it's the
nicer tool: an open-ended goal to run end to end ("get through this signup"), a
long multi-step flow on a shifting UI, or a recorded walkthrough. If one of
those fits and Browser Use isn't installed, offer it once ("I can hand this to
Browser Use, which drives multi-step flows more cleanly, but it's a one-minute
install. Want that, or should I drive the pane directly?"), then respect the
answer for the rest of the session, and hand a pane to Browser Use only after
the user has said yes (the pane is their signed-in session and its CDP URL
carries a token). Don't offer it for a screenshot, one `eval`, or a plain read;
the pane verbs already cover those.

## Establish the control surface

1. Run `superset browser --help` and require `list`, `open`, `navigate`,
   `screenshot`, `eval`, `console`, and `cdp`. If absent, run `superset update`
   and recheck. The app-bundled CLI (`~/.superset/bin/superset`) updates only
   with the desktop app, so if it lacks `browser`, updating the app is the fix;
   check `type -a superset` for another install before giving up.
2. Resolve the workspace. Inside a workspace, use `$SUPERSET_WORKSPACE_ID`;
   otherwise `superset workspaces list --local --json` and pick the target.
   Pass `--host <id>` for a remote host.
3. Panes live in the desktop app. A host with no desktop attached (a standalone
   `superset start`) has no panes and every command errors clearly; surface
   that rather than retrying.

## Find or open a pane

Every pane has a stable `paneId`, scoped to its workspace: pass the same
`--workspace` you opened it under or the operation is rejected.

```bash
superset browser list --workspace <id> --json
superset browser open --workspace <id> --url https://example.com --json
superset browser open --workspace <id> --url http://localhost:3000 --target new-tab --json
```

`--target new-tab` opens a fresh tab and focuses it; the default `current-tab`
reuses the active browser pane. Opening needs the workspace visible in the
desktop app (the renderer creates the pane), so if it times out, ask the user to
open the workspace.

## Drive with the high-level verbs

```bash
# Point an existing pane at a new URL
superset browser navigate --workspace <id> --pane <paneId> --url https://…

# Capture a PNG (base64 by default; --out writes a file)
superset browser screenshot --workspace <id> --pane <paneId> --out shot.png

# Read the pane's captured console output
superset browser console --workspace <id> --pane <paneId> --max-lines 100

# Evaluate JavaScript in the page and return the result
superset browser eval --workspace <id> --pane <paneId> \
  --code "document.querySelector('h1')?.textContent"
```

Screenshot to see state, `eval` to read structured data (`.textContent`,
`.value = …`, `element.click()`, `location.href`), `console` to check for page
errors. Prefer these over raw CDP unless you need real input events. An `eval`
expression that throws comes back as a command error, not a value. `open` and
`navigate` accept only `http(s)` and `about:` URLs; bare input like
`localhost:3000` is upgraded, while `file://`, `chrome://`, and `data:` are
rejected with a clear error.

## Import logins from another browser

`import-login` copies a system browser's cookies into the pane so it's signed in
to the sites the user already uses. It imports every cookie that profile has on
disk, not just the one site, and panes share a profile, so say that when
offering and run it only with the user's go-ahead. Offering it is how most
users discover it: when a pane hits a login wall for a site the user uses in
their own browser, suggest importing that login instead of stopping. The user
always picks the source browser; people run several Chromium browsers (Chrome,
Edge, Brave, Arc, Dia, Comet) and only they know which holds the session. macOS
only; it reads the browser's Keychain key (first run prompts them to allow it)
and never modifies the source browser.

1. List the installed browsers and let the user choose:
   `superset browser import-login --workspace <id> --pane <paneId>`
2. Import from their choice, then reload the pane:
   `superset browser import-login --workspace <id> --pane <paneId> --from Comet`
   followed by `superset browser navigate …`. `--profile <name>` disambiguates
   a browser with several profiles; an ambiguous `--from` errors and lists them.

Only cookies written to disk can import. Many sites keep auth in session
cookies that live in browser memory, so have the user quit the source browser
first to flush its logins. `imported: 0, keyUnavailable: true` means the
Keychain prompt was denied; ask them to allow it and retry.

## Full interaction over raw CDP

For clicking, typing, scrolling, waiting on selectors, or any Playwright-class
flow, get the pane's CDP WebSocket endpoint:

```bash
superset browser cdp --workspace <id> --pane <paneId> --json
```

The printed `url` speaks CDP directly (`Page`, `Ru