@voluminis/browser-cli (br)

A fork of @browsemake/browser-cli that can drive your real, installed Chrome (or Edge) against a persistent, logged-in profile — so br can reuse your existing cookies, sessions, history and bookmarks instead of a throwaway Chromium profile.

br is a command-line browser-automation tool designed to be driven by an LLM agent (Claude Code, Gemini CLI, ChatGPT, …) or by a human directly. It runs a background daemon that controls a browser and exposes small, LLM-friendly commands (goto, click, fill, screenshot, view-tree, …).

Why this fork exists

Upstream br always launches patchright's bundled Chromium in a profile that br manages itself:

• br start (the default instance) creates a brand-new throwaway profile in your temp dir on every start — so anything you log into is gone the next time you start it.
• br -n <name> start (a named instance) does persist, under ~/.config/br/profiles/<name> — but it's still bundled Chromium, so it can't see your real Chrome's logins or history.

And you can't simply copy your real Chrome profile into it: since Chrome 127, cookies are protected by App-Bound Encryption (ABE), so cookies copied out of Chrome (or opened by a different browser) won't decrypt and you end up logged out.

This fork adds the missing capability: point br at a real installed browser and a real profile directory, so genuine Chrome decrypts its own cookies and everything just works — logged in, with your history, persisting across restarts.

What this fork adds

Three new br start options (wired through to launchPersistentContext):

| Option | What it does | | --- | --- | | --channel <channel> | Launch a real installed browser (chrome, msedge, chrome-beta, …) instead of bundled Chromium. | | --user-data-dir <path> | Use an existing profile root (e.g. a Chrome User Data dir, or a copy of one) instead of the managed location. | | --profile-directory <name> | Pick a sub-profile inside that dir (e.g. Default, Profile 1). |

Plus: when --channel is set, the daemon's startup health-check timeout is raised from 5s to 45s, because real Chrome with a large profile cold-starts more slowly than bundled Chromium.

Everything else is upstream @browsemake/[email protected] (patchright-based), unchanged.

Install

npm install -g @voluminis/browser-cli

For bundled Chromium mode (the upstream default) you also need the browser once:

npx patchright install chromium

For real-Chrome mode (--channel chrome) you don't need that — it uses the Google Chrome you already have installed.

Everyday commands

Drive your real Chrome with a persistent, logged-in profile

Only start needs the flags; every later command just targets the instance by name.

# Start a named instance backed by a real Chrome profile.
# (Point --user-data-dir at a Chrome "User Data" root; --profile-directory selects the profile.)
br -n chrome start \
  --channel chrome \
  --user-data-dir "$HOME/.config/br/chrome-profile" \
  --profile-directory "Profile 1"

# Then just use the instance:
br -n chrome goto https://mail.google.com
br -n chrome screenshot -o page.png
br -n chrome extract-text
br -n chrome view-tree

First-time login: because of ABE (see above), a copied profile keeps your history/bookmarks but not your cookies — so log into your accounts once in the real-Chrome window br opens. That login is written back in place and persists from then on. If you instead point --user-data-dir at your live Chrome User Data (with Chrome closed), your existing logins work immediately.

Bundled Chromium (upstream behavior)

br start                      # ephemeral profile (throwaway each start)
br -n work start              # persistent profile at ~/.config/br/profiles/work
br goto https://example.com

Common actions

br goto https://example.com
br click "button.submit"      # CSS selector, XPath, or a numeric id from `br view-tree`
br fill "input[name='q']" "search text"
br press Enter
br view-tree                  # accessibility + DOM tree (LLM-friendly)
br view-html
br tabs / br switch-tab 1
br history                    # action history for replay

Secrets never need to be passed to the LLM:

MY_SECRET="…" br fill-secret "input[name='password']" MY_SECRET

Stopping cleanly (important on Windows)

br stop hard-kills the daemon on Windows — it does not flush the browser's in-memory cookies to disk, so a login you just made can be lost. To stop cleanly (which runs the browser's graceful close and flushes cookies), POST to the daemon's shutdown endpoint using the port from br ls:

# port comes from `br ls`
curl -X POST http://127.0.0.1:3030/shutdown
# PowerShell:
Invoke-RestMethod -Method Post http://127.0.0.1:3030/shutdown

Notes / gotchas

• Headless + real Chrome: modern Google Chrome tends to crash in old headless mode (exit code 21). Use headed (the default) with --channel chrome. Bundled Chromium still supports --headless fine.
• One instance per user-data-dir: you can't drive a profile that another Chrome is currently using (single-instance lock). Use a copy of the profile (independent of your daily Chrome) or close Chrome first.
• Profile persistence rules: | Mode | Profile location | Persists? | | --- | --- | --- | | br start | %TEMP%/$TMPDIR br_user_data_default_<timestamp> | ❌ new each start | | br -n <name> start | ~/.config/br/profiles/<name> | ✅ | | --user-data-dir <path> | wherever you point it | ✅ |

Credits & license

Fork of browsemake/browser-cli by halfjuice. Licensed under MIT (original copyright retained in LICENSE). All upstream functionality and credit belong to the original authors; this fork only adds the real-browser / persistent-profile options described above.