browsercli Python Client

Zero-dependency Python client for the browsercli browser workspace daemon.

Installation

pip install -e clients/python   # from the repo root

Platform Support

The client auto-detects the RPC transport from the session file:

• macOS / Linux — connects via Unix socket (socket_path in session.json)
• Windows — connects via TCP localhost (rpc_port in session.json)

No code changes are needed — BrowserCLI.connect() handles both transports.

Quick Start

from browsercli import BrowserCLI

# Connect to a running daemon
# macOS/Linux: reads ~/.browsercli/session.json
# Windows: reads %LOCALAPPDATA%\browsercli\session.json
ac = BrowserCLI.connect()

# Navigate and inspect
ac.goto("/")
title = ac.dom_query("h1", mode="text")
print(f"Title: {title}")

# Evaluate JavaScript
result = ac.eval("1 + 1")
print(f"Result: {result}")

# Screenshot
ac.screenshot(out="page.png")

# Stop the daemon
ac.stop()

Error Handling

All exceptions inherit from BrowserCLIError, so you can catch the whole family or handle specific cases:

from browsercli import (
    BrowserCLI,
    BrowserCLIError,
    ConnectionError,
    AuthenticationError,
    SessionError,
    NotFoundError,
    ServerError,
)

try:
    ac = BrowserCLI.connect()
    ac.dom_query("#missing-element", mode="text")
except SessionError:
    print("Daemon not running — start it with: browsercli start")
except ConnectionError:
    print("Cannot reach daemon — is the socket file valid?")
except AuthenticationError:
    print("Token rejected — daemon may have restarted, reconnect")
except NotFoundError as e:
    print(f"Element or endpoint not found: {e}")
except ServerError as e:
    print(f"Daemon internal error (HTTP {e.status_code}): {e.error_message}")
except BrowserCLIError as e:
    print(f"Unexpected client error: {e}")

Exception Hierarchy

BrowserCLIError            # Base — catch-all
├── SessionError            # session.json missing/invalid
├── ConnectionError         # RPC endpoint unreachable (socket or TCP)
├── AuthenticationError     # HTTP 401 (bad token)
└── RPCError                # Any HTTP 4xx/5xx with status_code + error_message
    ├── BadRequestError     # HTTP 400
    ├── NotFoundError       # HTTP 404
    └── ServerError         # HTTP 5xx

Constructor

BrowserCLI(socket_path="", token="", timeout=30.0, *, rpc_port=0)

You must provide either socket_path or rpc_port. In most cases, use the connect() factory instead of calling the constructor directly.

API Reference

Valid Parameter Values

Invalid values raise ValueError before any RPC call is made.

Logging

The client uses Python's logging module under the logger name browsercli:

import logging
logging.basicConfig(level=logging.DEBUG)
# Now all RPC requests and responses are logged.

Running Tests

cd clients/python
python -m unittest tests.test_client -v

Tests include:

• Session parsing: valid/invalid/missing session files (including rpc_port for Windows)
• Parameter validation: client-side checks for all method arguments
• Contract tests: mock server (Unix socket on macOS/Linux, TCP on Windows) emulating the Rust daemon
• Error handling: auth failures, 400/404/500 errors, connection errors
• Exception hierarchy: inheritance and attribute verification

Requirements

• Python 3.9+
• A running browsercli daemon (browsercli start)
• No external dependencies (stdlib only)