Getting Started

Installation

Install the Python package and the Chromium browser:

pip install brow-cli
brow setup

Verify the installation:

brow --help

Updating

pip install --upgrade brow-cli updates the CLI itself. To pick up a newer patchright and the Chromium build it drives:

brow setup --upgrade

This upgrades the patchright pip package first, then installs the Chromium build that new version expects — running brow setup again on its own would just re-fetch the build for whatever version was already pinned, not actually upgrade anything. It also stops a running daemon, since it already imported the old patchright in memory and won’t pick up the upgrade until it restarts.

Configuration

brow reads a small set of environment variables:

Variable	Default	Description
`BROW_HOME`	`~/.brow`	Data directory (profiles, states, screenshots)
`BROW_PORT`	`19987`	Daemon HTTP port
`BROW_MAX_SESSIONS`	`10`	Maximum concurrent browser sessions
`BROW_NO_UPDATE_CHECK`	unset	Set to disable the update-available check below

Update notices

Most commands check once a day (cached in ~/.brow/update_check.json) whether a newer brow-cli is on PyPI, and print a one-line notice to stderr if so:

[brow] brow 1.3.0 is available (you have 1.2.0). Update with: pip install --upgrade brow-cli

The check has a short timeout and never fails or blocks a command — if PyPI is unreachable it just retries sooner (hourly instead of daily) and stays silent otherwise. Set BROW_NO_UPDATE_CHECK=1 to disable it entirely, e.g. for offline or sandboxed environments.

Your first session

Headless (default)

brow session new          # → 1
brow navigate -s 1 "https://example.com"
brow snapshot -s 1
brow session delete 1

Headed (visible browser)

Add --headed to see the Chromium window. Useful for debugging and for sites that block headless browsers:

brow session new --headed
brow navigate -s 1 "https://example.com"
brow session delete 1

The daemon

brow runs a local FastAPI daemon on port 19987. It starts automatically on the first command that needs it — you never have to start it manually.

brow daemon status          # check if running
brow daemon stop            # stop it
brow daemon start --wait    # start and block until ready

The daemon survives individual CLI invocations. Sessions you create persist until you delete them or stop the daemon.

Selectors

brow uses Playwright’s selector syntax. The most useful forms:

Selector	Example
CSS	`#submit`, `button.primary`, `input[type="email"]`
Text	`text=Sign In`
Role	`role=button[name="Save"]`
Ref (from snapshot)	`--ref 15`

The snapshot command annotates interactive elements with a numeric ref. You can use --ref N instead of a selector for any click/fill/select command.