CLI and sessions

blop-browser keeps browser state in a local daemon between commands. A named session preserves tabs, cookies, action history, and semantic references until you close it or the daemon reaches its idle timeout.

Configure a browser

Use Chromium for deterministic testing of applications you control. Save a mode non-interactively with one of these commands:

blop-browser config --mode chromium-headless
blop-browser config --mode chromium-headed
blop-browser config --mode chrome-cdp \
  --cdp-endpoint http://127.0.0.1:9222
blop-browser config --mode camoufox-headless
blop-browser config --mode camoufox-headed

Camoufox is an optional third-party Firefox-derived browser. Install it only when a site rejects automated Chromium traffic:

blop-browser install camoufox

Use named sessions

Pass the same session name to each command to keep one workflow isolated from other browser work:

blop-browser --session checkout open https://example.com
blop-browser --session checkout snapshot
blop-browser --session checkout click e6
blop-browser --session checkout close

Session names contain 1 to 64 letters, digits, underscores, or hyphens.

Use concise commands

The concise interface maps common operations to native tools:

Command	Operation
open URL	Navigate the active page
snapshot	Read visible text, semantic controls, and ARIA fallback data
click TARGET	Click a semantic reference or structured target
type TARGET TEXT	Fill a field, with optional --submit
expect-text TEXT	Retry until visible text appears
screenshot NAME	Save bounded visual evidence
finish STATUS REASON	Record the final workflow outcome

Call any native tool

List the available tools and inspect their exact JSON Schema before calling an unfamiliar operation:

blop-browser tools
blop-browser describe browser_click
blop-browser call browser_click \
  --input '{"target":{"ref":"e1"}}'

Add --json when another program consumes the result. Successful calls return an ok: true envelope; failures return ok: false and set a nonzero exit code.

Attach to an existing Chrome profile

Chrome DevTools Protocol (CDP) mode reuses an existing profile, cookies, and tabs. Start Chrome on a localhost-only debugging endpoint with a dedicated profile directory:

google-chrome \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/blop-chrome \
  about:blank

Attach a named session and navigate the selected tab:

blop-browser --session chrome \
  --cdp-endpoint http://127.0.0.1:9222 snapshot
blop-browser --session chrome open https://example.com
blop-browser --session chrome close

close disconnects the harness without closing the external Chrome process.

Caution

A CDP endpoint grants control over its Chrome profile. Keep it on localhost and don’t expose it to an untrusted network.

Configure with environment variables

Use environment variables when a host needs ephemeral configuration:

Variable	Purpose
BLOP_BROWSER_SESSION	Select the session name
BLOP_BROWSER	Select chromium or camoufox
BLOP_BROWSER_HEADLESS	Set to 0 for headed mode
BLOP_BROWSER_CDP_ENDPOINT	Attach to an HTTP, HTTPS, WS, or WSS CDP endpoint
BLOP_BROWSER_EXECUTABLE_PATH	Override the Chrome or Chromium executable
BLOP_BROWSER_IDLE_TIMEOUT_MS	Set the daemon idle timeout
BLOP_BROWSER_RUNTIME_DIR	Override the local daemon and artifact directory

Next steps

Read the TypeScript API when your host needs direct tool objects, or review the security model before sharing browser access.