CLI and 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

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

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:

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 lists the remaining variables.