browser-cli/n8n-nodes-browser-cli/README.md

# n8n-nodes-browser-cli
An [n8n](https://n8n.io) community node, published on npm as [`n8n-nodes-browser-cli`](https://www.npmjs.com/package/n8n-nodes-browser-cli), that controls a **real, visible browser**
from your workflows via [browser-cli](https://chromewebstore.google.com/detail/browser-cli/hekaebjhbhhdbmakimmaklbblbmccahp).

browser-cli drives a running browser through a native-messaging host and a
browser extension — it **cannot be installed inside the n8n container**. So this
node speaks the `browser-cli serve` protocol **directly**: a length-framed TCP
connection authenticated with an Ed25519 key, with request/response bodies
encrypted end-to-end via an ML-KEM-768 (post-quantum) key exchange — the same
wire protocol the `browser-cli --remote` client uses.

```
n8n workflow ──TCP (Ed25519 + ML-KEM-768)──▶ browser-cli serve (remote host) ──▶ browser
```

Because the payloads are end-to-end encrypted, the endpoint is safe to expose on
an untrusted network without a TLS proxy in front of it.

## Remote setup (on the browser machine)
Install browser-cli, register the extension, trust your n8n key, then start
`serve` opening exactly the command tiers you need (it is **safe-only by default**):

```bash
uv tool install real-browser-cli
browser-cli install brave            # one-time: register the extension/native host

# On the n8n side, generate a client key and print its public key:
browser-cli auth keygen -o n8n_key.pem

# On the browser machine, trust that public key (optionally scope its policy):
browser-cli auth trust <pubkey-hex> --allow-control

# Expose the browser. Open only what your workflow needs:
browser-cli serve --host 0.0.0.0 --port 8765 \
  --authorized-keys ~/.browser_cli/authorized_keys --allow-read-page --allow-control
```

Paste the contents of `n8n_key.pem` into the n8n credential.

## n8n credential — "Browser CLI API"
| Field | Description |
|-------|-------------|
| Host | host of the `serve` endpoint, e.g. `browser-host.example` |
| Port | `serve` TCP port (default `8765`) |
| Ed25519 Private Key | PKCS8 PEM from `browser-cli auth keygen` (empty only for `--no-auth` loopback) |
| Browser Alias | optional `_route` target — required if the endpoint serves multiple browsers |
| Use TLS | wrap the connection in TLS (only for a TLS-terminating proxy; the protocol is already encrypted) |
| Ignore SSL Issues | when TLS is on, accept a self-signed proxy cert |

## Operations
Every operation maps to one raw browser-cli command, each subject to the server
policy tier noted below.

| Resource | Operation | Command | Server flag needed |
|----------|-----------|---------|--------------------|
| Tab | List / Query / Get / Count / Filter / Active in Window | `tabs.list` / `tabs.query` / `tabs.status` / `tabs.count` / `tabs.filter` / `tabs.active_in_window` | safe (default) |
| Tab | Get HTML | `tabs.html` | `--allow-read-page` |
| Tab | Open / Close / Activate / Move / Navigate To / Reload / Hard Reload / Back / Forward | `navigate.open` / `tabs.close` / `tabs.active` / `tabs.move` / `navigate.to` / `navigate.reload` / `navigate.hard_reload` / `navigate.back` / `navigate.forward` | `--allow-control` |
| Tab | Mute / Unmute / Pin / Unpin / Dedupe / Sort / Merge Windows | `tabs.mute` / `tabs.unmute` / `tabs.pin` / `tabs.unpin` / `tabs.dedupe` / `tabs.sort` / `tabs.merge_windows` | `--allow-control` |
| Tab | Screenshot | `tabs.screenshot` | `--allow-dangerous` |
| Page | Get Info | `page.info` | safe (default) |
| Page | Extract Text / Links / Images / HTML / Markdown / JSON | `extract.*` | `--allow-read-page` |
| DOM | Query / Text / Attribute / Exists | `dom.query` / `dom.text` / `dom.attr` / `dom.exists` | `--allow-read-page` |
| DOM | Click / Type / Select / Hover / Focus / Check / Uncheck / Clear / Submit / Scroll / Key | `dom.*` | `--allow-control` |
| DOM | Eval | `dom.eval` | `--allow-dangerous` |
| Group | List / Query / Tabs | `group.list` / `group.query` / `group.tabs` | safe (default) |
| Group | Count / Create / Add Tab / Move / Close | `group.count` / `group.open` / `group.add_tab` / `group.move` / `group.close` | `--allow-control` |
| Window | List | `windows.list` | safe (default) |
| Window | Open / Close / Rename | `windows.open` / `windows.close` / `windows.rename` | `--allow-control` |
| Session | List / Save / Load / Remove / Export / Diff / Auto Save | `session.*` | `--allow-control` |
| Storage | Get / Set | `storage.get` / `storage.set` | `--allow-dangerous` |
| Performance | Status | `perf.status` | safe (default) |
| Extension | Info / Capabilities | `extension.info` / `extension.capabilities` | safe (default) |
| Extension | Reload | `extension.reload` | `--allow-control` |
| Client | List | `clients.list` | safe (default) |
| Command | Execute | any command name + JSON args | per command |

**Command → Execute** is the escape hatch: any command string the server policy
allows (`tabs.query`, `session.save`, `windows.list`, …) with a JSON args object.
Use it for anything the typed operations don't cover.

> Note: `serve` returns the **raw** command result (no SDK post-processing).
> `extract.markdown` therefore returns the page payload as the extension hands it
> back, not the CLI's rendered Markdown. For clean text use **Extract Text**.

## Develop / build
```bash
cd n8n-nodes-browser-cli
npm install                 # add --ignore-scripts if a transitive native dep
                            # (isolated-vm) fails to compile on your Node version
npm test          # pure unit tests: command mapping + crypto known-answer vectors
npm run build     # tsc -> dist/, copies the icon
```

Install the published package in n8n as a [community node](https://docs.n8n.io/integrations/community-nodes/installation/) using the package name `n8n-nodes-browser-cli`, or symlink `dist/` into `~/.n8n/custom` for local testing.

## License
PolyForm Noncommercial License 1.0.0 — same as browser-cli.