browser-cli/README.md

browser-cli

Control your real, running browser from the terminal, Python SDK, or a trusted remote client — no headless browser, no Playwright, no virtual display. Your actual open tabs, windows, and tab groups respond to your commands.

---

What it does

You have 40 tabs open. You want to close all the duplicates, group the GitHub ones, save your session before a meeting, and open a few URLs into a specific group — all from a script. That is what browser-cli is for.

It works by pairing a small browser extension with a Python package that provides both a CLI and SDK. The extension has full access to your browser's tabs, windows, groups, and page DOM. The CLI and SDK talk to it in real time over a local IPC channel, or through the optional authenticated TCP remote bridge.

---

How it works

terminal / python script / remote client
        │
        │  Local IPC  (Unix socket on Linux/macOS, named pipe on Windows)
        │  or TCP remote bridge  (Ed25519 auth, optional compression)
        ▼
  Native Messaging Host  (Python process, launched by the browser)
        │
        │  Native Messaging Protocol  (stdin/stdout, 4-byte length prefix + JSON)
        ▼
  Browser Extension  (background worker/page)
        │
        │  extension APIs
        ▼
  Your running browser

1. The extension calls chrome.runtime.connectNative('com.browsercli.host') on startup.
2. The browser launches the native host Python process (registered in the OS).
3. The native host opens a local IPC endpoint for the CLI.
4. CLI commands connect to that socket, send a JSON command, and wait for the result.
5. The native host relays the command to the extension via stdout, receives the result via stdin, and sends it back to the CLI.

No local server needs to be running beforehand. The browser manages the native host's lifecycle. For cross-machine control, browser-cli serve starts an explicit TCP listener protected by Ed25519 public-key authentication unless you opt out with --no-auth.

Message format

Every command is a JSON object:

{ "id": "uuid", "command": "tabs.list", "args": {} }

Every response:

{ "id": "uuid", "success": true, "data": [...] }

---

Installation

Requirements: Python 3.10+, uv, Chrome, Chromium, Brave, Edge, Vivaldi, or Firefox

Install with uv

Install the CLI from PyPI as a uv tool:

uv tool install real-browser-cli
browser-cli --version
browser-cli install brave   # or: chrome, chromium, edge, vivaldi, firefox

The PyPI package is named real-browser-cli; the installed command is still browser-cli.

For better remote-response compression, install the optional fast extra:

uv tool install "real-browser-cli[fast]"

To upgrade later:

uv tool upgrade real-browser-cli

Install from source

git clone <repo>
cd browser-cli
uv sync
uv run browser-cli install brave   # or: chrome, chromium, edge, vivaldi, firefox

The install command will:

1. Ask you to load the browser-specific extension package
2. Show the stable extension ID used by that browser family
3. Write the native messaging manifest to your OS so the browser can find the host
4. Copy the native host into an internal libexec directory and create a small wrapper outside your PATH

After install, fully restart your browser (Quit and reopen — not just close the window). The extension will connect to the native host automatically on startup.

Only the browser-cli command needs to be on your PATH. The browser launches the native host wrapper directly from its absolute path in the native messaging manifest, and that wrapper imports the installed browser_cli.native.host entry point. On Windows the install command also registers the host in the current user's Registry for the selected browser.

---

Project structure

browser-cli/
├── browser_cli/
│   ├── __init__.py          # Public sync SDK: BrowserCLI and namespace wiring
│   ├── async_sdk.py         # AsyncBrowserCLI
│   ├── cli.py               # Click root command and native-host entry point
│   ├── client/              # send_command path, local/remote routing, message helpers
│   ├── sdk/                 # SDK namespaces: nav, tabs, groups, windows, dom, session, ...
│   ├── commands/            # CLI presentation layer over the SDK namespaces
│   ├── native/              # Browser-launched Native Messaging host + local IPC server
│   ├── remote/              # TCP remote client transport and saved endpoint registry
│   ├── serve/               # Authenticated TCP server runtime
│   ├── transport/           # JSON/msgpack response encoding and compression helpers
│   ├── markdown/            # HTML-to-Markdown extraction helpers
│   ├── auth/                # Ed25519 keys, signing, SSH-agent/YubiKey helpers, PQ KEX
│   └── models.py            # Tab, Group, BrowserCounts dataclasses
├── extension/
│   ├── manifest.json        # Chromium MV3 manifest
│   └── src/                 # TypeScript WebExtension source
│       ├── index.ts         # Background/service-worker bundle entry
│       ├── content-dispatch.ts
│       ├── commands/        # Browser-side command implementations
│       ├── content/         # DOM/extract/Markdown logic injected into pages
│       └── core/            # Shared extension helpers
├── examples/                # Python and shell walkthroughs
├── scripts/                 # Packaging and release helper scripts
├── tests/                   # pytest suite
├── package.json             # Extension build/test/package scripts
├── pyproject.toml           # Python package metadata
└── uv.lock                  # locked Python dependencies

---

CLI reference

During source development, commands are usually run as uv run browser-cli [--browser ALIAS] <command>. After tool installation, use browser-cli ... directly. Add --remote HOST[:PORT] and optionally --key PATH to target a browser exposed by browser-cli serve.

If exactly one browser instance is connected, commands auto-target it. Use --browser ALIAS when multiple browser instances are connected. tabs list, tabs count, groups list, groups count, windows list, and session list aggregate across all active browsers when --browser is omitted; in that mode they show the source browser alias or UUID. When local and saved remote browsers are mixed, tables group rows by source (local or the remote endpoint) and indent the browser profile below that group. You can inspect active instances with browser-cli clients and assign a persistent profile alias from inside the target browser with browser-cli clients rename --browser <current-alias> <new-alias>. Closed browsers are removed from the client registry automatically.

Important: profile aliases are browser-instance aliases, not window aliases. Window aliases created with windows rename are only for targeting windows in commands like nav open --window work. If a browser instance has no explicit profile alias set, the native host gives it a generated UUID alias so multiple unaliased browsers stay distinct.

Navigation (nav)

# Open a URL (no focus stealing by default)
browser-cli nav open https://example.com
browser-cli nav open https://example.com --focus            # bring opened tab/window forward
browser-cli nav open https://example.com --window work      # into a named window
browser-cli nav open https://example.com --group research   # into a tab group (name or ID)

# Reload
browser-cli nav reload                  # reload active tab
browser-cli nav reload 1234             # reload tab by ID
browser-cli nav hard-reload             # bypass cache

# Navigate history
browser-cli nav back
browser-cli nav forward 1234            # forward in specific tab

# Jump to a tab by URL pattern
browser-cli nav focus github            # focuses first tab whose URL contains "github"

Search

Each search command opens the search results in your browser using the same flags as nav open.

browser-cli search google openai api
browser-cli search brave rust iterators
browser-cli search ddg tab groups --window work
browser-cli search youtube browser automation
browser-cli search yt lo fi
browser-cli search spotify aphex twin
browser-cli search amazon mechanical keyboard
browser-cli search ecosia native messaging
browser-cli search furaffinity dragons
browser-cli search fa dragons
browser-cli search bing browser cli
browser-cli search github browser-cli
browser-cli search wikipedia native messaging
browser-cli search wiki native messaging
browser-cli search reddit chrome extensions
browser-cli search stackoverflow click choices
browser-cli search so click choices

Tabs

browser-cli tabs list                        # list all open tabs (all windows)
browser-cli tabs count                       # count all tabs
browser-cli tabs count youtube               # count tabs matching URL pattern
browser-cli tabs filter youtube              # list tabs matching URL pattern
browser-cli tabs query "pull request"        # search tabs by URL or title

browser-cli tabs active 1234                 # switch browser focus to tab
browser-cli tabs html                        # print full HTML of active tab
browser-cli tabs html 1234                   # print HTML of specific tab

browser-cli tabs close 1234                  # close specific tab
browser-cli tabs close --inactive            # close all inactive tabs
browser-cli tabs close --duplicates          # close duplicate URLs (keep first)
browser-cli tabs dedupe                      # same as close --duplicates

browser-cli tabs move 1234 --window 2        # move tab to another window
browser-cli tabs move 1234 --group 42        # move tab into a group

browser-cli tabs sort --by domain            # sort tabs within each window
browser-cli tabs sort --by title
browser-cli tabs sort --by time

browser-cli tabs merge-windows               # pull all tabs into the current window

Tab groups

browser-cli groups list                      # list all tab groups
browser-cli groups count                     # count groups
browser-cli groups query "work"              # search groups by name
browser-cli groups tabs 42                   # list tabs inside group ID 42

browser-cli groups create "research"         # create a new group
browser-cli groups add-tab research          # open a blank tab in the group
browser-cli groups add-tab research https://example.com  # open URL in the group
browser-cli groups add-tab 42 https://example.com        # by group ID

browser-cli groups close 42                  # ungroup the group
browser-cli groups move research --forward   # move group right
browser-cli groups move research --right     # same as --forward
browser-cli groups move research -r          # short right alias
browser-cli groups move 42 --backward        # move group left
browser-cli groups move 42 --left            # same as --backward
browser-cli groups move 42 -l                # short left alias

Windows

browser-cli windows list                     # list all windows
browser-cli windows open                     # open a new window
browser-cli windows open https://example.com # open a new window on a URL
browser-cli windows rename 1 "work"          # give a window a local alias
browser-cli windows close 1                  # close a window

DOM

These commands run on the active tab. The tab must be on a regular http:// or https:// page — not a browser internal page like brave://newtab.

browser-cli dom query "h1"                   # return elements matching CSS selector
browser-cli dom text "h1"                    # get text content of matching elements
browser-cli dom attr "a" href                # get attribute value from elements
browser-cli dom exists ".modal-banner"       # exits 0 if found, 1 if not
browser-cli dom click ".accept-button"       # click an element
browser-cli dom type "#search" "hello"       # type text into an input

Extract

browser-cli extract links                    # all <a href> links on the page
browser-cli extract images                   # all <img> tags (src + alt)
browser-cli extract text                     # all visible text (innerText)
browser-cli extract json "#data"             # parse JSON inside a CSS selector
browser-cli extract html                     # full HTML of the active tab
browser-cli extract markdown                 # main page content as Markdown
browser-cli extract markdown --selector "article"   # specific DOM subtree as Markdown

Sessions

A session is a snapshot of all open tab URLs, stored inside the extension via chrome.storage.local. Sessions survive browser restarts but are lost if the extension is uninstalled or extension data is cleared.

browser-cli session save before-meeting      # save current tabs as a named session
browser-cli session load before-meeting      # reopen all saved tabs
browser-cli session list                     # list all saved sessions (name, tab count, date)
browser-cli session remove before-meeting    # delete a saved session
browser-cli session diff session-a session-b # show which URLs were added / removed
browser-cli session auto-save on             # auto-save after every tab change
browser-cli session auto-save off

Misc

browser-cli clients                          # show connected browser info from the registry
browser-cli clients rename --browser abcd1234 work  # rename one connected browser instance
browser-cli --browser abcd1234 clients rename work  # equivalent global form
browser-cli install brave                    # (re)register the native host
browser-cli completion zsh                   # print setup instructions
browser-cli completion zsh --script          # output raw completion script

Remote control, auth, and gateways

# On the machine with the browser
browser-cli auth keygen --output ~/.config/browser-cli/client.key
PUBKEY=$(browser-cli auth show --key ~/.config/browser-cli/client.key | tail -n1)
browser-cli auth trust "$PUBKEY"
browser-cli serve --host 0.0.0.0 --port 8765 --authorized-keys ~/.config/browser-cli/authorized_keys

# From another machine
browser-cli --remote browser-host.example:8765 --key ~/.config/browser-cli/client.key tabs list
browser-cli remote trust browser-host.example:8765 ~/.config/browser-cli/client.key
browser-cli --remote browser-host.example:8765 clients

# Local HTTP JSON gateway for small integrations
browser-cli serve-http --port 8766
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8766/tabs

Remote auth uses Ed25519 challenge/response. --remote domains default to port 443; explicit host:port endpoints are also supported. Saved remote endpoints participate in aggregate list/count commands, where output is grouped by endpoint.

---

Python SDK

from browser_cli import AsyncBrowserCLI, BrowserCLI

b = BrowserCLI()

Commands are grouped into namespaces on the client (b.tabs, b.dom, b.session, ...). Each sync call blocks until the browser responds and returns the data directly as a Python object. Create BrowserCLI(remote="host:8765", key="client.key") to target a remote server. For asyncio programs, AsyncBrowserCLI exposes the same namespaces as native awaitable methods over async Unix/TCP transport.

# Navigation  ── b.nav
b.nav.open("https://example.com")
b.nav.open("https://example.com", background=True)
b.nav.open("https://example.com", window="work")
b.nav.reload()
b.nav.hard_reload()
b.nav.back()
b.nav.forward(tab_id=1234)
b.nav.focus("github")
b.nav.to(1234, "https://example.com")   # navigate a specific tab in place
b.nav.search("google", "python asyncio")

# Tabs  ── b.tabs
tabs = b.tabs.list()          # list[Tab]; in multi-browser mode each tab.browser is set
tab = b.tabs.open("https://example.com")              # returns a bound Tab object
tab = b.tabs.open("https://example.com", wait=True, timeout=10)
active = b.tabs.active()      # active Tab object
tab = b.tabs.get(1234)        # tab by ID
tab = b.tabs.first("github")  # first matching tab or None
b.tabs.activate(1234)
b.tabs.close(1234)
b.tabs.close(tab_ids=[1, 2, 3])  # close many in one round-trip (IDs or Tab objects)
b.tabs.close_inactive()
b.tabs.close_duplicates()
b.tabs.filter("youtube")      # list of matching tabs
b.tabs.query("pull request")
counts = b.tabs.count("github")  # int, or BrowserCounts(total=..., by_browser=...) in multi-browser mode
html = b.tabs.html()          # full HTML string of active tab
b.tabs.sort(by="domain")
b.tabs.merge_windows()
b.tabs.dedupe()

# Bound Tab helpers
tab = b.tabs.active()
tab.pin()
tab.screenshot()
tab.refresh()
tab.wait_for_load(timeout=10)
tab.watch_url(r"/done$")

# Tab groups  ── b.groups
groups = b.groups.list()      # list[Group]; in multi-browser mode each group.browser is set
b.groups.create("research")   # creates group, returns Group
b.groups.close(42)
b.groups.tabs(42)             # tabs inside a group
b.groups.add_tab(42, "https://example.com")
b.groups.count()              # int, or BrowserCounts(...) in multi-browser mode

# Windows  ── b.windows
windows = b.windows.list()    # in multi-browser mode each dict has a "browser" key
b.windows.rename(1, "work")
b.windows.open()
b.windows.open("https://example.com")
b.windows.close(1)

# DOM  ── b.dom  (active tab must be http/https)
elements = b.dom.query("h2")           # list of { tag, text, attrs }
texts = b.dom.text(".article p")       # list of strings
attrs = b.dom.attr("a", "href")        # list of strings
exists = b.dom.exists(".modal-banner") # bool
b.dom.click(".accept-button")
b.dom.type("#search", "hello world")
b.dom.wait_for("#results", visible=True, timeout=10)
b.dom.eval("document.title")

# Extract  ── b.extract
links = b.extract.links()     # list of { text, href }
images = b.extract.images()   # list of { alt, src }
text = b.extract.text()       # string
data = b.extract.json("#app-data")  # parsed Python object
md = b.extract.markdown("article")

# Page / storage
info = b.page.info()
b.storage.set("token", "abc")
val = b.storage.get("token")

# Sessions  ── b.session
b.session.save("before-meeting")
b.session.load("before-meeting")
sessions = b.session.list()   # [{ name, tabs, savedAt }, ...]
b.session.remove("before-meeting")
diff = b.session.diff("session-a", "session-b")
# diff = { "added": [...urls], "removed": [...urls] }
b.session.auto_save(True)

# Performance + extension
b.perf.status()
b.perf.set_profile("gentle")
b.extension.reload()

# Workflow decorators  ── b.decorators
@b.decorators.new_tab("https://example.com", wait=True, close=True)
def scrape(*, tab):
    return b.extract.markdown("article")

@b.decorators.wait_for_selector("#ready", visible=True)
def run_after_page_ready():
    return b.dom.text("#ready")

@b.decorators.performance_profile("ultra")
def restore_big_session():
    return b.session.load("work", lazy=True)

@b.decorators.retry(times=3, delay=1)
@b.decorators.save_session_before("before-risky-step")
def risky_workflow():
    b.tabs.close_duplicates()

# Async SDK: same namespaces, native awaitable methods
async def async_example():
    ab = AsyncBrowserCLI()
    tabs = await ab.tabs.list()

    @ab.decorators.new_tab("https://example.com", wait=True, close=True)
    async def scrape(*, tab):
        return await ab.extract.markdown("article")

    return tabs, await scrape()

# Misc
clients = b.clients()
raw = b.command("tabs.count", {"pattern": "github"})  # escape hatch for raw commands

Error handling

from browser_cli import BrowserCLI, BrowserNotConnected

b = BrowserCLI()
try:
    tabs = b.tabs.list()
except BrowserNotConnected:
    print("Browser is not running or extension is not loaded")
except RuntimeError as e:
    print(f"Browser returned an error: {e}")

from browser_cli import BrowserCLI, BrowserCounts

b = BrowserCLI()

tabs = b.tabs.list()
for tab in tabs:
    print(tab.browser, tab.title)

counts = b.tabs.count()
if isinstance(counts, BrowserCounts):
    print(counts.total)
    print(counts.by_browser)
    print(counts.browser_groups)  # e.g. {"local:work": "local", "remote:work": "remote"}

---

Example scripts

See examples/demo.py (Python) and examples/demo.sh (Bash) for full walkthroughs covering tabs, groups, DOM extraction, and session management.

uv run python examples/demo.py
bash examples/demo.sh

---

Development

npm ci
npm run check:extension   # type-check, build extension bundles, syntax-check bundle
uv run pytest -q

On NixOS or hosts without global Node/npm:

nix-shell   # automatically runs npm ci when node_modules is missing/outdated
npm run check:extension

The extension source lives in extension/src/. extension/background.js and extension/content-dispatch.js are generated and ignored by git. Run npm run build:extension before using Load unpacked with extension/. On NixOS, use nix-shell first if npm is not installed globally.

Packaging:

just publish                                 # build to /tmp/dist-browser-cli and publish with .env credentials
npm run package:extension                    # testing/unpacked zip, keeps manifest.key for stable Chromium native-messaging ID
npm run package:extension:webstore           # Chrome Web Store zip, strips manifest.key
npm run package:extension:webstore:verified  # Chrome Web Store CRX signed for verified uploads
npm run package:extension:firefox            # Firefox zip, strips manifest.key and Firefox-incompatible permissions

Chrome Web Store rejects manifest.key, so upload the *-webstore-* zip from dist/. For verified CRX uploads, create a dedicated RSA upload key once and protect it with your GPG key:

scripts/setup_verified_crx_key.sh --recipient '<your GPG key id or email>'
# Add the generated public key in Chrome Developer Dashboard -> Package -> Verified uploads.
npm run package:extension:webstore:verified

The verified-upload private key is not a GPG key; Chrome requires an RSA CRX signing key. GPG is used here to encrypt that RSA private key at rest. The signed *.crx from dist/ is the upload artifact after verified uploads are enabled. For Firefox, use the *-firefox-* zip.

For Firefox temporary testing via about:debugging#/runtime/this-firefox, run npm run package:extension:firefox first and load dist/extension-package-firefox/manifest.json. Do not load extension/manifest.json directly: it is the Chromium MV3 manifest and Firefox currently rejects background.service_worker for temporary add-ons.

---

Limitations

• Browser internal pages (chrome://, brave://, edge://, about:) cannot be scripted. DOM and extract commands only work on regular http:// and https:// pages.
• Multiple browser instances can be auto-distinguished, but generated aliases are temporary. Unaliased browsers get UUID aliases from the native host, which avoids collisions but is less ergonomic than setting a stable alias with browser-cli clients rename --browser <current-alias> <new-alias>.
• Supported install targets are explicit, not “all Chromium browsers”. The installer currently supports Chrome, Chromium, Brave, Edge, Vivaldi, and Firefox. Other Chromium-based browsers may use different or shared native messaging manifest locations, so they need browser-specific verification before being added safely.
• Firefox support is experimental. Basic tab/window/navigation/native-messaging support is wired, including tab-group APIs on supported Firefox versions.

---

License

PolyForm Noncommercial License 1.0.0. See LICENSE.

Commercial use is not permitted under this license. For commercial licensing, contact the project maintainer.