browser-cli

CLI-first browser automation for AI agents.

browser-cli gives an agent a small, auditable browser surface: stdin commands in, JSON responses out, optional NDJSON logs, policy tiers, screenshots, downloads, CDP reuse, and action traces.

It is designed to be used by Claude Code, Codex, Cursor, Gemini CLI, shell scripts, and CI without requiring the agent host to inject a browser-specific tool schema into the context window.

Why

AI agents often need to inspect rendered pages, click real controls, and capture evidence. Browser MCP tools can do this, but the control boundary is usually host-managed.

browser-cli keeps the boundary visible:

command stdin -> browser-cli -> stdout JSON
                         -> stderr diagnostics
                         -> files/artifacts/logs
                         -> exit code

This matches Trinity's operating rule:

Trust artifacts, not claims.

Status

• Public clean export: v0.3.0
• Runtime: Node.js + Playwright
• Contract surface: v1/v2 JSON responses, v3 Trinity Tool Contract envelope, policy tiers, artifacts, logs
• Trinity Tool Contract: partial v1.0 implementation; write-boundary enforcement still partial
• Text output: clean whitespace by default, opt out with --clean=false or @clean=false
• Snapshot globals: config-driven via snapshot.globals, default empty
• Private configs, screenshots, session data, and project-specific docs are not included in this repository

Install

npm install
npm run install-browsers

Quick Start

Run one command against a public page:

node index.js --config configs/example.json --cmd "goto /"

Pipe a small browser script:

printf "goto /\ntitle\nscreenshot example-home.png\nexit\n" \
  | node index.js --config configs/example.json --response-schema=v2

Use an existing Chrome through CDP:

./scripts/start-chrome-debug.sh
node index.js --cdp http://localhost:9222 \
  --config configs/example.json \
  --reuse-tab \
  --cmd "outline"

Change viewport in real time during the same session:

printf "goto /\nviewport 375x667\nscreenshot mobile.png\nviewport 1440x900\nscreenshot desktop.png\nexit\n" \
  | node index.js --config configs/example.json --response-schema=v2

Clean text output is enabled by default:

node index.js --config configs/example.json --cmd "text body"
node index.js --config configs/example.json --clean=false --cmd "text body"

Command Model

browser-cli is a REPL. Each line is one command.

Examples:

goto /
text h1
exists .login-button
click "text=Sign in"
fill input[name=email] user@example.com
screenshot proof.png
text body @clean=false
ajax-log
exit

Structured output mode:

node index.js \
  --config configs/example.json \
  --response-schema=v2 \
  --policy=normal \
  --log-file ./browser-cli.ndjson

Trinity Tool Contract output envelope:

node index.js \
  --config configs/example.json \
  --response-schema=v3 \
  --policy=safe \
  --cmd "text body"

Trinity Tool Contract input envelope:

node index.js --config configs/example.json --input request.json
cat request.json | node index.js --config configs/example.json --input -

Policy Tiers

browser-cli classifies commands before execution.

Tier	Examples	Default behavior
safe	goto, text, exists, outline, screenshot	allowed
medium	click, fill, select	allowed in normal
high	upload, force-click, force-submit	blocked unless aggressive

viewport / set-viewport are safe browser-state commands. They change the current page viewport for responsive verification, but do not mutate application data.

Policy modes:

safe       allow read-only / low-risk commands
normal     allow normal interaction, block force/high-risk commands
aggressive allow all local commands

Trinity Tool Contract

Canonical contract repo:

• https://github.com/postmunnet/trinity-tool-contract

browser-cli is the first browser organ in the Trinity ecosystem. The current public export keeps its historical v1/v2 response schema and adds a v3 Trinity Tool Contract output envelope plus --input envelope mode. See CONTRACT_COMPLIANCE.md.

Tests

npm test

This runs unit tests for parsing, response wrapping, policy tiers, recorder privacy filters, and CDP URL validation. Browser smoke tests are opt-in:

./scripts/start-chrome-debug.sh
node tests/cdp.js --smoke

Documentation

• docs/ARCHITECTURE.md
• docs/COMMANDS.md
• docs/CONFIG.md
• docs/CONFORMANCE.md
• README_TH.md

License

Apache-2.0