# CLI and sessions

> Look up blop-browser commands, options, browser modes and environment variables for persistent browser sessions.

`blop-browser` keeps a browser alive between shell calls. The first command starts a local daemon; later commands with the same session name reuse its tabs, cookies, action history and element references.

## Global options

| Option | Effect |
| --- | --- |
| `--session NAME` | Select a named session. Default `default`. Names are 1 to 64 letters, digits, underscores or hyphens. |
| `--browser chromium\|camoufox` | Browser for a new session |
| `--headless`, `--headed` | Run a new managed browser without or with a window |
| `--profile persistent\|disposable` | Keep session state until `destroy` (default), or delete it on `close` or idle shutdown |
| `--cdp-endpoint URL` | Connect to a running Chrome over CDP |
| `--attach-existing` | Allow access to an existing CDP profile. Required on the command that first attaches. |
| `--anti-bot [on\|off]` | Launch Camoufox (`on`) or Chromium (`off`, default) |
| `--json` | Print a machine-readable envelope |

Flags and environment variables override saved configuration.

## Browser commands

```bash
blop-browser --session checkout open https://example.com
blop-browser --session checkout snapshot
blop-browser --session checkout click e13
blop-browser --session checkout close
```

| Command | Effect |
| --- | --- |
| `open URL` | Navigate the active page |
| `snapshot` | Read visible text, controls with references, and ARIA fallback data |
| `click TARGET` | Click a reference or structured target |
| `type TARGET TEXT [--submit]` | Fill a field, optionally submitting it |
| `expect-text TEXT` | Retry until the text is visible; exit `1` if it never appears |
| `screenshot [NAME] [--full-page]` | Save bounded visual evidence to the session's artifact directory |
| `finish passed\|failed REASON` | Record the final outcome |
| `status` | Report the session, browser, page, safety mode and storage scope |
| `close` | Stop the browser; a persistent profile keeps its state |
| `destroy` | Close the session and delete its managed state |

## Native tool commands

```bash
blop-browser tools
blop-browser describe browser_click
blop-browser call browser_click --input '{"target":{"ref":"e13"}}' --json
```

| Command | Effect |
| --- | --- |
| `tools` | List every tool |
| `describe TOOL` | Print a tool's description and JSON Schema |
| `call TOOL --input JSON` | Call any tool |

With `--json`, success returns `{"ok": true, "result": …}`. Failure returns `{"ok": false, "error": …}` and exits nonzero.

## Setup and maintenance commands

| Command | Effect |
| --- | --- |
| `doctor [--json]` | Report available browsers, configuration and the daemon |
| `config --mode MODE` | Save the default browser mode (table in the next section) |
| `config --anti-bot on\|off` | Save the Camoufox default |
| `install camoufox` | Download Camoufox |
| `skill show`, `skill install --target agents\|claude\|opencode\|all [--scope project\|user]` | Print or install the agent skill |
| `data list`, `data delete SESSION` | List retained session data, or delete one session's data |

## Browser modes

| Mode | Browser |
| --- | --- |
| `chromium-headless` | Managed Chromium, no window. Default for agents and CI. |
| `chromium-headed` | Managed Chromium with a window |
| `chrome-cdp` | Existing Chrome, with `--cdp-endpoint URL` |
| `camoufox-headless`, `camoufox-headed` | Camoufox |

Use Chromium for deterministic testing of apps you control. Camoufox is an optional third-party Firefox-based browser; install it with `blop-browser install camoufox` only when a site you are authorised to automate rejects automated Chromium.

## Attach to an existing Chrome

Start Chrome with debugging bound to localhost and a dedicated profile, then attach:

```bash
google-chrome \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/blop-chrome
blop-browser --session chrome --attach-existing \
  --cdp-endpoint http://127.0.0.1:9222 snapshot
blop-browser --session chrome open https://example.com
blop-browser --session chrome close
```

Later commands reuse the connection. `close` disconnects without closing Chrome.

> **Caution:** A CDP endpoint controls its whole Chrome profile. Keep it on localhost and never expose it to an untrusted network.

## Environment variables

| Variable | Default | Effect |
| --- | --- | --- |
| `BLOP_BROWSER_SESSION` | `default` | Session name |
| `BLOP_BROWSER` | `chromium` | `chromium` or `camoufox` |
| `BLOP_BROWSER_HEADLESS` | `1` | `0` shows the browser window |
| `BLOP_BROWSER_CDP_ENDPOINT` | unset | HTTP, HTTPS, WS or WSS CDP endpoint; still needs `--attach-existing` |
| `BLOP_BROWSER_EXECUTABLE_PATH` | auto-detect | Chrome or Chromium executable |
| `BLOP_BROWSER_IDLE_TIMEOUT_MS` | `1800000` (30 minutes) | Daemon idle timeout |
| `BLOP_BROWSER_READ_ONLY` | unset | `1` on the command that starts a session denies clicks, typing, forms, uploads and page closing |
| `BLOP_BROWSER_RUNTIME_DIR` | OS temporary directory | Daemon state, profiles and artifacts |

The [Browser Harness README](https://github.com/blop-oss/blop-browser#configuration-reference) lists the remaining variables.