browser-cli is a small Playwright REPL for agents and shell scripts.
stdin / --cmd
|
v
parser -> policy -> dispatcher -> Playwright command handlers
| | |
| | +-> artifacts
| +--------------> block/allow verdict
+------------------------> structured response wrapper
The runtime supports two browser modes:
| Mode | Description |
|---|---|
| local | Launch a new Chromium instance for the CLI process |
| CDP | Connect to an existing Chrome/Chromium on http://localhost:<port> |
Viewport is part of browser runtime state. The initial viewport can come from
--viewport, VIEWPORT_W/VIEWPORT_H, or config. During a session, the
viewport command calls Playwright page.setViewportSize() on the active page,
so agents can run responsive checks without restarting the REPL.
The output boundary is intentionally simple:
| Stream | Purpose |
|---|---|
| stdout | Machine-readable JSON responses |
| stderr | Human diagnostics and warnings |
| files | Screenshots, downloads, NDJSON logs, traces |
| exit code | Process-level success/failure |
browser-cli is meant to remain portable across vendor AI harnesses. If a host can run shell commands, it can use browser-cli without loading a browser-specific tool registry into the model context.
Trinity Protocol is the governance kernel. browser-cli is an organ: a focused tool that can produce browser evidence for a verifier. It should not decide whether work is complete. It only executes browser operations and emits evidence.