real-browser-cli 0.15.5__tar.gz → 0.16.2__tar.gz

{real_browser_cli-0.15.5 → real_browser_cli-0.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: real-browser-cli
-Version: 0.15.5
+Version: 0.16.2
 Summary: Control your real running browser from the terminal or Python SDK
 Project-URL: Homepage, https://git.yiprawr.dev/Automatisation/browser-cli
 Project-URL: Repository, https://git.yiprawr.dev/Automatisation/browser-cli
@@ -86,28 +86,30 @@ Requires-Python: >=3.10
 Requires-Dist: click>=8
 Requires-Dist: cryptography>=48
 Requires-Dist: msgpack>=1
+Requires-Dist: questionary>=2
 Requires-Dist: rich>=13
 Provides-Extra: fast
 Requires-Dist: zstandard>=0.22; extra == 'fast'
 Description-Content-Type: text/markdown
 
 # browser-cli
-Control your real, running browser from the terminal or the Python SDK — no headless browser, no Playwright, no virtual display. Your actual open tabs, windows, and tab groups respond to your commands.
+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.
+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
+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)
         │
@@ -126,7 +128,7 @@ terminal / python script
 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 server needs to be running beforehand. The browser manages the native host's lifecycle.
+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**
 
@@ -145,8 +147,10 @@ Every response:
 
 **Requirements:** Python 3.10+, [uv](https://github.com/astral-sh/uv), Chrome, Chromium, Brave, Edge, Vivaldi, or Firefox
 
+browser-cli has two parts: the **CLI / native host** (a Python package) and the **browser extension** (published on the public stores).
+
 ### Install with uv
-Once published on PyPI, install the CLI as a uv tool:
+Install the CLI from PyPI as a uv tool, then register the native host:
 
 ```sh
 uv tool install real-browser-cli
@@ -168,21 +172,31 @@ To upgrade later:
 uv tool upgrade real-browser-cli
 ```
 
+### Add the browser extension
+Install the extension from its public store listing (the `install` command prints the right link for you):
+
+- Chrome / Chromium / Brave / Edge / Vivaldi — [Chrome Web Store](https://chromewebstore.google.com/detail/browser-cli/hekaebjhbhhdbmakimmaklbblbmccahp)
+- Firefox — [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/browser-cli/)
+
+The native host manifest trusts both the published store ID and the unpacked development ID, so the store extension works out of the box. If you are hacking on the extension yourself, run `browser-cli install <browser> --dev` for the unpacked / temporary-add-on load steps instead.
+
 ### Install from source
 ```sh
 git clone <repo>
 cd browser-cli
 uv sync
-uv run browser-cli install brave   # or: chrome, chromium, edge, vivaldi, firefox
+npm ci && npm run build:extension                 # build the unpacked extension bundles
+uv run browser-cli install brave --dev            # --dev prints unpacked-load steps; or: chrome, chromium, edge, vivaldi, firefox
 ```
 
+Omit `--dev` to be pointed at the public store listing instead of loading the unpacked build.
+
 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`
+1. Write the native messaging manifest to your OS so the browser can find the host
+2. Copy the native host into an internal `libexec` directory and create a small wrapper outside your `PATH`
+3. Print the public store link for installing the extension (or, with `--dev`, the unpacked / temporary-add-on load steps)
 
-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.
+After install, add the extension from the store link above and **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.
 
@@ -193,62 +207,42 @@ Only the `browser-cli` command needs to be on your `PATH`. The browser launches
 ```text
 browser-cli/
 ├── browser_cli/
-│   ├── __init__.py        # Python SDK — BrowserCLI class and SDK entry point
-│   ├── cli.py             # Click CLI entry point
-│   ├── client/            # Client-side command routing used by CLI and SDK
-│   │   ├── core.py         # send_command and remote command routing
-│   │   ├── targets.py      # Browser target discovery and socket resolution
-│   │   ├── auth.py         # Remote auth fields and key lookup
-│   │   └── messages.py     # Request/response helpers
-│   ├── models.py          # Tab and Group helper models
-│   ├── native/            # Native messaging host internals
-│   │   ├── host.py         # Browser-launched native host entry point
-│   │   ├── local_server.py # Local CLI IPC server
-│   │   └── protocol.py     # Chrome Native Messaging framing
-│   ├── remote/            # Client-side remote browser support
-│   │   ├── transport.py    # TCP/TLS remote transport
-│   │   └── registry.py     # Saved remote endpoints/keys
-│   └── commands/
-│       ├── navigate.py    # nav open/reload/back/forward/focus
-│       ├── search.py      # search engine shortcuts
-│       ├── tabs.py        # tab management
-│       ├── groups.py      # tab group management
-│       ├── windows.py     # window management
-│       ├── dom.py         # DOM querying and interaction
-│       ├── extract.py     # content extraction
-│       └── session.py     # session save/load
+│   ├── __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      # MV3 extension manifest
-│   ├── content.js         # Content-script helpers
-│   └── src/               # TypeScript source split by command area
-│       ├── index.ts       # Builds generated extension/background.js
-│       └── content/       # Builds generated extension/content-dispatch.js
-├── examples/
-│   ├── demo.py            # Python SDK walkthrough
-│   └── demo.sh            # Bash CLI walkthrough
-├── tests/
-│   ├── conftest.py        # shared pytest fixtures
-│   ├── test_api.py
-│   ├── test_cli.py
-│   ├── test_dom.py
-│   ├── test_extract.py
-│   ├── test_groups.py
-│   ├── test_nav.py
-│   ├── test_session.py
-│   ├── test_tabs.py
-│   └── test_windows.py
-├── com.browsercli.host.json  # native messaging manifest template
-├── pyproject.toml            # package metadata and CLI entry point
-└── uv.lock                   # locked dependencies for uv
+│   ├── 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
 
-All commands are run with `uv run browser-cli [--browser ALIAS] <command>`.
+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. You can inspect the 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.
+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.
 
@@ -408,6 +402,44 @@ browser-cli completion zsh                   # print setup instructions
 browser-cli completion zsh --script          # output raw completion script
 ```
 
+### Remote control, auth, and gateways
+
+```sh
+# 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
+
+# Allow remote browser control (navigation, clicks); safe-only otherwise
+browser-cli serve --authorized-keys ~/.config/browser-cli/authorized_keys --allow-control
+
+# Per-key authorization (inline in authorized_keys) + a tighter rate limit
+browser-cli auth trust "$PUBKEY" --name ci-bot --allow-read-page --allow-control
+browser-cli serve --authorized-keys ~/.config/browser-cli/authorized_keys --rate-limit 20
+
+# 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.
+
+#### Security model
+
+- **`serve` (TCP)** authenticates every connection with an Ed25519 signature over a fresh server nonce and, for modern clients, wraps the transport in an ML-KEM-768 (post-quantum) AEAD channel. Commands are gated by a **safe-only policy by default** — even a trusted key can only run read-only status/listing commands until you open more with `--allow-read-page`, `--allow-control`, `--allow-dangerous`, or `--allow-all` (full control, including `dom.eval`/`storage.*`). `--no-auth` is rejected on non-loopback hosts.
+  - **Per-key authorization:** a key in `authorized_keys` can carry an optional `allow:` token (`<pubkey> <name> allow:read-page,control`) listing its categories (`all`, `safe`, `read-page`, `control`, `dangerous`). That key uses its own policy, overriding the server-wide `--allow-*` default; keys without a token fall back to the default. Set it with `auth trust <pubkey> --allow-control …` (works locally and over `--remote`); `auth keys` shows each key's policy.
+  - **Rate limiting:** `--rate-limit N` caps commands/second per client key (token bucket, default `100`, `0` disables) so a compromised key can't hammer the browser.
+  - **Audit logging:** request logs include the acting key (its name from `authorized_keys` plus a short pubkey), not just the client address.
+- **`serve-http`** is a convenience gateway with the inverse trade-off: commands are gated by the same `--allow-*` policy (safe-only by default), but the bearer token travels in **clear text over plain HTTP**. It binds to loopback by default; `--no-auth` is only permitted there. If you must expose it beyond loopback, put it behind a TLS-terminating reverse proxy — never send the token over an untrusted network unencrypted.
+
+For low latency, an authenticated encrypted remote connection is kept open and reused for further commands in the same process — so SDK scripts and multi-browser fan-out avoid repeating the TCP/TLS/challenge handshake on every command. Aggregate commands also fan out to remote targets concurrently. Both degrade gracefully against older servers that handle one command per connection.
+
 ---
 
 ## Python SDK
@@ -418,7 +450,7 @@ 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. For asyncio programs, `AsyncBrowserCLI` exposes the same namespaces as native awaitable methods over async Unix/TCP transport.
+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.
 
 ```python
 # Navigation  ── b.nav
@@ -573,6 +605,7 @@ 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"}
 ```
 
 ---
@@ -603,11 +636,12 @@ 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.
+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 loading the unpacked `extension/` directory; `browser-cli install <browser> --dev` prints the per-browser load steps. On NixOS, use `nix-shell` first if npm is not installed globally.
 
 Packaging:
 
 ```bash
+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

{real_browser_cli-0.15.5 → real_browser_cli-0.16.2}/README.md

@@ -1,20 +1,21 @@
 # browser-cli
-Control your real, running browser from the terminal or the Python SDK — no headless browser, no Playwright, no virtual display. Your actual open tabs, windows, and tab groups respond to your commands.
+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.
+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
+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)
         │
@@ -33,7 +34,7 @@ terminal / python script
 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 server needs to be running beforehand. The browser manages the native host's lifecycle.
+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**
 
@@ -52,8 +53,10 @@ Every response:
 
 **Requirements:** Python 3.10+, [uv](https://github.com/astral-sh/uv), Chrome, Chromium, Brave, Edge, Vivaldi, or Firefox
 
+browser-cli has two parts: the **CLI / native host** (a Python package) and the **browser extension** (published on the public stores).
+
 ### Install with uv
-Once published on PyPI, install the CLI as a uv tool:
+Install the CLI from PyPI as a uv tool, then register the native host:
 
 ```sh
 uv tool install real-browser-cli
@@ -75,21 +78,31 @@ To upgrade later:
 uv tool upgrade real-browser-cli
 ```
 
+### Add the browser extension
+Install the extension from its public store listing (the `install` command prints the right link for you):
+
+- Chrome / Chromium / Brave / Edge / Vivaldi — [Chrome Web Store](https://chromewebstore.google.com/detail/browser-cli/hekaebjhbhhdbmakimmaklbblbmccahp)
+- Firefox — [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/browser-cli/)
+
+The native host manifest trusts both the published store ID and the unpacked development ID, so the store extension works out of the box. If you are hacking on the extension yourself, run `browser-cli install <browser> --dev` for the unpacked / temporary-add-on load steps instead.
+
 ### Install from source
 ```sh
 git clone <repo>
 cd browser-cli
 uv sync
-uv run browser-cli install brave   # or: chrome, chromium, edge, vivaldi, firefox
+npm ci && npm run build:extension                 # build the unpacked extension bundles
+uv run browser-cli install brave --dev            # --dev prints unpacked-load steps; or: chrome, chromium, edge, vivaldi, firefox
 ```
 
+Omit `--dev` to be pointed at the public store listing instead of loading the unpacked build.
+
 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`
+1. Write the native messaging manifest to your OS so the browser can find the host
+2. Copy the native host into an internal `libexec` directory and create a small wrapper outside your `PATH`
+3. Print the public store link for installing the extension (or, with `--dev`, the unpacked / temporary-add-on load steps)
 
-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.
+After install, add the extension from the store link above and **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.
 
@@ -100,62 +113,42 @@ Only the `browser-cli` command needs to be on your `PATH`. The browser launches
 ```text
 browser-cli/
 ├── browser_cli/
-│   ├── __init__.py        # Python SDK — BrowserCLI class and SDK entry point
-│   ├── cli.py             # Click CLI entry point
-│   ├── client/            # Client-side command routing used by CLI and SDK
-│   │   ├── core.py         # send_command and remote command routing
-│   │   ├── targets.py      # Browser target discovery and socket resolution
-│   │   ├── auth.py         # Remote auth fields and key lookup
-│   │   └── messages.py     # Request/response helpers
-│   ├── models.py          # Tab and Group helper models
-│   ├── native/            # Native messaging host internals
-│   │   ├── host.py         # Browser-launched native host entry point
-│   │   ├── local_server.py # Local CLI IPC server
-│   │   └── protocol.py     # Chrome Native Messaging framing
-│   ├── remote/            # Client-side remote browser support
-│   │   ├── transport.py    # TCP/TLS remote transport
-│   │   └── registry.py     # Saved remote endpoints/keys
-│   └── commands/
-│       ├── navigate.py    # nav open/reload/back/forward/focus
-│       ├── search.py      # search engine shortcuts
-│       ├── tabs.py        # tab management
-│       ├── groups.py      # tab group management
-│       ├── windows.py     # window management
-│       ├── dom.py         # DOM querying and interaction
-│       ├── extract.py     # content extraction
-│       └── session.py     # session save/load
+│   ├── __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      # MV3 extension manifest
-│   ├── content.js         # Content-script helpers
-│   └── src/               # TypeScript source split by command area
-│       ├── index.ts       # Builds generated extension/background.js
-│       └── content/       # Builds generated extension/content-dispatch.js
-├── examples/
-│   ├── demo.py            # Python SDK walkthrough
-│   └── demo.sh            # Bash CLI walkthrough
-├── tests/
-│   ├── conftest.py        # shared pytest fixtures
-│   ├── test_api.py
-│   ├── test_cli.py
-│   ├── test_dom.py
-│   ├── test_extract.py
-│   ├── test_groups.py
-│   ├── test_nav.py
-│   ├── test_session.py
-│   ├── test_tabs.py
-│   └── test_windows.py
-├── com.browsercli.host.json  # native messaging manifest template
-├── pyproject.toml            # package metadata and CLI entry point
-└── uv.lock                   # locked dependencies for uv
+│   ├── 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
 
-All commands are run with `uv run browser-cli [--browser ALIAS] <command>`.
+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. You can inspect the 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.
+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.
 
@@ -315,6 +308,44 @@ browser-cli completion zsh                   # print setup instructions
 browser-cli completion zsh --script          # output raw completion script
 ```
 
+### Remote control, auth, and gateways
+
+```sh
+# 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
+
+# Allow remote browser control (navigation, clicks); safe-only otherwise
+browser-cli serve --authorized-keys ~/.config/browser-cli/authorized_keys --allow-control
+
+# Per-key authorization (inline in authorized_keys) + a tighter rate limit
+browser-cli auth trust "$PUBKEY" --name ci-bot --allow-read-page --allow-control
+browser-cli serve --authorized-keys ~/.config/browser-cli/authorized_keys --rate-limit 20
+
+# 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.
+
+#### Security model
+
+- **`serve` (TCP)** authenticates every connection with an Ed25519 signature over a fresh server nonce and, for modern clients, wraps the transport in an ML-KEM-768 (post-quantum) AEAD channel. Commands are gated by a **safe-only policy by default** — even a trusted key can only run read-only status/listing commands until you open more with `--allow-read-page`, `--allow-control`, `--allow-dangerous`, or `--allow-all` (full control, including `dom.eval`/`storage.*`). `--no-auth` is rejected on non-loopback hosts.
+  - **Per-key authorization:** a key in `authorized_keys` can carry an optional `allow:` token (`<pubkey> <name> allow:read-page,control`) listing its categories (`all`, `safe`, `read-page`, `control`, `dangerous`). That key uses its own policy, overriding the server-wide `--allow-*` default; keys without a token fall back to the default. Set it with `auth trust <pubkey> --allow-control …` (works locally and over `--remote`); `auth keys` shows each key's policy.
+  - **Rate limiting:** `--rate-limit N` caps commands/second per client key (token bucket, default `100`, `0` disables) so a compromised key can't hammer the browser.
+  - **Audit logging:** request logs include the acting key (its name from `authorized_keys` plus a short pubkey), not just the client address.
+- **`serve-http`** is a convenience gateway with the inverse trade-off: commands are gated by the same `--allow-*` policy (safe-only by default), but the bearer token travels in **clear text over plain HTTP**. It binds to loopback by default; `--no-auth` is only permitted there. If you must expose it beyond loopback, put it behind a TLS-terminating reverse proxy — never send the token over an untrusted network unencrypted.
+
+For low latency, an authenticated encrypted remote connection is kept open and reused for further commands in the same process — so SDK scripts and multi-browser fan-out avoid repeating the TCP/TLS/challenge handshake on every command. Aggregate commands also fan out to remote targets concurrently. Both degrade gracefully against older servers that handle one command per connection.
+
 ---
 
 ## Python SDK
@@ -325,7 +356,7 @@ 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. For asyncio programs, `AsyncBrowserCLI` exposes the same namespaces as native awaitable methods over async Unix/TCP transport.
+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.
 
 ```python
 # Navigation  ── b.nav
@@ -480,6 +511,7 @@ 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"}
 ```
 
 ---
@@ -510,11 +542,12 @@ 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.
+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 loading the unpacked `extension/` directory; `browser-cli install <browser> --dev` prints the per-browser load steps. On NixOS, use `nix-shell` first if npm is not installed globally.
 
 Packaging:
 
 ```bash
+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

{real_browser_cli-0.15.5 → real_browser_cli-0.16.2}/browser_cli/auth/__init__.py

@@ -17,11 +17,14 @@ from browser_cli.auth.agent import (
 )
 from browser_cli.auth.keys import (
   add_authorized_key,
+  format_authorized_line,
   generate_keypair,
   load_authorized_keys,
   load_authorized_keys_with_names,
+  load_authorized_keys_with_policies,
   load_private_key,
   public_key_hex,
+  set_authorized_key_policy,
 )
 from browser_cli.auth.pq import (
   new_nonce,
@@ -51,9 +54,11 @@ __all__ = [
   "agent_list_keys",
   "agent_sign_raw",
   "canonical_payload",
+  "format_authorized_line",
   "generate_keypair",
   "load_authorized_keys",
   "load_authorized_keys_with_names",
+  "load_authorized_keys_with_policies",
   "load_private_key",
   "new_nonce",
   "pq_decrypt",
@@ -62,6 +67,7 @@ __all__ = [
   "pq_kex_server_decapsulate",
   "pq_kex_server_keypair",
   "public_key_hex",
+  "set_authorized_key_policy",
   "sign",
   "verify",
 ]