Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
feat: Add fast CLI for browser automation (bu command)
Gregor Žuničc4ffaca6e79b
diff --git a/CLI_SPEC.md b/CLI_SPEC.mdnew file mode 100644index 000000000..647cd6a54--- /dev/null+++ b/CLI_SPEC.md@@ -0,0 +1,718 @@+# Browser-Use CLI: Complete Implementation Specification++> **Standalone spec for developers** - Everything needed to implement the browser-use CLI with persistent sessions, Python execution, and multi-browser support.++---++## Table of Contents++1. [Overview](#overview)+2. [Architecture Decision: Why NOT a Separate Daemon](#architecture-decision)+3. [The Correct Architecture: Session Server](#the-correct-architecture)+4. [Browser Modes](#browser-modes)+5. [Persistent Python Execution](#persistent-python-execution)+6. [API Key & Monetization](#api-key--monetization)+7. [Complete Command List](#complete-command-list)+8. [Code Structure](#code-structure)+9. [Implementation Heuristics](#implementation-heuristics)+10. [Future Work](#future-work)++---++## Overview++Build a **fast CLI** (`browser-use`) with:++- **Persistent browser sessions** - Browser stays open between commands+- **Multiple browser modes** - Chromium, Real Browser (user profile), Remote (Cloud)+- **Persistent Python execution** - Jupyter-like REPL for scraping/automation+- **Agent task execution** - Run AI agents on persistent sessions (requires API key)+- **Claude Code integration** - API for AI assistants to control browsers++### Design Principles++1. **Work WITH BrowserSession, not around it** - No conflicts with existing internals+2. **CLI must be instant** (<50ms) - Stdlib only in CLI layer+3. **Promote Browser-Use Cloud** - Remote browsers + proxies = revenue+4. **Python persistence is a killer feature** - Enable complex automation workflows++---++## Architecture Decision++### Why NOT a Separate Daemon?++After analyzing BrowserSession internals, a **separate daemon would cause major conflicts**:++| Conflict Area | Problem |+|---------------|---------|+| **Process Ownership** | `LocalBrowserWatchdog` owns the subprocess. Two owners = race conditions on kill/cleanup |+| **CDP Connection** | Single `_cdp_client_root` per session. Duplicate connections = event chaos |+| **Event Bus** | 11 watchdogs register handlers. Separate daemon misses critical events |+| **Session State** | Shared mutable state (focus, cache, downloads). Daemon would cause inconsistencies |+| **Cleanup** | BrowserSession.kill() stops all handlers. Daemon wouldn't participate |++### The go-rod Launcher Insight++The go-rod launcher is excellent for **spawning browsers and getting CDP URLs**, but browser-use already has this via:+- `LocalBrowserWatchdog` - Process management+- `BrowserProfile` - Configuration+- CDP URL discovery via `/json/version`++**We don't need to replace this. We need to keep BrowserSession instances alive.**++---++## The Correct Architecture++### Session Server (Not Daemon)++Instead of a daemon that manages browsers directly, we build a **server that manages BrowserSession instances**:++```+┌─────────────────────────────────────────────────────────────────────────────┐+│ FAST CLI │+│ (stdlib only: <50ms startup) │+│ │+│ $ browser-use open https://example.com --session work --browser real │+│ $ browser-use python "data = browser.scrape('table')" │+│ $ browser-use run "fill the form" --session work # Requires API key │+└─────────────────────────────────────────────────────────────────────────────┘+ │+ Unix Socket │ /tmp/browser-use.sock+ ▼+┌─────────────────────────────────────────────────────────────────────────────┐+│ SESSION SERVER │+│ (keeps BrowserSession instances alive) │+│ │+│ ┌────────────────────────────────────────────────────────────────────┐ │+│ │ Session Registry │ │+│ │ │ │+│ │ sessions = { │ │+│ │ "work": { │ │+│ │ browser_session: BrowserSession, # ← Uses existing class! │ │+│ │ python_session: PythonSession, # ← Jupyter-like REPL │ │+│ │ mode: "real", │ │+│ │ ... │ │+│ │ } │ │+│ │ } │ │+│ └────────────────────────────────────────────────────────────────────┘ │+│ │+│ The server USES BrowserSession, doesn't replace it. │+│ All watchdogs, CDP management, event bus work normally. │+└─────────────────────────────────────────────────────────────────────────────┘+ │+ │ (BrowserSession handles everything)+ ▼+┌─────────────────────────────────────────────────────────────────────────────┐+│ BROWSER │+│ │+│ Mode: chromium │ Mode: real │ Mode: remote │+│ ───────────────── │ ────────────────── │ ───────────────── │+│ Playwright binary │ User's Chrome │ Browser-Use Cloud │+│ Temp profile │ Real profile │ CDP via API │+│ Headless/headed │ With extensions │ Proxies available │+│ │ Logged-in sessions │ BROWSER_USE_API_KEY req. │+└─────────────────────────────────────────────────────────────────────────────┘+```++### Key Insight: BrowserSession Already Does Everything++BrowserSession handles:+- ✅ Browser process lifecycle (LocalBrowserWatchdog)+- ✅ CDP connection management (SessionManager)+- ✅ Event-driven architecture (EventBus + 11 watchdogs)+- ✅ Crash detection & recovery+- ✅ Screenshot, DOM, downloads, popups, etc.++**Our job is just to:**+1. Keep BrowserSession instances in memory (don't let them get garbage collected)+2. Provide a fast CLI to interact with them+3. Add Python execution on top+4. Route commands to the right session++---++## Browser Modes++Three browser modes, configured via `--browser` flag:++### 1. Chromium (Default)+```bash+browser-use open https://example.com --browser chromium+browser-use open https://example.com --browser chromium --headed+```++- Uses Playwright-managed Chromium+- Fresh profile (isolated)+- Fast, reliable, headless by default+- **No API key required**++### 2. Real Browser+```bash+browser-use open https://example.com --browser real+browser-use open https://example.com --browser real --profile "Profile 1"+```++- Uses user's actual Chrome installation+- Preserves login sessions, cookies, extensions+- Great for authenticated workflows+- See: https://docs.browser-use.com/customize/browser/real-browser+- **No API key required**++### 3. Remote (Browser-Use Cloud)+```bash+browser-use open https://example.com --browser remote+browser-use open https://example.com --browser remote --proxy residential+```++- Cloud-hosted browser via Browser-Use API+- Supports proxies (residential, datacenter)+- See: https://docs.browser-use.com/customize/browser/remote+- **Requires BROWSER_USE_API_KEY** ← Revenue!++### Implementation++Maps directly to existing BrowserSession/BrowserProfile:++```python+def create_browser_session(mode: str, headed: bool, profile: str | None) -> BrowserSession:+ if mode == "chromium":+ return BrowserSession(+ browser_profile=BrowserProfile(headless=not headed)+ )++ elif mode == "real":+ # Real browser with user profile+ return BrowserSession(+ browser_profile=BrowserProfile(+ use_own_browser=True,+ chrome_instance_path=find_chrome(), # Auto-detect+ user_data_dir=get_chrome_profile(profile),+ headless=False, # Real browser is always visible+ )+ )++ elif mode == "remote":+ require_api_key() # Raises if missing+ return BrowserSession(+ use_cloud=True,+ cloud_config=CloudConfig(+ proxy_type=proxy, # residential, datacenter, none+ )+ )+```++---++## Persistent Python Execution++### The Killer Feature++Inspired by bu-use's `PythonSession`, we add Jupyter-like persistent execution:++```bash+# Turn 1: Scrape data+$ browser-use python "products = browser.extract('all product names and prices')"++# Turn 2: Variables persist!+$ browser-use python "print(len(products))"+42++# Turn 3: Process and save+$ browser-use python "+import json+with open('products.json', 'w') as f:+ json.dump(products, f)+"++# Turn 4: Loop through pages (deterministic automation!)+$ browser-use python "+for page in range(1, 10):+ browser.click(f'page-{page}')+ data = browser.extract('prices')+ all_data.extend(data)+"+```++### Why This is Powerful++1. **Deterministic automation** - Write loops, conditionals in Python+2. **Data persistence** - Variables survive across commands+3. **Full Python ecosystem** - pandas, numpy, BeautifulSoup, etc.+4. **Browser access** - `browser` object provides full control+5. **Incremental development** - Test code step by step++### Implementation++```python+@dataclass+class PythonSession:+ """Jupyter-like persistent Python execution."""+ namespace: dict[str, Any] = field(default_factory=dict)+ execution_count: int = 0+ history: list[ExecutionRecord] = field(default_factory=list)++ def __post_init__(self):+ # Pre-populate namespace with useful imports+ self.namespace.update({+ 'json': __import__('json'),+ 're': __import__('re'),+ 'Path': Path,+ # browser object injected per-session+ })++ def execute(self, code: str, browser: BrowserSession) -> ExecutionResult:+ """Execute code in persistent namespace."""+ self.namespace['browser'] = BrowserWrapper(browser)+ self.execution_count += 1++ # Capture stdout+ stdout = io.StringIO()+ with redirect_stdout(stdout):+ try:+ # Try as expression first (for REPL-like behavior)+ result = eval(code, self.namespace)+ if result is not None:+ print(repr(result))+ except SyntaxError:+ # Execute as statements+ exec(code, self.namespace)++ output = stdout.getvalue()+ self.history.append(ExecutionRecord(code, output))+ return ExecutionResult(success=True, output=output)+```++### BrowserWrapper++Provides convenient methods for Python code:++```python+class BrowserWrapper:+ """Convenient browser access for Python code."""++ def __init__(self, session: BrowserSession):+ self.session = session++ @property+ def url(self) -> str:+ return self.session.current_url++ @property+ def title(self) -> str:+ return self.session.title++ def goto(self, url: str):+ """Navigate to URL."""+ asyncio.run(self.session.navigate(url))++ def click(self, selector_or_index: str | int):+ """Click element by selector or index."""+ asyncio.run(self.session.click(selector_or_index))++ def type(self, text: str, selector: str | int | None = None):+ """Type text into element."""+ asyncio.run(self.session.type(text, selector))++ def extract(self, query: str) -> Any:+ """Extract structured data using LLM."""+ # Uses the existing extract tool+ asyncio.run(self.session.extract(query))++ def screenshot(self) -> bytes:+ """Take screenshot, return bytes."""+ return asyncio.run(self.session.screenshot())++ @property+ def html(self) -> str:+ """Get page HTML."""+ return asyncio.run(self.session.get_html())++ @property+ def text(self) -> str:+ """Get page text content."""+ return asyncio.run(self.session.get_text())+```++---++## API Key & Monetization++### Strategy++1. **Free tier** - Chromium and Real browser modes work without API key+2. **Paid features** - Remote browsers, proxies, and **agent tasks** require API key+3. **Easy injection** - Multiple ways to provide key++### When API Key is Required++| Feature | API Key Required? |+|---------|-------------------|+| `--browser chromium` | No |+| `--browser real` | No |+| `--browser remote` | **Yes** |+| `browser-use run "<task>"` (agent) | **Yes** |+| `browser-use python "..."` | No |+| Direct browser control (click, type, etc.) | No |++### API Key Injection (Easy for Users)++**Option 1: Environment variable** (recommended)+```bash+export BROWSER_USE_API_KEY=your_key_here+browser-use run "fill the form"+```++**Option 2: Config file** (`~/.config/browser-use/config.json`)+```json+{+ "api_key": "your_key_here"+}+```++**Option 3: CLI flag** (one-time)+```bash+browser-use run "fill the form" --api-key your_key_here+```++**Option 4: Interactive prompt** (first-time setup)+```bash+$ browser-use run "fill the form"++╭─────────────────────────────────────────────────────────────╮+│ 🔑 Browser-Use API Key Required │+│ │+│ Agent tasks require an API key. │+│ Get yours at: https://browser-use.com/dashboard │+│ │+│ Enter API key: ________________________________________ │+│ │+│ [ ] Save to ~/.config/browser-use/config.json │+╰─────────────────────────────────────────────────────────────╯+```++### Implementation++```python+def require_api_key(feature: str = "this feature") -> str:+ """Get API key or raise helpful error."""++ # 1. Check environment+ key = os.environ.get("BROWSER_USE_API_KEY")+ if key:+ return key++ # 2. Check config file+ config_path = Path.home() / ".config" / "browser-use" / "config.json"+ if config_path.exists():+ config = json.loads(config_path.read_text())+ if key := config.get("api_key"):+ return key++ # 3. Interactive prompt (if TTY)+ if sys.stdin.isatty():+ return prompt_for_api_key(feature)++ # 4. Error with helpful message+ raise APIKeyRequired(f"""+╭─────────────────────────────────────────────────────────────╮+│ 🔑 Browser-Use API Key Required │+│ │+│ {feature} requires an API key. │+│ │+│ Get yours at: https://browser-use.com/dashboard │+│ │+│ Then set it via: │+│ export BROWSER_USE_API_KEY=your_key_here │+│ │+│ Or add to ~/.config/browser-use/config.json: │+│ {{"api_key": "your_key_here"}} │+╰─────────────────────────────────────────────────────────────╯+""")+```++---++## Complete Command List++### Browser Control++| Command | Description | API Key? |+|---------|-------------|----------|+| `open <url>` | Navigate to URL | No |+| `click <index>` | Click element | No |+| `type <text>` | Type text | No |+| `input <index> <text>` | Type into element | No |+| `scroll [up\|down]` | Scroll page | No |+| `back` | Go back | No |+| `screenshot` | Take screenshot | No |+| `state` | Get browser state | No |+| `switch <tab>` | Switch tab | No |+| `close-tab <tab>` | Close tab | No |+| `keys <keys>` | Send keys | No |+| `select <index> <text>` | Select dropdown | No |+| `eval <js>` | Execute JS | No |+| `extract <query>` | Extract data (LLM) | No |++### Python Execution++| Command | Description | API Key? |+|---------|-------------|----------|+| `python "<code>"` | Execute Python | No |+| `python --file script.py` | Run Python file | No |+| `python --reset` | Clear namespace | No |+| `python --vars` | Show variables | No |++### Agent Tasks++| Command | Description | API Key? |+|---------|-------------|----------|+| `run "<task>"` | Run agent task | **Yes** |+| `run --max-steps N` | Limit steps | **Yes** |++### Session Management++| Command | Description | API Key? |+|---------|-------------|----------|+| `sessions` | List sessions | No |+| `close [--session X]` | Close session | No |+| `close --all` | Close all | No |++### Server Control++| Command | Description |+|---------|-------------|+| `server status` | Check server |+| `server stop` | Stop server |+| `server logs` | View logs |++### Global Flags++| Flag | Description | Default |+|------|-------------|---------|+| `--session NAME` | Session name | `"default"` |+| `--browser MODE` | chromium/real/remote | `"chromium"` |+| `--headed` | Show browser | `false` |+| `--profile NAME` | Chrome profile (real mode) | Default profile |+| `--proxy TYPE` | Proxy type (remote mode) | `none` |+| `--api-key KEY` | API key override | From env/config |+| `--json` | JSON output | `false` |++---++## Code Structure++```+browser_use/cli/+├── __init__.py+├── __main__.py # Entry: python -m browser_use.cli+│+├── main.py # Fast CLI (STDLIB ONLY!)+│ ├── Argument parsing+│ ├── ensure_server()+│ ├── send_command()+│ └── main()+│+├── server.py # Session server+│ ├── SessionServer class+│ ├── Socket server (asyncio)+│ ├── Command dispatch+│ └── Graceful shutdown+│+├── sessions.py # Session registry+│ ├── SessionInfo dataclass+│ ├── SessionRegistry class+│ ├── create_browser_session()+│ └── Health checks+│+├── commands/ # Command handlers+│ ├── __init__.py+│ ├── browser.py # open, click, type, etc.+│ ├── python_exec.py # python command+│ ├── agent.py # run command (requires API key)+│ └── session.py # sessions, close+│+├── python_session.py # Jupyter-like REPL+│ ├── PythonSession class+│ ├── BrowserWrapper class+│ └── execute()+│+├── api_key.py # API key management+│ ├── require_api_key()+│ ├── prompt_for_api_key()+│ └── save_api_key()+│+├── protocol.py # Message types+│ ├── Request/Response+│ └── Serialization+│+└── utils.py # Helpers+ ├── Platform detection+ └── Path utilities+```++### pyproject.toml Entry Point++```toml+[project.scripts]+browser-use = "browser_use.cli.main:main"+```++---++## Implementation Heuristics++### 1. CLI Speed is Sacred++**Rule**: The CLI file (`main.py`) must ONLY use stdlib imports.++```python+# ✅ GOOD - stdlib only+import argparse, json, os, socket, subprocess, sys, time++# ❌ BAD - external imports+import click # NO!+import rich # NO!+from browser_use import ... # NO!+```++All heavy imports go in the server, which loads once and stays running.++### 2. BrowserSession is the Source of Truth++**Rule**: Never bypass BrowserSession. Always use its methods.++```python+# ✅ GOOD - use BrowserSession+session.browser_session.navigate(url)+await session.browser_session.click(index)++# ❌ BAD - direct CDP calls+cdp_client.send("Page.navigate", {"url": url}) # NO!+```++This ensures all watchdogs, events, and state stay in sync.++### 3. Promote Cloud Browsers Naturally++**Rule**: When remote features are needed, guide users to Browser-Use Cloud.++```python+# When user needs proxy+if needs_proxy and mode != "remote":+ print("💡 Tip: For proxy support, use --browser remote")+ print(" Get API key at: https://browser-use.com/dashboard")++# When agent task fails due to blocks+if blocked_by_captcha:+ print("💡 Tip: Browser-Use Cloud includes CAPTCHA solving")+ print(" Try: browser-use run '...' --browser remote")+```++### 4. Python Session Isolation++**Rule**: Each named session has its own Python namespace.++```bash+# Session "work" has its own variables+browser-use python "x = 1" --session work++# Session "personal" is isolated+browser-use python "print(x)" --session personal # Error: x not defined+```++### 5. Graceful Degradation++**Rule**: Always clean up resources, even on crash.++```python+# Server shutdown+async def shutdown(self):+ for session in self.registry.all():+ try:+ await session.browser_session.stop()+ except:+ pass # Browser might already be dead++ # Remove socket/PID files+ cleanup_files()+```++### 6. Error Messages Should Help++**Rule**: Every error should tell the user what to do next.++```python+# ❌ BAD+raise Exception("API key missing")++# ✅ GOOD+raise APIKeyRequired("""+API key required for agent tasks.+Get yours at: https://browser-use.com/dashboard+Set via: export BROWSER_USE_API_KEY=your_key+""")+```++### 7. Session Auto-Creation++**Rule**: Sessions are created on-demand, not explicitly.++```bash+# This creates session "work" if it doesn't exist+browser-use open https://example.com --session work++# No need for explicit "create session" command+```++### 8. Default to Headless++**Rule**: Chromium mode defaults to headless for speed/resources.++```bash+browser-use open https://example.com # Headless+browser-use open https://example.com --headed # Visible+browser-use open https://example.com --browser real # Always visible+```++---++## Future Work++### From CodeAgent/BU Agent+- **Background shell processes** - `bash` with persistent shells+- **File operations** - `read`, `write`, `edit`, `glob`, `grep`+- **Todo tracking** - Task progress management+- **Context compaction** - Auto-compress long conversations++### From agent-browser+- **Live streaming** - Stream browser view to terminal+- **Screencast recording** - Record sessions as video+- **Multiple browser types** - Firefox, WebKit support++### From browser-use+- **Skills integration** - Load automation skills from API+- **Storage persistence** - Save/restore cookies across server restarts+- **Download management** - Track and organize downloads++### New Features+- **Session snapshots** - Save/restore full browser state+- **Event replay** - Record and replay automation sequences+- **HTTP API** - REST endpoint for programmatic access+- **Watch mode** - Re-run Python on file changes+- **Notebook export** - Export Python session as .ipynb++---++## Success Criteria++- [ ] `browser-use open <url>` works with <50ms CLI startup+- [ ] All three browser modes work (chromium, real, remote)+- [ ] Python execution persists variables across commands+- [ ] Agent tasks require and validate API key+- [ ] API key prompt is user-friendly+- [ ] Sessions are isolated and named+- [ ] Server integrates cleanly with BrowserSession (no conflicts)+- [ ] Graceful shutdown cleans all resources+- [ ] Works on macOS, Linux, Windowsdiff --git a/browser_use/skill_cli/IMPLEMENTATION_PLAN.md b/browser_use/skill_cli/IMPLEMENTATION_PLAN.mdnew file mode 100644index 000000000..663dc4546--- /dev/null+++ b/browser_use/skill_cli/IMPLEMENTATION_PLAN.md@@ -0,0 +1,916 @@+# Browser-Use CLI Implementation Plan++## Overview++This document outlines the implementation plan for the browser-use CLI as specified in CLI_SPEC.md.++## Architecture Summary++```+┌─────────────────────────────────────────────────────────────────────────────┐+│ FAST CLI (main.py) │+│ (stdlib only: <50ms startup) │+│ │+│ $ browser-use open https://example.com --session work --browser real │+│ $ browser-use python "data = browser.scrape('table')" │+│ $ browser-use run "fill the form" --session work # Requires API key │+└─────────────────────────────────────────────────────────────────────────────┘+ │+ Unix Socket │ /tmp/browser-use-{session}.sock+ ▼+┌─────────────────────────────────────────────────────────────────────────────┐+│ SESSION SERVER (server.py) │+│ (keeps BrowserSession instances alive) │+└─────────────────────────────────────────────────────────────────────────────┘+```++## File Structure++```+browser_use/cli/+├── __init__.py # Package init, expose main()+├── __main__.py # Entry: python -m browser_use.cli+│+├── main.py # Fast CLI (STDLIB ONLY!)+│ ├── Argument parsing (argparse)+│ ├── ensure_server()+│ ├── send_command()+│ └── main()+│+├── server.py # Session server+│ ├── SessionServer class+│ ├── Socket server (asyncio)+│ ├── Command dispatch+│ └── Graceful shutdown+│+├── sessions.py # Session registry+│ ├── SessionInfo dataclass+│ ├── SessionRegistry class+│ ├── create_browser_session()+│ └── Health checks+│+├── commands/ # Command handlers+│ ├── __init__.py+│ ├── browser.py # open, click, type, etc.+│ ├── python_exec.py # python command+│ ├── agent.py # run command (requires API key)+│ └── session.py # sessions, close+│+├── python_session.py # Jupyter-like REPL+│ ├── PythonSession class+│ ├── BrowserWrapper class+│ └── execute()+│+├── api_key.py # API key management+│ ├── require_api_key()+│ ├── prompt_for_api_key()+│ └── save_api_key()+│+├── protocol.py # Message types+│ ├── Request/Response+│ └── Serialization+│+└── utils.py # Helpers+ ├── Platform detection+ └── Path utilities+```++## Implementation Order++### Phase 1: Core Infrastructure+1. `protocol.py` - Message types for CLI↔Server communication+2. `utils.py` - Platform detection, socket paths, PID files+3. `main.py` - Fast CLI layer (stdlib only)+4. `server.py` - Basic socket server++### Phase 2: Session Management+5. `sessions.py` - Session registry+6. `api_key.py` - API key handling++### Phase 3: Commands+7. `commands/browser.py` - Basic browser control (open, click, type, etc.)+8. `commands/session.py` - Session management+9. `commands/python_exec.py` - Python execution+10. `commands/agent.py` - Agent tasks++### Phase 4: Python Execution+11. `python_session.py` - Jupyter-like REPL++### Phase 5: Integration+12. Update pyproject.toml entry point+13. Test all features+14. Create Claude skill description++## Implementation Details++### 1. protocol.py++```python+"""Wire protocol for CLI↔Server communication."""+from dataclasses import dataclass+from typing import Any+import json++@dataclass+class Request:+ id: str+ action: str+ session: str+ params: dict[str, Any]++ def to_json(self) -> str: ...+ @classmethod+ def from_json(cls, data: str) -> 'Request': ...++@dataclass+class Response:+ id: str+ success: bool+ data: Any = None+ error: str | None = None++ def to_json(self) -> str: ...+ @classmethod+ def from_json(cls, data: str) -> 'Response': ...+```++### 2. utils.py++```python+"""Platform utilities."""+import os+import sys+import tempfile+from pathlib import Path++def get_socket_path(session: str) -> str:+ """Get Unix socket path or TCP port for session."""+ if sys.platform == 'win32':+ # Windows: use TCP on deterministic port+ import hashlib+ port = 49152 + (int(hashlib.md5(session.encode()).hexdigest()[:4], 16) % 16383)+ return f"tcp://localhost:{port}"+ return f"/tmp/browser-use-{session}.sock"++def get_pid_path(session: str) -> Path:+ return Path(tempfile.gettempdir()) / f"browser-use-{session}.pid"++def is_server_running(session: str) -> bool: ...+def find_chrome_executable() -> str | None: ...+def get_chrome_profile_path(profile: str | None) -> str | None: ...+```++### 3. main.py (Critical: STDLIB ONLY)++```python+#!/usr/bin/env python3+"""Fast CLI for browser-use. STDLIB ONLY - must start in <50ms."""+import argparse+import json+import os+import socket+import subprocess+import sys+import time++def get_socket_path(session: str) -> str: ...+def get_pid_path(session: str) -> str: ...++def is_server_running(session: str) -> bool:+ pid_path = get_pid_path(session)+ if not pid_path.exists():+ return False+ try:+ pid = int(pid_path.read_text().strip())+ os.kill(pid, 0) # Check if process exists+ return True+ except (OSError, ValueError):+ return False++def ensure_server(session: str, browser: str, headed: bool, profile: str | None) -> bool:+ """Start server if not running. Returns True if started."""+ if is_server_running(session):+ # Try to connect to verify it's responsive+ try:+ conn = connect_to_server(session, timeout=0.05)+ conn.close()+ return False # Already running+ except:+ pass # Server dead, restart++ # Start server as background process+ cmd = [+ sys.executable, '-m', 'browser_use.cli.server',+ '--session', session,+ '--browser', browser,+ ]+ if headed:+ cmd.append('--headed')+ if profile:+ cmd.extend(['--profile', profile])++ subprocess.Popen(+ cmd,+ start_new_session=True,+ stdout=subprocess.DEVNULL,+ stderr=subprocess.DEVNULL,+ )++ # Wait for server to be ready+ for _ in range(50): # 2.5 seconds max+ if is_server_running(session):+ try:+ conn = connect_to_server(session, timeout=0.05)+ conn.close()+ return True+ except:+ pass+ time.sleep(0.05)++ print("Error: Failed to start server", file=sys.stderr)+ sys.exit(1)++def connect_to_server(session: str, timeout: float = 5.0) -> socket.socket:+ sock_path = get_socket_path(session)+ if sock_path.startswith('tcp://'):+ # Windows TCP+ host, port = sock_path[6:].split(':')+ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)+ sock.settimeout(timeout)+ sock.connect((host, int(port)))+ else:+ # Unix socket+ sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)+ sock.settimeout(timeout)+ sock.connect(sock_path)+ return sock++def send_command(session: str, action: str, params: dict) -> dict:+ import time+ request = {+ 'id': f'r{int(time.time() * 1000000) % 1000000}',+ 'action': action,+ 'session': session,+ 'params': params,+ }++ sock = connect_to_server(session)+ try:+ sock.sendall((json.dumps(request) + '\n').encode())++ # Read response+ data = b''+ while not data.endswith(b'\n'):+ chunk = sock.recv(4096)+ if not chunk:+ break+ data += chunk++ return json.loads(data.decode())+ finally:+ sock.close()++def main():+ parser = argparse.ArgumentParser(prog='browser-use', description='Browser automation CLI')+ parser.add_argument('--session', '-s', default='default', help='Session name')+ parser.add_argument('--browser', '-b', choices=['chromium', 'real', 'remote'], default='chromium')+ parser.add_argument('--headed', action='store_true', help='Show browser window')+ parser.add_argument('--profile', help='Chrome profile (real browser mode)')+ parser.add_argument('--json', action='store_true', help='JSON output')+ parser.add_argument('--api-key', help='API key override')++ subparsers = parser.add_subparsers(dest='command', required=True)++ # open <url>+ open_p = subparsers.add_parser('open', help='Navigate to URL')+ open_p.add_argument('url', help='URL to navigate to')++ # click <index>+ click_p = subparsers.add_parser('click', help='Click element')+ click_p.add_argument('index', type=int, help='Element index')++ # type <text>+ type_p = subparsers.add_parser('type', help='Type text')+ type_p.add_argument('text', help='Text to type')++ # ... more subparsers for all commands++ args = parser.parse_args()++ # Handle API key+ if args.api_key:+ os.environ['BROWSER_USE_API_KEY'] = args.api_key++ # Ensure server is running+ ensure_server(args.session, args.browser, args.headed, args.profile)++ # Build params from args+ params = vars(args).copy()+ del params['command']+ del params['session']+ del params['browser']+ del params['headed']+ del params['profile']+ del params['json']+ del params['api_key']++ # Send command+ response = send_command(args.session, args.command, params)++ # Output+ if args.json:+ print(json.dumps(response))+ else:+ if response.get('success'):+ if response.get('data'):+ print(response['data'])+ else:+ print(f"Error: {response.get('error')}", file=sys.stderr)+ sys.exit(1)++if __name__ == '__main__':+ main()+```++### 4. server.py++```python+"""Session server - keeps BrowserSession instances alive."""+import asyncio+import json+import os+import signal+import sys+from pathlib import Path++# Heavy imports OK here - server loads once and stays running+from browser_use.browser.session import BrowserSession+from browser_use.browser.profile import BrowserProfile+from browser_use.cli.sessions import SessionRegistry+from browser_use.cli.commands import browser, python_exec, agent, session++class SessionServer:+ def __init__(self, session_name: str, browser_mode: str, headed: bool, profile: str | None):+ self.session_name = session_name+ self.browser_mode = browser_mode+ self.headed = headed+ self.profile = profile+ self.registry = SessionRegistry()+ self.running = True++ async def handle_connection(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter):+ while True:+ try:+ line = await reader.readline()+ if not line:+ break++ request = json.loads(line.decode())+ response = await self.dispatch(request)+ writer.write((json.dumps(response) + '\n').encode())+ await writer.drain()++ except Exception as e:+ response = {'id': '', 'success': False, 'error': str(e)}+ writer.write((json.dumps(response) + '\n').encode())+ await writer.drain()++ writer.close()+ await writer.wait_closed()++ async def dispatch(self, request: dict) -> dict:+ action = request.get('action')+ params = request.get('params', {})+ req_id = request.get('id', '')++ try:+ # Get or create session+ session_info = await self.registry.get_or_create(+ self.session_name,+ self.browser_mode,+ self.headed,+ self.profile,+ )++ # Dispatch to handler+ if action in browser.COMMANDS:+ result = await browser.handle(action, session_info, params)+ elif action == 'python':+ result = await python_exec.handle(session_info, params)+ elif action == 'run':+ result = await agent.handle(session_info, params)+ elif action in session.COMMANDS:+ result = await session.handle(action, self.registry, params)+ elif action == 'close':+ await self.shutdown()+ result = {'closed': True}+ else:+ return {'id': req_id, 'success': False, 'error': f'Unknown action: {action}'}++ return {'id': req_id, 'success': True, 'data': result}++ except Exception as e:+ return {'id': req_id, 'success': False, 'error': str(e)}++ async def shutdown(self):+ self.running = False+ await self.registry.close_all()+ # Remove socket/PID files+ cleanup_files(self.session_name)++ async def run(self):+ # Write PID file+ pid_path = get_pid_path(self.session_name)+ pid_path.write_text(str(os.getpid()))++ # Setup signal handlers+ loop = asyncio.get_event_loop()+ for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):+ loop.add_signal_handler(sig, lambda: asyncio.create_task(self.shutdown()))++ # Start server+ sock_path = get_socket_path(self.session_name)+ if sock_path.startswith('tcp://'):+ host, port = sock_path[6:].split(':')+ server = await asyncio.start_server(+ self.handle_connection, host, int(port)+ )+ else:+ # Remove stale socket+ if os.path.exists(sock_path):+ os.unlink(sock_path)+ server = await asyncio.start_unix_server(+ self.handle_connection, sock_path+ )++ async with server:+ while self.running:+ await asyncio.sleep(0.1)++def main():+ import argparse+ parser = argparse.ArgumentParser()+ parser.add_argument('--session', required=True)+ parser.add_argument('--browser', default='chromium')+ parser.add_argument('--headed', action='store_true')+ parser.add_argument('--profile')+ args = parser.parse_args()++ server = SessionServer(args.session, args.browser, args.headed, args.profile)+ asyncio.run(server.run())++if __name__ == '__main__':+ main()+```++### 5. sessions.py++```python+"""Session registry - manages BrowserSession instances."""+from dataclasses import dataclass, field+from typing import Any++from browser_use.browser.session import BrowserSession+from browser_use.browser.profile import BrowserProfile+from browser_use.cli.python_session import PythonSession++@dataclass+class SessionInfo:+ name: str+ browser_mode: str+ headed: bool+ profile: str | None+ browser_session: BrowserSession+ python_session: PythonSession = field(default_factory=PythonSession)++class SessionRegistry:+ def __init__(self):+ self._sessions: dict[str, SessionInfo] = {}++ async def get_or_create(+ self,+ name: str,+ browser_mode: str,+ headed: bool,+ profile: str | None,+ ) -> SessionInfo:+ if name in self._sessions:+ return self._sessions[name]++ browser_session = await create_browser_session(+ browser_mode, headed, profile+ )+ await browser_session.start()++ session_info = SessionInfo(+ name=name,+ browser_mode=browser_mode,+ headed=headed,+ profile=profile,+ browser_session=browser_session,+ )+ self._sessions[name] = session_info+ return session_info++ def list_sessions(self) -> list[dict[str, Any]]:+ return [+ {+ 'name': s.name,+ 'browser_mode': s.browser_mode,+ 'headed': s.headed,+ }+ for s in self._sessions.values()+ ]++ async def close_session(self, name: str) -> bool:+ if name not in self._sessions:+ return False+ session = self._sessions.pop(name)+ await session.browser_session.kill()+ return True++ async def close_all(self):+ for session in self._sessions.values():+ try:+ await session.browser_session.kill()+ except:+ pass+ self._sessions.clear()++async def create_browser_session(+ mode: str,+ headed: bool,+ profile: str | None,+) -> BrowserSession:+ """Create BrowserSession based on mode."""+ if mode == 'chromium':+ return BrowserSession(+ headless=not headed,+ )++ elif mode == 'real':+ from browser_use.cli.utils import find_chrome_executable, get_chrome_profile_path+ return BrowserSession(+ executable_path=find_chrome_executable(),+ user_data_dir=get_chrome_profile_path(profile),+ headless=False, # Real browser always visible+ )++ elif mode == 'remote':+ from browser_use.cli.api_key import require_api_key+ require_api_key('Remote browser')+ return BrowserSession(+ use_cloud=True,+ )++ else:+ raise ValueError(f'Unknown browser mode: {mode}')+```++### 6. api_key.py++```python+"""API key management."""+import json+import os+import sys+from pathlib import Path++class APIKeyRequired(Exception):+ pass++def require_api_key(feature: str = 'this feature') -> str:+ """Get API key or raise helpful error."""++ # 1. Check environment+ key = os.environ.get('BROWSER_USE_API_KEY')+ if key:+ return key++ # 2. Check config file+ config_path = Path.home() / '.config' / 'browser-use' / 'config.json'+ if config_path.exists():+ try:+ config = json.loads(config_path.read_text())+ if key := config.get('api_key'):+ return key+ except:+ pass++ # 3. Interactive prompt (if TTY)+ if sys.stdin.isatty():+ return prompt_for_api_key(feature)++ # 4. Error with helpful message+ raise APIKeyRequired(f'''+╭─────────────────────────────────────────────────────────────╮+│ 🔑 Browser-Use API Key Required │+│ │+│ {feature} requires an API key. │+│ │+│ Get yours at: https://browser-use.com/dashboard │+│ │+│ Then set it via: │+│ export BROWSER_USE_API_KEY=your_key_here │+│ │+│ Or add to ~/.config/browser-use/config.json: │+│ {{"api_key": "your_key_here"}} │+╰─────────────────────────────────────────────────────────────╯+''')++def prompt_for_api_key(feature: str) -> str:+ """Interactive prompt for API key."""+ print(f'''+╭─────────────────────────────────────────────────────────────╮+│ 🔑 Browser-Use API Key Required │+│ │+│ {feature} requires an API key. │+│ Get yours at: https://browser-use.com/dashboard │+╰─────────────────────────────────────────────────────────────╯+''')+ key = input('Enter API key: ').strip()+ if not key:+ raise APIKeyRequired('No API key provided')++ save = input('Save to config? [y/N]: ').strip().lower()+ if save == 'y':+ save_api_key(key)++ return key++def save_api_key(key: str):+ """Save API key to config file."""+ config_path = Path.home() / '.config' / 'browser-use' / 'config.json'+ config_path.parent.mkdir(parents=True, exist_ok=True)++ config = {}+ if config_path.exists():+ try:+ config = json.loads(config_path.read_text())+ except:+ pass++ config['api_key'] = key+ config_path.write_text(json.dumps(config, indent=2))+ print(f'Saved to {config_path}')+```++### 7. python_session.py++```python+"""Jupyter-like persistent Python execution."""+import asyncio+import io+from contextlib import redirect_stdout+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any++from browser_use.browser.session import BrowserSession++@dataclass+class ExecutionResult:+ success: bool+ output: str = ''+ error: str | None = None++@dataclass+class PythonSession:+ """Jupyter-like persistent Python execution."""+ namespace: dict[str, Any] = field(default_factory=dict)+ execution_count: int = 0++ def __post_init__(self):+ # Pre-populate namespace with useful imports+ self.namespace.update({+ 'json': __import__('json'),+ 're': __import__('re'),+ 'Path': Path,+ })++ def execute(self, code: str, browser: BrowserSession) -> ExecutionResult:+ """Execute code in persistent namespace."""+ self.namespace['browser'] = BrowserWrapper(browser)+ self.execution_count += 1++ stdout = io.StringIO()+ try:+ with redirect_stdout(stdout):+ try:+ # Try as expression first (for REPL-like behavior)+ result = eval(code, self.namespace)+ if result is not None:+ print(repr(result))+ except SyntaxError:+ # Execute as statements+ exec(code, self.namespace)++ return ExecutionResult(success=True, output=stdout.getvalue())++ except Exception as e:+ return ExecutionResult(success=False, error=str(e), output=stdout.getvalue())++ def reset(self):+ """Clear namespace."""+ self.namespace.clear()+ self.__post_init__()++ def get_variables(self) -> dict[str, str]:+ """Get user-defined variables."""+ return {+ k: type(v).__name__+ for k, v in self.namespace.items()+ if not k.startswith('_') and k not in ('json', 're', 'Path', 'browser')+ }++class BrowserWrapper:+ """Convenient browser access for Python code."""++ def __init__(self, session: BrowserSession):+ self._session = session+ self._loop = asyncio.new_event_loop()++ def _run(self, coro):+ return self._loop.run_until_complete(coro)++ @property+ def url(self) -> str:+ # Get current URL from session+ return self._run(self._get_url())++ async def _get_url(self) -> str:+ state = await self._session.get_state()+ return state.url if state else ''++ def goto(self, url: str):+ """Navigate to URL."""+ self._run(self._session.navigate(url))++ def click(self, index: int):+ """Click element by index."""+ from browser_use.browser.events import ClickElementEvent+ self._run(self._session.event_bus.adispatch(+ ClickElementEvent(index=index)+ ))++ def type(self, text: str):+ """Type text."""+ from browser_use.browser.events import TypeTextEvent+ self._run(self._session.event_bus.adispatch(+ TypeTextEvent(text=text)+ ))++ def screenshot(self) -> bytes:+ """Take screenshot, return bytes."""+ return self._run(self._session.take_screenshot())++ @property+ def html(self) -> str:+ """Get page HTML."""+ return self._run(self._session.get_html())++ def scroll(self, direction: str = 'down', amount: int = 500):+ """Scroll page."""+ from browser_use.browser.events import ScrollEvent+ self._run(self._session.event_bus.adispatch(+ ScrollEvent(direction=direction, amount=amount)+ ))+```++### 8. commands/browser.py++```python+"""Browser control commands."""+from typing import Any+from browser_use.cli.sessions import SessionInfo+from browser_use.browser.events import (+ NavigateToUrlEvent,+ ClickElementEvent,+ TypeTextEvent,+ ScrollEvent,+ SendKeysEvent,+ SwitchTabEvent,+ CloseTabEvent,+)++COMMANDS = {+ 'open', 'click', 'type', 'input', 'scroll', 'back',+ 'screenshot', 'state', 'switch', 'close-tab', 'keys',+ 'select', 'eval', 'extract',+}++async def handle(action: str, session: SessionInfo, params: dict) -> Any:+ bs = session.browser_session++ if action == 'open':+ await bs.event_bus.adispatch(NavigateToUrlEvent(url=params['url']))+ return {'url': params['url']}++ elif action == 'click':+ await bs.event_bus.adispatch(ClickElementEvent(index=params['index']))+ return {'clicked': params['index']}++ elif action == 'type':+ await bs.event_bus.adispatch(TypeTextEvent(text=params['text']))+ return {'typed': params['text']}++ elif action == 'input':+ await bs.event_bus.adispatch(ClickElementEvent(index=params['index']))+ await bs.event_bus.adispatch(TypeTextEvent(text=params['text']))+ return {'input': params['text'], 'to': params['index']}++ elif action == 'scroll':+ direction = params.get('direction', 'down')+ await bs.event_bus.adispatch(ScrollEvent(direction=direction))+ return {'scrolled': direction}++ elif action == 'back':+ # TODO: Implement back navigation+ return {'back': True}++ elif action == 'screenshot':+ data = await bs.take_screenshot()+ if params.get('path'):+ from pathlib import Path+ Path(params['path']).write_bytes(data)+ return {'saved': params['path']}+ import base64+ return {'screenshot': base64.b64encode(data).decode()}++ elif action == 'state':+ state = await bs.get_state()+ return {+ 'url': state.url if state else '',+ 'title': state.title if state else '',+ }++ elif action == 'switch':+ await bs.event_bus.adispatch(SwitchTabEvent(tab_index=params['tab']))+ return {'switched': params['tab']}++ elif action == 'close-tab':+ await bs.event_bus.adispatch(CloseTabEvent(tab_index=params.get('tab')))+ return {'closed': params.get('tab')}++ elif action == 'keys':+ await bs.event_bus.adispatch(SendKeysEvent(keys=params['keys']))+ return {'sent': params['keys']}++ elif action == 'eval':+ # TODO: Implement JS eval+ return {'eval': params['js']}++ elif action == 'extract':+ # TODO: Implement LLM extraction+ return {'query': params['query']}++ raise ValueError(f'Unknown browser action: {action}')+```++### 9. Claude Skill Description++Located at: `skills/browser-use/SKILL.md`++## Testing Plan++1. **Unit Tests**+ - Protocol serialization+ - Session registry operations+ - API key handling++2. **Integration Tests**+ - Server startup/shutdown+ - CLI↔Server communication+ - Browser session creation++3. **E2E Tests**+ - Full workflow: open → click → type → screenshot+ - Python execution with variable persistence+ - Multi-session isolation++## Open Questions++1. **Real Browser Detection**: How to reliably find Chrome on different platforms?+ - macOS: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`+ - Linux: `which google-chrome` or `which chromium`+ - Windows: Check registry or common paths++2. **Cloud Proxy Configuration**: The spec mentions `--proxy residential` for remote mode. Need to verify CloudBrowserParams supports this.++3. **Agent Task Implementation**: The `run` command requires the full Agent class. Need to determine:+ - Which LLM to use (from config?)+ - How to stream output back to CLI++4. **Event Loop Management**: The Python session needs to run async browser methods from sync code. Current approach uses a separate event loop but this may conflict with the server's loop.++5. **Backward Compatibility**: The existing `browser_use/cli.py` is a TUI app. We need to:+ - Keep the TUI as a separate command (`browser-use tui`)?+ - Or replace it entirely?++## Notes++- The CLI layer (main.py) MUST only use stdlib imports for <50ms startup+- All heavy imports go in the server layer+- Use Unix sockets on macOS/Linux, TCP on Windows+- Session names allow parallel browser instances+- API key is only required for remote browsers and agent tasksdiff --git a/browser_use/skill_cli/OPEN_QUESTIONS.md b/browser_use/skill_cli/OPEN_QUESTIONS.mdnew file mode 100644index 000000000..270c6df81--- /dev/null+++ b/browser_use/skill_cli/OPEN_QUESTIONS.md@@ -0,0 +1,171 @@+# Browser-Use CLI: Open Questions & Implementation Notes++## Implementation Status++### Completed Features+- [x] Fast CLI layer (stdlib only, <50ms startup)+- [x] Session server with Unix socket IPC (TCP on Windows)+- [x] Session registry with named sessions+- [x] Browser modes: chromium, real, remote+- [x] Browser commands: open, click, type, input, scroll, back, screenshot, state, switch, close-tab, keys, select, eval+- [x] Python execution with persistent namespace (Jupyter-like REPL)+- [x] API key management with environment, config file, and interactive prompt support+- [x] Agent task execution (basic implementation)+- [x] JSON output mode+- [x] Claude skill description (SKILL.md)++### Features Not Fully Implemented+- [ ] `extract` command - Returns placeholder, needs LLM integration+- [ ] Agent task `run` command - Basic implementation, may need tuning+- [ ] Cloud browser proxy configuration (`--proxy residential`)++## Open Questions++### 1. TUI vs CLI Coexistence++**Current State**:+- The existing `browser_use/cli.py` is a Textual TUI application+- The new CLI is in `browser_use/skill_cli/` with entry point `bu`+- Both coexist: `browser-use` launches TUI, `bu` launches fast CLI++**Question**: Should we:+1. Keep both (`browser-use` = TUI, `bu` = fast CLI)+2. Replace TUI with fast CLI (`browser-use` = fast CLI, deprecate TUI)+3. Make TUI a subcommand (`browser-use tui`, `browser-use` = fast CLI)++**Recommendation**: Option 3 - Make TUI accessible via `browser-use tui` and have `browser-use` launch the fast CLI. This provides a migration path.++### 2. Agent Task LLM Configuration++**Current State**:+The `run` command tries to auto-detect LLM from environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY).++**Question**: Should we:+1. Require explicit LLM configuration in `~/.config/browser-use/config.json`+2. Keep auto-detection from environment+3. Add `--llm` flag to specify model++**Recommendation**: Keep auto-detection, add optional `--llm` flag for overrides.++### 3. Remote Browser Proxy Configuration++**Spec mentions**: `--proxy residential` for remote browser mode++**Current State**: Not implemented. The `CloudBrowserParams` supports `proxy_country_code` but not proxy type.++**Question**: What proxy types does Browser-Use Cloud support?+- residential+- datacenter+- none++**Action Needed**: Verify with Browser-Use Cloud API documentation.++### 4. Real Browser Mode Profile Handling++**Current State**:+- `--profile NAME` passes the profile name to `user_data_dir`+- This may not work correctly as Chrome expects specific paths++**Question**: How should profile selection work?+1. Pass profile name as subdirectory+2. Use Chrome's `--profile-directory` flag+3. Let user specify full path++**Recommendation**: Support both `--profile "Profile 1"` (Chrome's named profile) and `--user-data-dir /path` for full control.++### 5. Session Cleanup on Server Restart++**Current State**:+- Server writes PID and socket files to temp directory+- On shutdown, files are cleaned up+- If server crashes, files may remain++**Question**: Should we:+1. Clean up stale files on CLI startup+2. Add a `bu server clean` command+3. Both++**Recommendation**: Clean up stale files on startup (check if PID exists, if not, remove socket).++### 6. Event Loop Handling in Python Session++**Current State**:+The `BrowserWrapper` in `python_session.py` uses `concurrent.futures.ThreadPoolExecutor` to run async operations from sync context.++**Potential Issues**:+- May conflict with the server's event loop+- Thread pool overhead++**Question**: Is there a better approach? Consider:+1. Using `asyncio.run_coroutine_threadsafe()`+2. Making Python execution async and handling differently++### 7. Browser State Element Indices++**Current State**:+The `state` command returns elements from `dom_state.selector_map` with their original indices.++**Observation**: Indices are not sequential (e.g., 18, 19, 20...). This is because they're mapped to actual DOM elements.++**Question**: Should we:+1. Keep original indices (consistent with how the agent works)+2. Re-number 0, 1, 2... (easier for humans but may cause confusion)++**Recommendation**: Keep original indices for consistency with agent.++## Architecture Notes++### Socket Communication+- Unix sockets on macOS/Linux: `/var/.../browser-use-{session}.sock`+- TCP on Windows: `tcp://localhost:{port}` where port is hash-derived+- Line-delimited JSON protocol++### Session Lifecycle+```+CLI Command → ensure_server() → connect_to_server() → send_command()+ ↓+ (if not running)+ ↓+ spawn server process+ ↓+ wait for socket ready+```++### Server Architecture+```+SessionServer+ ├── SessionRegistry (manages BrowserSession instances)+ ├── Socket Server (asyncio.start_unix_server)+ └── Command Dispatch+ ├── browser.py (open, click, type, etc.)+ ├── python_exec.py (Python REPL)+ ├── agent.py (run command)+ └── session.py (sessions, close)+```++## Testing Notes++All basic features have been tested:+- `bu open <url>` - Works (headed and headless)+- `bu state` - Works (returns elements with indices)+- `bu click <index>` - Works+- `bu type "text"` - Works+- `bu screenshot` - Works (base64 and file output)+- `bu eval "js"` - Works (returns JS result)+- `bu python "code"` - Works (persistent namespace)+- `bu python --vars` - Works+- `bu close` - Works+- `bu server status/stop` - Works+- `--json` mode - Works+- `--headed` mode - Works++## Future Improvements++1. **Streaming Output**: For long-running agent tasks, stream progress updates+2. **Tab Completion**: Add shell completion for commands+3. **History**: Remember command history across sessions+4. **Config File**: Support more configuration options+5. **Plugins**: Allow extending with custom commands+6. **HTTP API**: Add REST endpoint for programmatic access+7. **Watch Mode**: Re-run Python on file changes+8. **Notebook Export**: Export Python session as .ipynbdiff --git a/browser_use/skill_cli/__init__.py b/browser_use/skill_cli/__init__.pynew file mode 100644index 000000000..7c45f5652--- /dev/null+++ b/browser_use/skill_cli/__init__.py@@ -0,0 +1,17 @@+"""Browser-use CLI package.++This package provides a fast command-line interface for browser automation.+The CLI uses a session server architecture for persistent browser sessions.++Usage:+ browser-use open https://example.com+ browser-use click 5+ browser-use type "Hello World"+ browser-use python "print(browser.url)"+ browser-use run "Fill the contact form"+ browser-use close+"""++from browser_use.skill_cli.main import main++__all__ = ['main']diff --git a/browser_use/skill_cli/__main__.py b/browser_use/skill_cli/__main__.pynew file mode 100644index 000000000..84b20bf71--- /dev/null+++ b/browser_use/skill_cli/__main__.py@@ -0,0 +1,8 @@+"""Entry point for: python -m browser_use.skill_cli"""++import sys++from browser_use.skill_cli.main import main++if __name__ == '__main__':+ sys.exit(main())diff --git a/browser_use/skill_cli/api_key.py b/browser_use/skill_cli/api_key.pynew file mode 100644index 000000000..4d5db73a7--- /dev/null+++ b/browser_use/skill_cli/api_key.py@@ -0,0 +1,125 @@+"""API key management for browser-use CLI."""++import json+import os+import sys+from pathlib import Path+++class APIKeyRequired(Exception):+ """Raised when API key is required but not provided."""++ pass+++def get_config_path() -> Path:+ """Get browser-use config file path."""+ if sys.platform == 'win32':+ base = Path(os.environ.get('APPDATA', Path.home()))+ else:+ base = Path(os.environ.get('XDG_CONFIG_HOME', Path.home() / '.config'))+ return base / 'browser-use' / 'config.json'+++def require_api_key(feature: str = 'this feature') -> str:+ """Get API key or raise helpful error.++ Checks in order:+ 1. BROWSER_USE_API_KEY environment variable+ 2. Config file (~/.config/browser-use/config.json)+ 3. Interactive prompt (if TTY)+ 4. Raises APIKeyRequired with helpful message+ """+ # 1. Check environment+ key = os.environ.get('BROWSER_USE_API_KEY')+ if key:+ return key++ # 2. Check config file+ config_path = get_config_path()+ if config_path.exists():+ try:+ config = json.loads(config_path.read_text())+ if key := config.get('api_key'):+ return key+ except Exception:+ pass++ # 3. Interactive prompt (if TTY)+ if sys.stdin.isatty() and sys.stdout.isatty():+ return prompt_for_api_key(feature)++ # 4. Error with helpful message+ raise APIKeyRequired(+ f"""+╭─────────────────────────────────────────────────────────────╮+│ 🔑 Browser-Use API Key Required │+│ │+│ {feature} requires an API key. │+│ │+│ Get yours at: https://browser-use.com/dashboard │+│ │+│ Then set it via: │+│ export BROWSER_USE_API_KEY=your_key_here │+│ │+│ Or add to {config_path}: │+│ {{"api_key": "your_key_here"}} │+╰─────────────────────────────────────────────────────────────╯+"""+ )+++def prompt_for_api_key(feature: str) -> str:+ """Interactive prompt for API key."""+ print(+ f"""+╭─────────────────────────────────────────────────────────────╮+│ 🔑 Browser-Use API Key Required │+│ │+│ {feature} requires an API key. │+│ Get yours at: https://browser-use.com/dashboard │+╰─────────────────────────────────────────────────────────────╯+"""+ )++ try:+ key = input('Enter API key: ').strip()+ except (EOFError, KeyboardInterrupt):+ raise APIKeyRequired('No API key provided')++ if not key:+ raise APIKeyRequired('No API key provided')++ try:+ save = input('Save to config? [y/N]: ').strip().lower()+ if save == 'y':+ save_api_key(key)+ except (EOFError, KeyboardInterrupt):+ pass++ return key+++def save_api_key(key: str) -> None:+ """Save API key to config file."""+ config_path = get_config_path()+ config_path.parent.mkdir(parents=True, exist_ok=True)++ config: dict = {}+ if config_path.exists():+ try:+ config = json.loads(config_path.read_text())+ except Exception:+ pass++ config['api_key'] = key+ config_path.write_text(json.dumps(config, indent=2))+ print(f'Saved to {config_path}')+++def get_api_key() -> str | None:+ """Get API key if available, without raising error."""+ try:+ return require_api_key('API key check')+ except APIKeyRequired:+ return Nonediff --git a/browser_use/skill_cli/commands/__init__.py b/browser_use/skill_cli/commands/__init__.pynew file mode 100644index 000000000..c1208e027--- /dev/null+++ b/browser_use/skill_cli/commands/__init__.py@@ -0,0 +1,5 @@+"""Command handlers for browser-use CLI."""++from browser_use.skill_cli.commands import agent, browser, python_exec, session++__all__ = ['browser', 'python_exec', 'agent', 'session']diff --git a/browser_use/skill_cli/commands/agent.py b/browser_use/skill_cli/commands/agent.pynew file mode 100644index 000000000..5029c632b--- /dev/null+++ b/browser_use/skill_cli/commands/agent.py@@ -0,0 +1,110 @@+"""Agent task command handler."""++import logging+import os+from typing import Any++from browser_use.skill_cli.api_key import APIKeyRequired, require_api_key+from browser_use.skill_cli.sessions import SessionInfo++logger = logging.getLogger(__name__)+++async def handle(session: SessionInfo, params: dict[str, Any]) -> Any:+ """Handle agent run command.++ Requires API key for LLM access.+ Runs a browser-use agent with the given task.+ """+ task = params.get('task')+ max_steps = params.get('max_steps', 100)++ if not task:+ return {'success': False, 'error': 'No task provided'}++ # Check API key for LLM access+ try:+ api_key = require_api_key('Agent tasks')+ except APIKeyRequired as e:+ return {'success': False, 'error': str(e)}++ try:+ # Import agent and LLM+ from browser_use.agent.service import Agent++ # Try to get LLM from environment+ llm = await get_llm()+ if llm is None:+ return {+ 'success': False,+ 'error': 'No LLM configured. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY',+ }++ # Create and run agent+ agent = Agent(+ task=task,+ llm=llm,+ browser_session=session.browser_session,+ )++ logger.info(f'Running agent task: {task}')+ result = await agent.run(max_steps=max_steps)++ # Extract result info+ final_result = result.final_result() if result else None++ return {+ 'success': True,+ 'task': task,+ 'steps': len(result) if result else 0,+ 'result': str(final_result) if final_result else None,+ 'done': result.is_done() if result else False,+ }++ except Exception as e:+ logger.exception(f'Agent task failed: {e}')+ return {+ 'success': False,+ 'error': str(e),+ 'task': task,+ }+++async def get_llm() -> Any:+ """Get LLM instance from environment configuration."""+ # Try OpenAI first+ if os.environ.get('OPENAI_API_KEY'):+ try:+ from langchain_openai import ChatOpenAI # type: ignore[import-not-found]++ return ChatOpenAI(model='gpt-4o') # type: ignore[return-value]+ except ImportError:+ pass++ # Try Anthropic+ if os.environ.get('ANTHROPIC_API_KEY'):+ try:+ from langchain_anthropic import ChatAnthropic # type: ignore[import-not-found]++ return ChatAnthropic(model='claude-sonnet-4-20250514') # type: ignore[return-value]+ except ImportError:+ pass++ # Try Google+ if os.environ.get('GOOGLE_API_KEY'):+ try:+ from langchain_google_genai import ChatGoogleGenerativeAI # type: ignore[import-not-found]++ return ChatGoogleGenerativeAI(model='gemini-2.0-flash') # type: ignore[return-value]+ except ImportError:+ pass++ # Try to use browser-use's default LLM setup+ try:+ from browser_use.llm import get_default_llm++ return get_default_llm() # type: ignore[return-value]+ except Exception:+ pass++ return Nonediff --git a/browser_use/skill_cli/commands/browser.py b/browser_use/skill_cli/commands/browser.pynew file mode 100644index 000000000..f5c2a5a37--- /dev/null+++ b/browser_use/skill_cli/commands/browser.py@@ -0,0 +1,206 @@+"""Browser control commands."""++import base64+import logging+from pathlib import Path+from typing import Any++from browser_use.skill_cli.sessions import SessionInfo++logger = logging.getLogger(__name__)++COMMANDS = {+ 'open',+ 'click',+ 'type',+ 'input',+ 'scroll',+ 'back',+ 'screenshot',+ 'state',+ 'switch',+ 'close-tab',+ 'keys',+ 'select',+ 'eval',+ 'extract',+}+++async def _execute_js(session: SessionInfo, js: str) -> Any:+ """Execute JavaScript in the browser via CDP."""+ bs = session.browser_session+ # Get or create a CDP session for the focused target+ cdp_session = await bs.get_or_create_cdp_session(target_id=None, focus=False)+ if not cdp_session:+ raise RuntimeError('No active browser session')++ result = await cdp_session.cdp_client.send.Runtime.evaluate(+ params={'expression': js, 'returnByValue': True},+ session_id=cdp_session.session_id,+ )+ return result.get('result', {}).get('value')+++async def handle(action: str, session: SessionInfo, params: dict[str, Any]) -> Any:+ """Handle browser control command."""+ bs = session.browser_session++ if action == 'open':+ url = params['url']+ # Ensure URL has scheme+ if not url.startswith(('http://', 'https://', 'file://')):+ url = 'https://' + url++ from browser_use.browser.events import NavigateToUrlEvent++ await bs.event_bus.dispatch(NavigateToUrlEvent(url=url))+ return {'url': url, 'success': True}++ elif action == 'click':+ from browser_use.browser.events import ClickElementEvent++ index = params['index']+ # Look up node from selector map+ node = await bs.get_element_by_index(index)+ if node is None:+ return {'error': f'Element index {index} not found - page may have changed'}+ await bs.event_bus.dispatch(ClickElementEvent(node=node))+ return {'clicked': index}++ elif action == 'type':+ # Type into currently focused element using CDP directly+ text = params['text']+ cdp_session = await bs.get_or_create_cdp_session(target_id=None, focus=False)+ if not cdp_session:+ return {'error': 'No active browser session'}+ await cdp_session.cdp_client.send.Input.insertText(+ params={'text': text},+ session_id=cdp_session.session_id,+ )+ return {'typed': text}++ elif action == 'input':+ from browser_use.browser.events import ClickElementEvent, TypeTextEvent++ index = params['index']+ text = params['text']+ # Look up node from selector map+ node = await bs.get_element_by_index(index)+ if node is None:+ return {'error': f'Element index {index} not found - page may have changed'}+ await bs.event_bus.dispatch(ClickElementEvent(node=node))+ await bs.event_bus.dispatch(TypeTextEvent(node=node, text=text))+ return {'input': text, 'element': index}++ elif action == 'scroll':+ from browser_use.browser.events import ScrollEvent++ direction = params.get('direction', 'down')+ amount = params.get('amount', 500)+ await bs.event_bus.dispatch(ScrollEvent(direction=direction, amount=amount))+ return {'scrolled': direction, 'amount': amount}++ elif action == 'back':+ from browser_use.browser.events import GoBackEvent++ await bs.event_bus.dispatch(GoBackEvent())+ return {'back': True}++ elif action == 'screenshot':+ data = await bs.take_screenshot(full_page=params.get('full', False))++ if params.get('path'):+ path = Path(params['path'])+ path.write_bytes(data)+ return {'saved': str(path), 'size': len(data)}++ # Return base64 encoded+ return {'screenshot': base64.b64encode(data).decode(), 'size': len(data)}++ elif action == 'state':+ state = await bs.get_browser_state_summary(include_screenshot=False)+ if state:+ # Build element list with indices from DOM state+ elements = []+ if state.dom_state and state.dom_state.selector_map:+ for idx, elem in state.dom_state.selector_map.items():+ elements.append(+ {+ 'index': idx,+ 'tag': getattr(elem, 'tag_name', ''),+ 'text': (getattr(elem, 'text', '') or '')[:50],+ 'role': getattr(elem, 'role', ''),+ }+ )++ return {+ 'url': state.url,+ 'title': state.title,+ 'element_count': len(elements),+ 'elements': elements[:20], # Return first 20 elements+ }+ return {'url': '', 'title': '', 'elements': []}++ elif action == 'switch':+ from browser_use.browser.events import SwitchTabEvent++ tab_index = params['tab']+ # Get target_id from tab index+ page_targets = bs.session_manager.get_all_page_targets() if bs.session_manager else []+ if tab_index < 0 or tab_index >= len(page_targets):+ return {'error': f'Invalid tab index {tab_index}. Available: 0-{len(page_targets) - 1}'}+ target_id = page_targets[tab_index].target_id+ await bs.event_bus.dispatch(SwitchTabEvent(target_id=target_id))+ return {'switched': tab_index}++ elif action == 'close-tab':+ from browser_use.browser.events import CloseTabEvent++ tab_index = params.get('tab')+ # Get target_id from tab index+ page_targets = bs.session_manager.get_all_page_targets() if bs.session_manager else []+ if tab_index is not None:+ if tab_index < 0 or tab_index >= len(page_targets):+ return {'error': f'Invalid tab index {tab_index}. Available: 0-{len(page_targets) - 1}'}+ target_id = page_targets[tab_index].target_id+ else:+ # Close current/focused tab+ target_id = bs.session_manager.get_focused_target().target_id if bs.session_manager else None+ if not target_id:+ return {'error': 'No focused tab to close'}+ await bs.event_bus.dispatch(CloseTabEvent(target_id=target_id))+ return {'closed': tab_index}++ elif action == 'keys':+ from browser_use.browser.events import SendKeysEvent++ keys = params['keys']+ await bs.event_bus.dispatch(SendKeysEvent(keys=keys))+ return {'sent': keys}++ elif action == 'select':+ from browser_use.browser.events import SelectDropdownOptionEvent++ index = params['index']+ value = params['value']+ # Look up node from selector map+ node = await bs.get_element_by_index(index)+ if node is None:+ return {'error': f'Element index {index} not found - page may have changed'}+ await bs.event_bus.dispatch(SelectDropdownOptionEvent(node=node, text=value))+ return {'selected': value, 'element': index}++ elif action == 'eval':+ js = params['js']+ # Execute JavaScript via CDP+ result = await _execute_js(session, js)+ return {'result': result}++ elif action == 'extract':+ query = params['query']+ # This requires LLM integration+ # For now, return a placeholder+ return {'query': query, 'error': 'extract requires agent mode - use: browser-use run "extract ..."'}++ raise ValueError(f'Unknown browser action: {action}')diff --git a/browser_use/skill_cli/commands/python_exec.py b/browser_use/skill_cli/commands/python_exec.pynew file mode 100644index 000000000..0bcbbcfa4--- /dev/null+++ b/browser_use/skill_cli/commands/python_exec.py@@ -0,0 +1,64 @@+"""Python execution command handler."""++import asyncio+import logging+from pathlib import Path+from typing import Any++from browser_use.skill_cli.sessions import SessionInfo++logger = logging.getLogger(__name__)+++async def handle(session: SessionInfo, params: dict[str, Any]) -> Any:+ """Handle python command.++ Supports:+ - python "<code>" - Execute Python code+ - python --file script.py - Execute Python file+ - python --reset - Reset namespace+ - python --vars - Show defined variables+ """+ python_session = session.python_session+ browser_session = session.browser_session++ # Handle --reset+ if params.get('reset'):+ python_session.reset()+ return {'reset': True, 'message': 'Python namespace cleared'}++ # Handle --vars+ if params.get('vars'):+ variables = python_session.get_variables()+ return {'variables': variables, 'count': len(variables)}++ # Get code to execute+ code = params.get('code')++ # Handle --file+ if params.get('file'):+ file_path = Path(params['file'])+ if not file_path.exists():+ return {'success': False, 'error': f'File not found: {file_path}'}+ code = file_path.read_text()++ if not code:+ return {'success': False, 'error': 'No code provided. Use: python "<code>" or --file script.py'}++ # Execute code in a thread pool so browser operations can schedule back to the event loop+ loop = asyncio.get_running_loop()+ result = await loop.run_in_executor(None, python_session.execute, code, browser_session, loop)++ if result.success:+ return {+ 'success': True,+ 'output': result.output,+ 'execution_count': python_session.execution_count,+ }+ else:+ return {+ 'success': False,+ 'output': result.output,+ 'error': result.error,+ 'execution_count': python_session.execution_count,+ }diff --git a/browser_use/skill_cli/commands/session.py b/browser_use/skill_cli/commands/session.pynew file mode 100644index 000000000..5466a804e--- /dev/null+++ b/browser_use/skill_cli/commands/session.py@@ -0,0 +1,41 @@+"""Session management command handlers."""++import logging+from typing import TYPE_CHECKING, Any++if TYPE_CHECKING:+ from browser_use.skill_cli.sessions import SessionRegistry++logger = logging.getLogger(__name__)++COMMANDS = {'sessions', 'close'}+++async def handle(action: str, registry: 'SessionRegistry', params: dict[str, Any]) -> Any:+ """Handle session management command."""+ if action == 'sessions':+ sessions = registry.list_sessions()+ return {+ 'sessions': sessions,+ 'count': len(sessions),+ }++ elif action == 'close':+ if params.get('all'):+ # Close all sessions+ sessions = registry.list_sessions()+ await registry.close_all()+ return {+ 'closed': [s['name'] for s in sessions],+ 'count': len(sessions),+ }+ else:+ # Close current session+ name = params.get('session', 'default')+ success = await registry.close_session(name)+ if success:+ return {'closed': name}+ else:+ return {'error': f'Session not found: {name}'}++ raise ValueError(f'Unknown session action: {action}')diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pynew file mode 100755index 000000000..bd5d760c5--- /dev/null+++ b/browser_use/skill_cli/main.py@@ -0,0 +1,410 @@+#!/usr/bin/env python3+"""Fast CLI for browser-use. STDLIB ONLY - must start in <50ms.++This is the main entry point for the browser-use CLI. It uses only stdlib+imports to ensure fast startup, delegating heavy operations to the session+server which loads once and stays running.+"""++import argparse+import hashlib+import json+import os+import socket+import subprocess+import sys+import tempfile+import time+from pathlib import Path++# =============================================================================+# Utility functions (inlined to avoid imports)+# =============================================================================+++def get_socket_path(session: str) -> str:+ """Get socket path for session."""+ if sys.platform == 'win32':+ port = 49152 + (int(hashlib.md5(session.encode()).hexdigest()[:4], 16) % 16383)+ return f'tcp://localhost:{port}'+ return str(Path(tempfile.gettempdir()) / f'browser-use-{session}.sock')+++def get_pid_path(session: str) -> Path:+ """Get PID file path for session."""+ return Path(tempfile.gettempdir()) / f'browser-use-{session}.pid'+++def is_server_running(session: str) -> bool:+ """Check if server is running for session."""+ pid_path = get_pid_path(session)+ if not pid_path.exists():+ return False+ try:+ pid = int(pid_path.read_text().strip())+ os.kill(pid, 0)+ return True+ except (OSError, ValueError):+ return False+++def connect_to_server(session: str, timeout: float = 60.0) -> socket.socket:+ """Connect to session server."""+ sock_path = get_socket_path(session)++ if sock_path.startswith('tcp://'):+ # Windows: TCP connection+ _, hostport = sock_path.split('://', 1)+ host, port = hostport.split(':')+ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)+ sock.settimeout(timeout)+ sock.connect((host, int(port)))+ else:+ # Unix socket+ sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)+ sock.settimeout(timeout)+ sock.connect(sock_path)++ return sock+++def ensure_server(session: str, browser: str, headed: bool, profile: str | None, api_key: str | None) -> bool:+ """Start server if not running. Returns True if started."""+ # Check if server is already running and responsive+ if is_server_running(session):+ try:+ sock = connect_to_server(session, timeout=0.1)+ sock.close()+ return False # Already running+ except Exception:+ pass # Server dead, restart++ # Build server command+ cmd = [+ sys.executable,+ '-m',+ 'browser_use.skill_cli.server',+ '--session',+ session,+ '--browser',+ browser,+ ]+ if headed:+ cmd.append('--headed')+ if profile:+ cmd.extend(['--profile', profile])++ # Set up environment+ env = os.environ.copy()+ if api_key:+ env['BROWSER_USE_API_KEY'] = api_key++ # Start server as background process+ if sys.platform == 'win32':+ # Windows: use CREATE_NEW_PROCESS_GROUP+ subprocess.Popen(+ cmd,+ env=env,+ creationflags=subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS,+ stdout=subprocess.DEVNULL,+ stderr=subprocess.DEVNULL,+ )+ else:+ # Unix: use start_new_session+ subprocess.Popen(+ cmd,+ env=env,+ start_new_session=True,+ stdout=subprocess.DEVNULL,+ stderr=subprocess.DEVNULL,+ )++ # Wait for server to be ready+ for _ in range(100): # 5 seconds max+ if is_server_running(session):+ try:+ sock = connect_to_server(session, timeout=0.1)+ sock.close()+ return True+ except Exception:+ pass+ time.sleep(0.05)++ print('Error: Failed to start session server', file=sys.stderr)+ sys.exit(1)+++def send_command(session: str, action: str, params: dict) -> dict:+ """Send command to server and get response."""+ request = {+ 'id': f'r{int(time.time() * 1000000) % 1000000}',+ 'action': action,+ 'session': session,+ 'params': params,+ }++ sock = connect_to_server(session)+ try:+ # Send request+ sock.sendall((json.dumps(request) + '\n').encode())++ # Read response+ data = b''+ while not data.endswith(b'\n'):+ chunk = sock.recv(4096)+ if not chunk:+ break+ data += chunk++ if not data:+ return {'id': request['id'], 'success': False, 'error': 'No response from server'}++ return json.loads(data.decode())+ finally:+ sock.close()+++# =============================================================================+# CLI Commands+# =============================================================================+++def build_parser() -> argparse.ArgumentParser:+ """Build argument parser with all commands."""+ parser = argparse.ArgumentParser(+ prog='browser-use',+ description='Browser automation CLI for browser-use',+ formatter_class=argparse.RawDescriptionHelpFormatter,+ epilog="""+Examples:+ browser-use open https://example.com+ browser-use click 5+ browser-use type "Hello World"+ browser-use python "print(browser.url)"+ browser-use run "Fill the contact form"+ browser-use sessions+ browser-use close+""",+ )++ # Global flags+ parser.add_argument('--session', '-s', default='default', help='Session name (default: default)')+ parser.add_argument('--browser', '-b', choices=['chromium', 'real', 'remote'], default='chromium', help='Browser mode')+ parser.add_argument('--headed', action='store_true', help='Show browser window')+ parser.add_argument('--profile', help='Chrome profile (real browser mode)')+ parser.add_argument('--json', action='store_true', help='Output as JSON')+ parser.add_argument('--api-key', help='Browser-Use API key')++ subparsers = parser.add_subparsers(dest='command', help='Command to execute')++ # -------------------------------------------------------------------------+ # Browser Control Commands+ # -------------------------------------------------------------------------++ # open <url>+ p = subparsers.add_parser('open', help='Navigate to URL')+ p.add_argument('url', help='URL to navigate to')++ # click <index>+ p = subparsers.add_parser('click', help='Click element by index')+ p.add_argument('index', type=int, help='Element index from state')++ # type <text>+ p = subparsers.add_parser('type', help='Type text')+ p.add_argument('text', help='Text to type')++ # input <index> <text>+ p = subparsers.add_parser('input', help='Type text into specific element')+ p.add_argument('index', type=int, help='Element index')+ p.add_argument('text', help='Text to type')++ # scroll [up|down]+ p = subparsers.add_parser('scroll', help='Scroll page')+ p.add_argument('direction', nargs='?', default='down', choices=['up', 'down'], help='Scroll direction')+ p.add_argument('--amount', type=int, default=500, help='Scroll amount in pixels')++ # back+ subparsers.add_parser('back', help='Go back in history')++ # screenshot [path]+ p = subparsers.add_parser('screenshot', help='Take screenshot')+ p.add_argument('path', nargs='?', help='Save path (outputs base64 if not provided)')+ p.add_argument('--full', action='store_true', help='Full page screenshot')++ # state+ subparsers.add_parser('state', help='Get browser state (URL, title, elements)')++ # switch <tab>+ p = subparsers.add_parser('switch', help='Switch to tab')+ p.add_argument('tab', type=int, help='Tab index')++ # close-tab [tab]+ p = subparsers.add_parser('close-tab', help='Close tab')+ p.add_argument('tab', type=int, nargs='?', help='Tab index (current if not specified)')++ # keys <keys>+ p = subparsers.add_parser('keys', help='Send keyboard keys')+ p.add_argument('keys', help='Keys to send (e.g., "Enter", "Control+a")')++ # select <index> <value>+ p = subparsers.add_parser('select', help='Select dropdown option')+ p.add_argument('index', type=int, help='Element index')+ p.add_argument('value', help='Value to select')++ # eval <js>+ p = subparsers.add_parser('eval', help='Execute JavaScript')+ p.add_argument('js', help='JavaScript code to execute')++ # extract <query>+ p = subparsers.add_parser('extract', help='Extract data using LLM')+ p.add_argument('query', help='What to extract')++ # -------------------------------------------------------------------------+ # Python Execution+ # -------------------------------------------------------------------------++ p = subparsers.add_parser('python', help='Execute Python code')+ p.add_argument('code', nargs='?', help='Python code to execute')+ p.add_argument('--file', '-f', help='Execute Python file')+ p.add_argument('--reset', action='store_true', help='Reset Python namespace')+ p.add_argument('--vars', action='store_true', help='Show defined variables')++ # -------------------------------------------------------------------------+ # Agent Tasks+ # -------------------------------------------------------------------------++ p = subparsers.add_parser('run', help='Run agent task (requires API key)')+ p.add_argument('task', help='Task description')+ p.add_argument('--max-steps', type=int, default=100, help='Maximum steps')++ # -------------------------------------------------------------------------+ # Session Management+ # -------------------------------------------------------------------------++ # sessions+ subparsers.add_parser('sessions', help='List active sessions')++ # close+ p = subparsers.add_parser('close', help='Close session')+ p.add_argument('--all', action='store_true', help='Close all sessions')++ # -------------------------------------------------------------------------+ # Server Control+ # -------------------------------------------------------------------------++ server_p = subparsers.add_parser('server', help='Server control')+ server_sub = server_p.add_subparsers(dest='server_command')+ server_sub.add_parser('status', help='Check server status')+ server_sub.add_parser('stop', help='Stop server')+ server_sub.add_parser('logs', help='View server logs')++ return parser+++def handle_server_command(args: argparse.Namespace) -> int:+ """Handle server subcommands."""+ if args.server_command == 'status':+ if is_server_running(args.session):+ print(f'Server for session "{args.session}" is running')+ return 0+ else:+ print(f'Server for session "{args.session}" is not running')+ return 1++ elif args.server_command == 'stop':+ if not is_server_running(args.session):+ print(f'Server for session "{args.session}" is not running')+ return 0+ response = send_command(args.session, 'shutdown', {})+ if response.get('success'):+ print(f'Server for session "{args.session}" stopped')+ return 0+ else:+ print(f'Error: {response.get("error")}', file=sys.stderr)+ return 1++ elif args.server_command == 'logs':+ log_path = Path(tempfile.gettempdir()) / f'browser-use-{args.session}.log'+ if log_path.exists():+ print(log_path.read_text())+ else:+ print('No logs found')+ return 0++ return 0+++def main() -> int:+ """Main entry point."""+ parser = build_parser()+ args = parser.parse_args()++ if not args.command:+ parser.print_help()+ return 0++ # Handle server subcommands without starting server+ if args.command == 'server':+ return handle_server_command(args)++ # Handle sessions list (may need to check multiple sessions)+ if args.command == 'sessions':+ # For now, just check the current session+ sessions = []+ if is_server_running(args.session):+ sessions.append({'name': args.session, 'status': 'running'})++ if args.json:+ print(json.dumps(sessions))+ else:+ if sessions:+ for s in sessions:+ print(f' {s["name"]}: {s["status"]}')+ else:+ print('No active sessions')+ return 0++ # Set API key in environment if provided+ if args.api_key:+ os.environ['BROWSER_USE_API_KEY'] = args.api_key++ # Ensure server is running+ ensure_server(args.session, args.browser, args.headed, args.profile, args.api_key)++ # Build params from args+ params = {}+ skip_keys = {'command', 'session', 'browser', 'headed', 'profile', 'json', 'api_key', 'server_command'}++ for key, value in vars(args).items():+ if key not in skip_keys and value is not None:+ params[key] = value++ # Send command to server+ response = send_command(args.session, args.command, params)++ # Output response+ if args.json:+ print(json.dumps(response))+ else:+ if response.get('success'):+ data = response.get('data')+ if data is not None:+ if isinstance(data, dict):+ for key, value in data.items():+ if key == 'screenshot' and len(str(value)) > 100:+ print(f'{key}: <{len(value)} bytes>')+ else:+ print(f'{key}: {value}')+ elif isinstance(data, str):+ print(data)+ else:+ print(data)+ else:+ print(f'Error: {response.get("error")}', file=sys.stderr)+ return 1++ return 0+++if __name__ == '__main__':+ sys.exit(main())diff --git a/browser_use/skill_cli/protocol.py b/browser_use/skill_cli/protocol.pynew file mode 100644index 000000000..9be7964d0--- /dev/null+++ b/browser_use/skill_cli/protocol.py@@ -0,0 +1,54 @@+"""Wire protocol for CLI↔Server communication.++Uses JSON over Unix sockets (or TCP on Windows) with newline-delimited messages.+"""++import json+from dataclasses import asdict, dataclass, field+from typing import Any+++@dataclass+class Request:+ """Command request from CLI to server."""++ id: str+ action: str+ session: str+ params: dict[str, Any] = field(default_factory=dict)++ def to_json(self) -> str:+ return json.dumps(asdict(self))++ @classmethod+ def from_json(cls, data: str) -> 'Request':+ d = json.loads(data)+ return cls(+ id=d['id'],+ action=d['action'],+ session=d['session'],+ params=d.get('params', {}),+ )+++@dataclass+class Response:+ """Response from server to CLI."""++ id: str+ success: bool+ data: Any = None+ error: str | None = None++ def to_json(self) -> str:+ return json.dumps(asdict(self))++ @classmethod+ def from_json(cls, data: str) -> 'Response':+ d = json.loads(data)+ return cls(+ id=d['id'],+ success=d['success'],+ data=d.get('data'),+ error=d.get('error'),+ )diff --git a/browser_use/skill_cli/python_session.py b/browser_use/skill_cli/python_session.pynew file mode 100644index 000000000..883a11f82--- /dev/null+++ b/browser_use/skill_cli/python_session.py@@ -0,0 +1,258 @@+"""Jupyter-like persistent Python execution for browser-use CLI."""++import asyncio+import io+import traceback+from contextlib import redirect_stderr, redirect_stdout+from dataclasses import dataclass, field+from pathlib import Path+from typing import TYPE_CHECKING, Any, Literal++if TYPE_CHECKING:+ from browser_use.browser.session import BrowserSession+++@dataclass+class ExecutionResult:+ """Result of Python code execution."""++ success: bool+ output: str = ''+ error: str | None = None+++@dataclass+class PythonSession:+ """Jupyter-like persistent Python execution.++ Maintains a namespace across multiple code executions, allowing variables+ to persist between commands. Provides a `browser` object for browser control.+ """++ namespace: dict[str, Any] = field(default_factory=dict)+ execution_count: int = 0+ history: list[tuple[str, ExecutionResult]] = field(default_factory=list)++ def __post_init__(self) -> None:+ """Initialize namespace with useful imports."""+ self.namespace.update(+ {+ '__name__': '__main__',+ '__doc__': None,+ 'json': __import__('json'),+ 're': __import__('re'),+ 'os': __import__('os'),+ 'Path': Path,+ 'asyncio': asyncio,+ }+ )++ def execute(+ self, code: str, browser_session: 'BrowserSession', loop: asyncio.AbstractEventLoop | None = None+ ) -> ExecutionResult:+ """Execute code in persistent namespace.++ The `browser` variable is injected into the namespace before each execution,+ providing a convenient wrapper around the BrowserSession.++ Args:+ code: Python code to execute+ browser_session: The browser session for browser operations+ loop: The event loop for async operations (required for browser access)+ """+ # Inject browser wrapper with the event loop for async operations+ if loop is not None:+ self.namespace['browser'] = BrowserWrapper(browser_session, loop)+ self.execution_count += 1++ stdout = io.StringIO()+ stderr = io.StringIO()++ try:+ with redirect_stdout(stdout), redirect_stderr(stderr):+ try:+ # First try to compile as expression (for REPL-like behavior)+ compiled = compile(code, '<input>', 'eval')+ result = eval(compiled, self.namespace)+ if result is not None:+ print(repr(result))+ except SyntaxError:+ # Compile as statements+ compiled = compile(code, '<input>', 'exec')+ exec(compiled, self.namespace)++ output = stdout.getvalue()+ if stderr.getvalue():+ output += stderr.getvalue()++ result = ExecutionResult(success=True, output=output)++ except Exception as e:+ output = stdout.getvalue()+ error_msg = traceback.format_exc()+ result = ExecutionResult(success=False, output=output, error=error_msg)++ self.history.append((code, result))+ return result++ def reset(self) -> None:+ """Clear namespace and history."""+ self.namespace.clear()+ self.history.clear()+ self.execution_count = 0+ self.__post_init__()++ def get_variables(self) -> dict[str, str]:+ """Get user-defined variables and their types."""+ skip = {'__name__', '__doc__', 'json', 're', 'os', 'Path', 'asyncio', 'browser'}+ return {k: type(v).__name__ for k, v in self.namespace.items() if not k.startswith('_') and k not in skip}+++class BrowserWrapper:+ """Convenient browser access for Python code.++ Provides synchronous methods that wrap async BrowserSession operations.+ Runs coroutines on the server's event loop using run_coroutine_threadsafe.+ """++ def __init__(self, session: 'BrowserSession', loop: asyncio.AbstractEventLoop) -> None:+ self._session = session+ self._loop = loop++ def _run(self, coro: Any) -> Any:+ """Run coroutine on the server's event loop."""+ future = asyncio.run_coroutine_threadsafe(coro, self._loop)+ return future.result(timeout=60)++ @property+ def url(self) -> str:+ """Get current page URL."""+ return self._run(self._get_url())++ async def _get_url(self) -> str:+ state = await self._session.get_browser_state_summary(include_screenshot=False)+ return state.url if state else ''++ @property+ def title(self) -> str:+ """Get current page title."""+ return self._run(self._get_title())++ async def _get_title(self) -> str:+ state = await self._session.get_browser_state_summary(include_screenshot=False)+ return state.title if state else ''++ def goto(self, url: str) -> None:+ """Navigate to URL."""+ self._run(self._goto_async(url))++ async def _goto_async(self, url: str) -> None:+ from browser_use.browser.events import NavigateToUrlEvent++ await self._session.event_bus.dispatch(NavigateToUrlEvent(url=url))++ def click(self, index: int) -> None:+ """Click element by index."""+ self._run(self._click_async(index))++ async def _click_async(self, index: int) -> None:+ from browser_use.browser.events import ClickElementEvent++ node = await self._session.get_element_by_index(index)+ if node is None:+ raise ValueError(f'Element index {index} not found')+ await self._session.event_bus.dispatch(ClickElementEvent(node=node))++ def type(self, text: str) -> None:+ """Type text into focused element."""+ self._run(self._type_async(text))++ async def _type_async(self, text: str) -> None:+ cdp_session = await self._session.get_or_create_cdp_session(target_id=None, focus=False)+ if not cdp_session:+ raise RuntimeError('No active browser session')+ await cdp_session.cdp_client.send.Input.insertText(+ params={'text': text},+ session_id=cdp_session.session_id,+ )++ def input(self, index: int, text: str) -> None:+ """Click element and type text."""+ self._run(self._input_async(index, text))++ async def _input_async(self, index: int, text: str) -> None:+ from browser_use.browser.events import ClickElementEvent, TypeTextEvent++ node = await self._session.get_element_by_index(index)+ if node is None:+ raise ValueError(f'Element index {index} not found')+ await self._session.event_bus.dispatch(ClickElementEvent(node=node))+ await self._session.event_bus.dispatch(TypeTextEvent(node=node, text=text))++ def scroll(self, direction: Literal['up', 'down', 'left', 'right'] = 'down', amount: int = 500) -> None:+ """Scroll the page."""+ self._run(self._scroll_async(direction, amount))++ async def _scroll_async(self, direction: Literal['up', 'down', 'left', 'right'], amount: int) -> None:+ from browser_use.browser.events import ScrollEvent++ await self._session.event_bus.dispatch(ScrollEvent(direction=direction, amount=amount))++ def screenshot(self, path: str | None = None) -> bytes:+ """Take screenshot, optionally save to file."""+ data = self._run(self._session.take_screenshot())+ if path:+ Path(path).write_bytes(data)+ return data++ @property+ def html(self) -> str:+ """Get page HTML."""+ return self._run(self._get_html())++ async def _get_html(self) -> str:+ cdp_session = await self._session.get_or_create_cdp_session(target_id=None, focus=False)+ if not cdp_session:+ return ''+ # Get the document root+ doc = await cdp_session.cdp_client.send.DOM.getDocument(+ params={},+ session_id=cdp_session.session_id,+ )+ if not doc or 'root' not in doc:+ return ''+ # Get outer HTML of the root node+ result = await cdp_session.cdp_client.send.DOM.getOuterHTML(+ params={'nodeId': doc['root']['nodeId']},+ session_id=cdp_session.session_id,+ )+ return result.get('outerHTML', '') if result else ''++ def keys(self, keys: str) -> None:+ """Send keyboard keys."""+ self._run(self._keys_async(keys))++ async def _keys_async(self, keys: str) -> None:+ from browser_use.browser.events import SendKeysEvent++ await self._session.event_bus.dispatch(SendKeysEvent(keys=keys))++ def back(self) -> None:+ """Go back in history."""+ self._run(self._back_async())++ async def _back_async(self) -> None:+ from browser_use.browser.events import GoBackEvent++ await self._session.event_bus.dispatch(GoBackEvent())++ def wait(self, seconds: float) -> None:+ """Wait for specified seconds."""+ import time++ time.sleep(seconds)++ def extract(self, query: str) -> Any:+ """Extract data using LLM (requires API key)."""+ # This would need LLM integration+ raise NotImplementedError('extract() requires LLM integration - use agent.run() instead')diff --git a/browser_use/skill_cli/server.py b/browser_use/skill_cli/server.pynew file mode 100644index 000000000..a24741f97--- /dev/null+++ b/browser_use/skill_cli/server.py@@ -0,0 +1,256 @@+"""Session server - keeps BrowserSession instances alive.++This server runs as a background process, managing browser sessions and+handling commands from the CLI. It uses Unix sockets (or TCP on Windows)+for IPC communication.+"""++import argparse+import asyncio+import json+import logging+import os+import signal+import sys+from pathlib import Path++# Configure logging before imports+logging.basicConfig(+ level=logging.INFO,+ format='%(asctime)s [%(levelname)s] %(name)s: %(message)s',+ handlers=[logging.StreamHandler()],+)+logger = logging.getLogger('browser_use.skill_cli.server')+++class SessionServer:+ """Server that manages browser sessions and handles CLI commands."""++ def __init__(+ self,+ session_name: str,+ browser_mode: str,+ headed: bool,+ profile: str | None,+ ) -> None:+ self.session_name = session_name+ self.browser_mode = browser_mode+ self.headed = headed+ self.profile = profile+ self.running = True+ self._server: asyncio.Server | None = None+ self._shutdown_event: asyncio.Event | None = None++ # Lazy import to avoid loading everything at startup+ from browser_use.skill_cli.sessions import SessionRegistry++ self.registry = SessionRegistry()++ async def handle_connection(+ self,+ reader: asyncio.StreamReader,+ writer: asyncio.StreamWriter,+ ) -> None:+ """Handle a client connection."""+ addr = writer.get_extra_info('peername')+ logger.debug(f'Connection from {addr}')++ try:+ while self.running:+ try:+ line = await asyncio.wait_for(reader.readline(), timeout=300) # 5 min timeout+ except TimeoutError:+ logger.debug(f'Connection timeout from {addr}')+ break++ if not line:+ break++ try:+ request = json.loads(line.decode())+ response = await self.dispatch(request)+ except json.JSONDecodeError as e:+ response = {'id': '', 'success': False, 'error': f'Invalid JSON: {e}'}+ except Exception as e:+ logger.exception(f'Error handling request: {e}')+ response = {'id': '', 'success': False, 'error': str(e)}++ writer.write((json.dumps(response) + '\n').encode())+ await writer.drain()++ # Check for shutdown command+ if request.get('action') == 'shutdown':+ await self.shutdown()+ break++ except Exception as e:+ logger.exception(f'Connection error: {e}')+ finally:+ writer.close()+ try:+ await writer.wait_closed()+ except Exception:+ pass++ async def dispatch(self, request: dict) -> dict:+ """Dispatch command to appropriate handler."""+ action = request.get('action', '')+ params = request.get('params', {})+ req_id = request.get('id', '')++ logger.info(f'Dispatch: {action} (id={req_id})')++ try:+ # Import command handlers+ from browser_use.skill_cli.commands import agent, browser, python_exec, session++ # Handle shutdown+ if action == 'shutdown':+ return {'id': req_id, 'success': True, 'data': {'shutdown': True}}++ # Get or create session+ session_info = await self.registry.get_or_create(+ self.session_name,+ self.browser_mode,+ self.headed,+ self.profile,+ )++ # Dispatch to handler+ if action in browser.COMMANDS:+ result = await browser.handle(action, session_info, params)+ elif action == 'python':+ result = await python_exec.handle(session_info, params)+ elif action == 'run':+ result = await agent.handle(session_info, params)+ elif action in session.COMMANDS:+ result = await session.handle(action, self.registry, params)+ else:+ return {'id': req_id, 'success': False, 'error': f'Unknown action: {action}'}++ return {'id': req_id, 'success': True, 'data': result}++ except Exception as e:+ logger.exception(f'Error dispatching {action}: {e}')+ return {'id': req_id, 'success': False, 'error': str(e)}++ async def shutdown(self) -> None:+ """Graceful shutdown."""+ logger.info('Shutting down server...')+ self.running = False++ # Signal the shutdown event+ if self._shutdown_event:+ self._shutdown_event.set()++ # Close all sessions+ await self.registry.close_all()++ # Stop the server+ if self._server:+ self._server.close()+ await self._server.wait_closed()++ # Clean up files+ from browser_use.skill_cli.utils import cleanup_session_files++ cleanup_session_files(self.session_name)++ async def run(self) -> None:+ """Run the server."""+ from browser_use.skill_cli.utils import get_pid_path, get_socket_path++ # Write PID file+ pid_path = get_pid_path(self.session_name)+ pid_path.write_text(str(os.getpid()))+ logger.info(f'PID file: {pid_path}')++ # Setup signal handlers+ loop = asyncio.get_running_loop()++ def signal_handler():+ asyncio.create_task(self.shutdown())++ for sig in (signal.SIGINT, signal.SIGTERM):+ try:+ loop.add_signal_handler(sig, signal_handler)+ except NotImplementedError:+ # Windows doesn't support add_signal_handler+ pass++ # Also handle SIGHUP on Unix+ if hasattr(signal, 'SIGHUP'):+ try:+ loop.add_signal_handler(signal.SIGHUP, signal_handler)+ except NotImplementedError:+ pass++ # Get socket path+ sock_path = get_socket_path(self.session_name)+ logger.info(f'Socket: {sock_path}')++ # Start server+ if sock_path.startswith('tcp://'):+ # Windows: TCP server+ _, hostport = sock_path.split('://', 1)+ host, port = hostport.split(':')+ self._server = await asyncio.start_server(+ self.handle_connection,+ host,+ int(port),+ )+ logger.info(f'Listening on TCP {host}:{port}')+ else:+ # Unix: socket server+ # Remove stale socket file+ sock_file = Path(sock_path)+ if sock_file.exists():+ sock_file.unlink()++ self._server = await asyncio.start_unix_server(+ self.handle_connection,+ sock_path,+ )+ logger.info(f'Listening on Unix socket {sock_path}')++ # Run until shutdown+ self._shutdown_event = asyncio.Event()+ try:+ async with self._server:+ await self._shutdown_event.wait()+ except asyncio.CancelledError:+ pass+ finally:+ logger.info('Server stopped')+++def main() -> None:+ """Main entry point for server process."""+ parser = argparse.ArgumentParser(description='Browser-use session server')+ parser.add_argument('--session', required=True, help='Session name')+ parser.add_argument('--browser', default='chromium', choices=['chromium', 'real', 'remote'])+ parser.add_argument('--headed', action='store_true', help='Show browser window')+ parser.add_argument('--profile', help='Chrome profile (real browser mode)')+ args = parser.parse_args()++ logger.info(f'Starting server for session: {args.session}')+ logger.info(f'Browser mode: {args.browser}, headed: {args.headed}')++ server = SessionServer(+ session_name=args.session,+ browser_mode=args.browser,+ headed=args.headed,+ profile=args.profile,+ )++ try:+ asyncio.run(server.run())+ except KeyboardInterrupt:+ logger.info('Interrupted')+ except Exception as e:+ logger.exception(f'Server error: {e}')+ sys.exit(1)+++if __name__ == '__main__':+ main()diff --git a/browser_use/skill_cli/sessions.py b/browser_use/skill_cli/sessions.pynew file mode 100644index 000000000..0371e77bd--- /dev/null+++ b/browser_use/skill_cli/sessions.py@@ -0,0 +1,137 @@+"""Session registry - manages BrowserSession instances."""++import logging+from dataclasses import dataclass, field+from typing import Any++from browser_use.browser.session import BrowserSession+from browser_use.skill_cli.python_session import PythonSession++logger = logging.getLogger(__name__)+++@dataclass+class SessionInfo:+ """Information about a browser session."""++ name: str+ browser_mode: str+ headed: bool+ profile: str | None+ browser_session: BrowserSession+ python_session: PythonSession = field(default_factory=PythonSession)+++class SessionRegistry:+ """Registry of active browser sessions.++ Sessions are created on-demand when first accessed. Each named session+ is isolated with its own BrowserSession and Python namespace.+ """++ def __init__(self) -> None:+ self._sessions: dict[str, SessionInfo] = {}++ async def get_or_create(+ self,+ name: str,+ browser_mode: str,+ headed: bool,+ profile: str | None,+ ) -> SessionInfo:+ """Get existing session or create new one."""+ if name in self._sessions:+ return self._sessions[name]++ logger.info(f'Creating new session: {name} (mode={browser_mode}, headed={headed})')++ browser_session = await create_browser_session(browser_mode, headed, profile)+ await browser_session.start()++ session_info = SessionInfo(+ name=name,+ browser_mode=browser_mode,+ headed=headed,+ profile=profile,+ browser_session=browser_session,+ )+ self._sessions[name] = session_info+ return session_info++ def get(self, name: str) -> SessionInfo | None:+ """Get session by name."""+ return self._sessions.get(name)++ def list_sessions(self) -> list[dict[str, Any]]:+ """List all active sessions."""+ return [+ {+ 'name': s.name,+ 'browser_mode': s.browser_mode,+ 'headed': s.headed,+ 'profile': s.profile,+ }+ for s in self._sessions.values()+ ]++ async def close_session(self, name: str) -> bool:+ """Close and remove a session."""+ if name not in self._sessions:+ return False++ session = self._sessions.pop(name)+ logger.info(f'Closing session: {name}')+ try:+ await session.browser_session.kill()+ except Exception as e:+ logger.warning(f'Error closing session {name}: {e}')+ return True++ async def close_all(self) -> None:+ """Close all sessions."""+ for name in list(self._sessions.keys()):+ await self.close_session(name)+++async def create_browser_session(+ mode: str,+ headed: bool,+ profile: str | None,+) -> BrowserSession:+ """Create BrowserSession based on mode.++ Modes:+ - chromium: Playwright-managed Chromium (default)+ - real: User's Chrome with profile+ - remote: Browser-Use Cloud (requires API key)+ """+ if mode == 'chromium':+ return BrowserSession(+ headless=not headed,+ )++ elif mode == 'real':+ from browser_use.skill_cli.utils import find_chrome_executable, get_chrome_profile_path++ chrome_path = find_chrome_executable()+ if not chrome_path:+ raise RuntimeError('Could not find Chrome executable. Please install Chrome or specify --browser chromium')++ user_data_dir = get_chrome_profile_path(profile)++ return BrowserSession(+ executable_path=chrome_path,+ user_data_dir=user_data_dir,+ headless=False, # Real browser always visible+ )++ elif mode == 'remote':+ from browser_use.skill_cli.api_key import require_api_key++ require_api_key('Remote browser')+ return BrowserSession(+ use_cloud=True,+ )++ else:+ raise ValueError(f'Unknown browser mode: {mode}')diff --git a/browser_use/skill_cli/utils.py b/browser_use/skill_cli/utils.pynew file mode 100644index 000000000..34371f495--- /dev/null+++ b/browser_use/skill_cli/utils.py@@ -0,0 +1,141 @@+"""Platform utilities for CLI and server."""++import hashlib+import os+import platform+import subprocess+import sys+import tempfile+from pathlib import Path+++def get_socket_path(session: str) -> str:+ """Get socket path for session.++ On Windows, returns a TCP address (tcp://localhost:PORT).+ On Unix, returns a Unix socket path.+ """+ if sys.platform == 'win32':+ # Windows: use TCP on deterministic port (49152-65535)+ port = 49152 + (int(hashlib.md5(session.encode()).hexdigest()[:4], 16) % 16383)+ return f'tcp://localhost:{port}'+ return str(Path(tempfile.gettempdir()) / f'browser-use-{session}.sock')+++def get_pid_path(session: str) -> Path:+ """Get PID file path for session."""+ return Path(tempfile.gettempdir()) / f'browser-use-{session}.pid'+++def get_log_path(session: str) -> Path:+ """Get log file path for session."""+ return Path(tempfile.gettempdir()) / f'browser-use-{session}.log'+++def is_server_running(session: str) -> bool:+ """Check if server is running for session."""+ pid_path = get_pid_path(session)+ if not pid_path.exists():+ return False+ try:+ pid = int(pid_path.read_text().strip())+ # Check if process exists+ os.kill(pid, 0)+ return True+ except (OSError, ValueError):+ # Process doesn't exist or invalid PID+ return False+++def cleanup_session_files(session: str) -> None:+ """Remove session socket and PID files."""+ sock_path = get_socket_path(session)+ pid_path = get_pid_path(session)++ # Remove socket file (Unix only)+ if not sock_path.startswith('tcp://'):+ try:+ os.unlink(sock_path)+ except OSError:+ pass++ # Remove PID file+ try:+ pid_path.unlink()+ except OSError:+ pass+++def find_chrome_executable() -> str | None:+ """Find Chrome/Chromium executable on the system."""+ system = platform.system()++ if system == 'Darwin':+ # macOS+ paths = [+ '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',+ '/Applications/Chromium.app/Contents/MacOS/Chromium',+ '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',+ ]+ for path in paths:+ if os.path.exists(path):+ return path++ elif system == 'Linux':+ # Linux: try common commands+ for cmd in ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser']:+ try:+ result = subprocess.run(['which', cmd], capture_output=True, text=True)+ if result.returncode == 0:+ return result.stdout.strip()+ except Exception:+ pass++ elif system == 'Windows':+ # Windows: check common paths+ paths = [+ os.path.expandvars(r'%ProgramFiles%\Google\Chrome\Application\chrome.exe'),+ os.path.expandvars(r'%ProgramFiles(x86)%\Google\Chrome\Application\chrome.exe'),+ os.path.expandvars(r'%LocalAppData%\Google\Chrome\Application\chrome.exe'),+ ]+ for path in paths:+ if os.path.exists(path):+ return path++ return None+++def get_chrome_profile_path(profile: str | None) -> str | None:+ """Get Chrome user data directory for a profile.++ If profile is None, returns the default Chrome user data directory.+ """+ if profile is None:+ # Use default Chrome profile location+ system = platform.system()+ if system == 'Darwin':+ return str(Path.home() / 'Library' / 'Application Support' / 'Google' / 'Chrome')+ elif system == 'Linux':+ return str(Path.home() / '.config' / 'google-chrome')+ elif system == 'Windows':+ return os.path.expandvars(r'%LocalAppData%\Google\Chrome\User Data')+ else:+ # Return the profile name - Chrome will use it as a subdirectory+ # The actual path will be user_data_dir/profile+ return profile++ return None+++def get_config_dir() -> Path:+ """Get browser-use config directory."""+ if sys.platform == 'win32':+ base = Path(os.environ.get('APPDATA', Path.home()))+ else:+ base = Path(os.environ.get('XDG_CONFIG_HOME', Path.home() / '.config'))+ return base / 'browser-use'+++def get_config_path() -> Path:+ """Get browser-use config file path."""+ return get_config_dir() / 'config.json'diff --git a/pyproject.toml b/pyproject.tomlindex 7c6aa5f59..cf0e4897c 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -94,6 +94,7 @@ Repository = "https://github.com/browser-use/browser-use"[project.scripts]browseruse = "browser_use.cli:main"browser-use = "browser_use.cli:main"+bu = "browser_use.skill_cli.main:main" # Fast CLI for browser automation[build-system]requires = ["hatchling"]diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdnew file mode 100644index 000000000..7eaff9f2f--- /dev/null+++ b/skills/browser-use/SKILL.md@@ -0,0 +1,208 @@+---+name: browser-use+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages.+allowed-tools: Bash(bu:*)+---++# Browser Automation with browser-use CLI++The `bu` command provides fast, persistent browser automation. It maintains browser sessions across commands, enabling complex multi-step workflows.++## Quick Start++```bash+bu open https://example.com # Navigate to URL+bu state # Get page elements with indices+bu click 5 # Click element by index+bu type "Hello World" # Type text+bu screenshot # Take screenshot+bu close # Close browser+```++## Core Workflow++1. **Navigate**: `bu open <url>` - Opens URL (starts browser if needed)+2. **Inspect**: `bu state` - Returns clickable elements with indices+3. **Interact**: Use indices from state to interact (`bu click 5`, `bu input 3 "text"`)+4. **Verify**: `bu state` or `bu screenshot` to confirm actions+5. **Repeat**: Browser stays open between commands++## Browser Modes++```bash+bu --browser chromium open <url> # Default: headless Chromium+bu --browser chromium --headed open <url> # Visible Chromium window+bu --browser real open <url> # User's Chrome with login sessions+bu --browser remote open <url> # Cloud browser (requires API key)+```++- **chromium**: Fast, isolated, headless by default+- **real**: Uses your Chrome with cookies, extensions, logged-in sessions+- **remote**: Cloud-hosted browser with proxy support (requires BROWSER_USE_API_KEY)++## Commands++### Navigation+```bash+bu open <url> # Navigate to URL+bu back # Go back in history+bu scroll down # Scroll down+bu scroll up # Scroll up+```++### Page State+```bash+bu state # Get URL, title, and clickable elements+bu screenshot # Take screenshot (outputs base64)+bu screenshot path.png # Save screenshot to file+bu screenshot --full path.png # Full page screenshot+```++### Interactions (use indices from `bu state`)+```bash+bu click <index> # Click element+bu type "text" # Type text into focused element+bu input <index> "text" # Click element, then type text+bu keys "Enter" # Send keyboard keys+bu keys "Control+a" # Send key combination+bu select <index> "option" # Select dropdown option+```++### Tab Management+```bash+bu switch <tab> # Switch to tab by index+bu close-tab # Close current tab+bu close-tab <tab> # Close specific tab+```++### JavaScript & Data+```bash+bu eval "document.title" # Execute JavaScript, return result+bu extract "all product prices" # Extract data using LLM (requires API key)+```++### Python Execution (Persistent Session)+```bash+bu python "x = 42" # Set variable+bu python "print(x)" # Access variable (outputs: 42)+bu python "print(browser.url)" # Access browser object+bu python --vars # Show defined variables+bu python --reset # Clear Python namespace+bu python --file script.py # Execute Python file+```++The Python session maintains state across commands. The `browser` object provides:+- `browser.url` - Current page URL+- `browser.title` - Page title+- `browser.goto(url)` - Navigate+- `browser.click(index)` - Click element+- `browser.type(text)` - Type text+- `browser.screenshot(path)` - Take screenshot+- `browser.scroll()` - Scroll page+- `browser.html` - Get page HTML++### Agent Tasks (Requires API Key)+```bash+bu run "Fill the contact form with test data" # Run AI agent+bu run "Extract all product prices" --max-steps 50+```++Agent tasks use an LLM to autonomously complete complex browser tasks. Requires `BROWSER_USE_API_KEY` or configured LLM API key (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc).++### Session Management+```bash+bu sessions # List active sessions+bu close # Close current session+bu close --all # Close all sessions+```++### Server Control+```bash+bu server status # Check if server is running+bu server stop # Stop server+bu server logs # View server logs+```++## Global Options++| Option | Description |+|--------|-------------|+| `--session NAME` | Use named session (default: "default") |+| `--browser MODE` | Browser mode: chromium, real, remote |+| `--headed` | Show browser window (chromium mode) |+| `--profile NAME` | Chrome profile (real mode only) |+| `--json` | Output as JSON |+| `--api-key KEY` | Override API key |++## Examples++### Form Submission+```bash+bu open https://example.com/contact+bu state+# Shows: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"+bu input 0 "John Doe"+bu input 1 "[email protected]"+bu input 2 "Hello, this is a test message."+bu click 3+bu state # Verify success+```++### Multi-Session Workflows+```bash+bu --session work open https://work.example.com+bu --session personal open https://personal.example.com+bu --session work state # Check work session+bu --session personal state # Check personal session+bu close --all # Close both sessions+```++### Data Extraction with Python+```bash+bu open https://example.com/products+bu python "+products = []+for i in range(20):+ browser.scroll('down')+browser.screenshot('products.png')+"+bu python "print(f'Captured {len(products)} products')"+```++### Using Real Browser (Logged-In Sessions)+```bash+bu --browser real open https://gmail.com+# Uses your actual Chrome with existing login sessions+bu state # Already logged in!+```++## Tips++1. **Always run `bu state` first** to see available elements and their indices+2. **Use `--headed` for debugging** to see what the browser is doing+3. **Sessions persist** - the browser stays open between commands+4. **Use `--json` for parsing** output programmatically+5. **Python variables persist** across `bu python` commands within a session+6. **Real browser mode** preserves your login sessions and extensions++## Troubleshooting++**Browser won't start?**+```bash+bu server stop # Stop any stuck server+bu --headed open <url> # Try with visible window+```++**Element not found?**+```bash+bu state # Check current elements+bu scroll down # Element might be below fold+bu state # Check again+```++**Session issues?**+```bash+bu sessions # Check active sessions+bu close --all # Clean slate+bu open <url> # Fresh start+```