GitHub - rinvii/buse: Control your browser from the terminal.

Control your browser from your terminal.

buse is a stateless CLI designed for AI agents and automation scripts. It turns complex browser interaction into simple, structured command-line primitives.

Key Features

• Stateless Control: Just point the CLI at a browser and go.
• Persistent Sessions: Multiple browser instances can run simultaneously.
• Universal Primitives: Click, type, scroll, and execute JS with one-liners.
• Vision-Ready: observe captures semantic state plus optional screenshots and SoM labels.
• Session Migration: Export cookies/storage via save-state to maintain persistent logins.

Why 'buse'?

Automating a browser usually means writing long, complex scripts or paying for expensive cloud services. buse changes that by letting you control a browser just like any other folder or file on your computer—using simple, one-word commands in your terminal.

For example, open a browser and navigate to a website:

uvx --python 3.12 buse browser-1
uvx --python 3.12 buse browser-1 navigate "https://example.com"
uvx --python 3.12 buse browser-2 # open a second browser
uvx --python 3.12 buse browser-2 search "latest tech news"

Installation

With uv:

uvx --python 3.12 buse --help

With pip:

From source:

cd buse
uv pip install -e .

Requirements

• Python 3.12
• Google Chrome (local install)

Usage Pattern

buse <instance_id> <command> [args]

Command List

1. Lifecycle & State

2. Analysis & Extraction

observe notes

• DOM indices are ephemeral; refresh with buse <id> observe after page changes, or use --id/--class for stability.
• Preferred flags are --visual (som, omni, none), --text (ai, dom, none), and --mode (efficient, full, raw).
• --human prints a human-friendly layout; JSON output is better for agents.
• Legacy flags (--screenshot, --omniparser, --som, --semantic, --no-dom, --diagnostics) are still supported for compatibility.
• observe --visual omni always captures a screenshot: saves image.jpg (input) and image_som.jpg (server output) in the screenshots dir or --path.
• When available, screenshot_path points to image_som.jpg. OmniParser bbox values are in CSS pixels (not normalized).
• Use --text none to skip DOM processing and return an empty dom_minified.
• --max-chars 0 disables semantic truncation entirely.

3. Navigation & Interaction

4. Advanced

Examples

Flag Matrix

Global (all commands):

• --format (json|toon, default: json), -f alias
• --profile (default: false), -p alias

Selected command flags:

• observe: --visual, --text, --mode, --max-chars, --max-labels, --selector, --frame, --human, --path (legacy: --screenshot, --omniparser, --som, --semantic, --no-dom, --diagnostics)
• click: --selector, --id, --class, --x/--y, --right, --middle, --double, --ctrl/--shift/--alt/--meta, --force, --debug
• input: --text, --id, --class, --slowly, --append, --submit
• fill: JSON list payload (positional)
• drag: --html5/--no-html5
• send-keys: --index, --id, --class, --list-keys
• scroll: --down/--up, --pages, --index
• wait: --text, --selector, --network-idle, --timeout

Commands

# Start a session
buse b1

# Observe without screenshot (JSON)
buse b1 observe

# Observe with SoM labels and semantic text (JSON + image)
buse b1 observe --visual som --text ai

# Navigate and click by coordinates
buse b1 navigate "https://example.com"
buse b1 click --x 280 --y 220

# Click by ref/id/class fallback
buse b1 click e3
buse b1 click --id "submit-button"
buse b1 click --class "cta-primary"

# Input by id with explicit --text
buse b1 input --id "email" --text "test@example.com"

# Input slowly and submit
buse b1 input --id "email" --text "test@example.com" --slowly --submit

# Fill multiple fields atomically
buse b1 fill '[{"ref":"e1","value":"user"},{"ref":"e2","value":"pass","type":"text"}]'

# Drag and drop
buse b1 drag e1 e2

# Upload a file
buse b1 upload-file 5 "./image.png"

# Send special keys
buse b1 send-keys "Enter"

# Send keys to a focused element
buse b1 send-keys --id "search" "Hello"

# List send-keys names
buse b1 send-keys --list-keys

# Find and scroll to text
buse b1 find-text "Contact Us"

# Get dropdown options and select by text
buse b1 dropdown-options --id "country"
buse b1 select-dropdown --id "country" --text "Canada"

# Scroll and wait
buse b1 scroll --down --pages 1.5
buse b1 scroll --up --pages 1
buse b1 wait 2

MCP Server

Expose the active browser instances via the Model Context Protocol.

buse mcp-server --host 0.0.0.0 --port 8000

• --transport selects streamable-http (default), sse, or stdio.
• --name changes the MCP server name, --stateless/--stateful controls HTTP mode, and --json-response/--no-json-response toggles JSON wrapping.
• --allow-remote permits non-local clients (default: local-only). --auth-token requires Authorization: Bearer <token> or X-Buse-Token for HTTP requests.
• --format (json|toon, default: json), -f alias.
• Resources:
  • buse://sessions returns a list of session metadata (instance_id, cdp_url, user_data_dir).
  • buse://session/{id} returns the metadata for a single session.
• Tools:
  • Supports all CLI actions: navigate, click, input_text, fill, drag, send_keys, scroll, switch_tab, close_tab, search, upload_file, find_text, dropdown_options, select_dropdown, go_back, hover, refresh, wait, save_state, extract, evaluate, stop_session, start_session, observe.

The mcp SDK ships with buse, so no extra installation is required.

Output & Profiling

• --format json|toon to switch output format.
• --profile (or -p) includes timing data in the JSON response.

Environment Variables

• BUSE_EXTRACT_MODEL: model name for extract (default: gpt-4o-mini).
• OPENAI_API_KEY: required for extract.
• BUSE_KEEP_SESSION: set to 1 to keep the session open within a single process.
• BUSE_SELECTOR_CACHE_TTL: selector-map cache TTL in seconds (default: 0, disabled).
• BUSE_REMOTE_ALLOW_ORIGINS: override Chrome --remote-allow-origins (default: http://localhost:<port>,http://127.0.0.1:<port>).
• BUSE_IMAGE_QUALITY: JPEG quality (1-100) for OmniParser images.
• BUSE_MCP_ALLOW_REMOTE: set to 1 to allow non-local MCP clients.
• BUSE_MCP_AUTH_TOKEN: require a Bearer or X-Buse-Token header for MCP HTTP access.

References & Inspiration

https://blog.google/innovation-and-ai/models-and-research/google-deepmind/gemini-computer-use-model/

https://www.anthropic.com/news/3-5-models-and-computer-use

https://docs.browser-use.com/introduction

Roadmap

• Support all operating systems: Windows, macOS, Linux (right now works on my 10.15 macOS and Windows 11)
• Add automation scripting examples
• Add e2e tests
• Add optional daemon for persistent background sessions