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
changes
ShawnPana4be221386b1b
diff --git a/browser_use/skill_cli/README.md b/browser_use/skill_cli/README.mdindex f81376a9b..c7490a322 100644--- a/browser_use/skill_cli/README.md+++ b/browser_use/skill_cli/README.md@@ -24,20 +24,10 @@ curl -fsSL https://browser-use.com/cli/install.sh | bash& "C:\Program Files\Git\bin\bash.exe" -c 'curl -fsSL https://browser-use.com/cli/install.sh | bash'```-### Installation Modes-```bash-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --full # All modes-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --local-only # Local browser only-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only # Cloud browser only-curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --api-key bu_xxx # With API key-```-### Post-Install```bashbrowser-use doctor # Validate installationbrowser-use setup # Run setup wizard (optional)-browser-use setup --mode local|remote|full # Non-interactive setup-browser-use setup --api-key bu_xxx --yes # With API key, skip prompts```### Generate Templates@@ -106,11 +96,11 @@ browser-use open https://example.com# Visible browser windowbrowser-use --headed open https://example.com-# Use your real Chrome (with existing logins/cookies)-browser-use --browser real open https://gmail.com+# Use your real Chrome with Default profile (with existing logins/cookies)+browser-use --profile open https://gmail.com-# Cloud browser (requires BROWSER_USE_API_KEY)-browser-use --browser remote open https://example.com+# Use a specific Chrome profile+browser-use --profile "Profile 1" open https://gmail.com```## All Commands@@ -213,75 +203,6 @@ browser-use run "task" --llm gpt-4o # Specify LLM modelRequires an LLM API key (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).-### Remote Mode (Cloud)-```bash-browser-use -b remote run "Search for AI news" # US proxy default-browser-use -b remote run "task" --llm gpt-4o # Specify LLM-browser-use -b remote run "task" --proxy-country gb # UK proxy-browser-use -b remote run "task" --session-id <id> # Reuse session-browser-use -b remote run "task" --no-wait # Async (returns task ID)-browser-use -b remote run "task" --wait # Wait for completion-browser-use -b remote run "task" --stream # Stream output-browser-use -b remote run "task" --flash # Fast mode-browser-use -b remote run "task" --keep-alive # Keep session alive-browser-use -b remote run "task" --thinking # Extended reasoning-browser-use -b remote run "task" --vision # Enable vision (default)-browser-use -b remote run "task" --no-vision # Disable vision-browser-use -b remote run "task" --profile <id> # Use cloud profile--# Task configuration-browser-use -b remote run "task" --start-url https://example.com # Start from URL-browser-use -b remote run "task" --allowed-domain example.com # Restrict navigation (repeatable)-browser-use -b remote run "task" --metadata key=value # Task metadata (repeatable)-browser-use -b remote run "task" --secret API_KEY=xxx # Task secrets (repeatable)-browser-use -b remote run "task" --skill-id skill-123 # Enable skills (repeatable)--# Structured output and evaluation-browser-use -b remote run "task" --structured-output '{"type":"object"}' # JSON schema-browser-use -b remote run "task" --judge # Enable judge mode-browser-use -b remote run "task" --judge-ground-truth "answer" # Expected answer-```--Requires `BROWSER_USE_API_KEY`.--## Task Management (Remote Mode)--Manage cloud tasks when using `--browser remote`.--| Command | Description |-|---------|-------------|-| `task list` | List recent tasks |-| `task list --status running` | Filter by status |-| `task list --session <id>` | Filter by session ID |-| `task status <id>` | Get task status (latest step only) |-| `task status <id> -c` | Compact: all steps with reasoning |-| `task status <id> -v` | Verbose: full details |-| `task status <id> --last 5` | Show last 5 steps |-| `task status <id> --step 3` | Show specific step number |-| `task status <id> --reverse` | Show steps newest first |-| `task stop <id>` | Stop running task |-| `task logs <id>` | Get execution logs |--## Cloud Sessions (Remote Mode)--Manage cloud browser sessions.--| Command | Description |-|---------|-------------|-| `session list` | List cloud sessions |-| `session list --status active` | Filter by status |-| `session get <id>` | Get session details + live URL |-| `session stop <id>` | Stop session |-| `session stop --all` | Stop all active sessions |-| `session create` | Create new session |-| `session create --profile <id>` | With cloud profile |-| `session create --proxy-country gb` | With geographic proxy |-| `session create --start-url <url>` | Start at specific URL |-| `session create --screen-size 1920x1080` | Custom screen size |-| `session create --keep-alive` | Keep session alive |-| `session create --persist-memory` | Persist memory between tasks |-| `session share <id>` | Create public share URL |-| `session share <id> --delete` | Delete public share |## Tunnels@@ -298,29 +219,16 @@ Expose local dev servers to cloud browsers via Cloudflare tunnels.# Example: Test local dev server with cloud browsernpm run dev & # localhost:3000browser-use tunnel 3000 # → https://abc.trycloudflare.com-browser-use -b remote open https://abc.trycloudflare.com+browser-use open https://abc.trycloudflare.com```## Profile Management-### Local Profiles (`-b real`)+### Local Profiles| Command | Description ||---------|-------------|| `profile list` | List Chrome profiles || `profile cookies <name>` | Show cookies by domain |-| `profile sync --from <name>` | Sync local profile to cloud |-| `profile sync --from Default --domain youtube.com` | Sync specific domain only |--### Cloud Profiles (`-b remote`)-| Command | Description |-|---------|-------------|-| `profile list` | List cloud profiles |-| `profile list --page 2 --page-size 50` | Pagination |-| `profile get <id>` | Get profile details |-| `profile create` | Create profile |-| `profile create --name "My Profile"` | Create with name |-| `profile update <id> --name <name>` | Rename profile |-| `profile delete <id>` | Delete profile |## Session Management@@ -332,9 +240,8 @@ browser-use -b remote open https://abc.trycloudflare.com| Option | Description ||--------|-------------|-| `--browser MODE` | Browser mode: chromium, real, remote || `--headed` | Show browser window |-| `--profile NAME` | Browser profile (local name or cloud ID) |+| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") || `--json` | Output as JSON || `--api-key KEY` | Override API key || `--mcp` | Run as MCP server via stdin/stdout |@@ -368,19 +275,6 @@ browser.screenshot('scrolled.png')"```-### Cloud Agent with Session Reuse-```bash-# Start task, keep session alive-browser-use -b remote run "Log into example.com" --keep-alive --no-wait-# → task_id: task-123, session_id: sess-456--# Check task status-browser-use task status task-123--# Run another task in same session (preserves login)-browser-use -b remote run "Go to settings" --session-id sess-456-```-## Claude Code SkillFor [Claude Code](https://claude.ai/code), a skill provides richer context for browser automation:diff --git a/browser_use/skill_cli/commands/profile.py b/browser_use/skill_cli/commands/profile.pyindex 2f6731c84..6823ca848 100644--- a/browser_use/skill_cli/commands/profile.py+++ b/browser_use/skill_cli/commands/profile.py@@ -36,12 +36,12 @@ def handle_profile_command(args: argparse.Namespace) -> int:def _print_usage() -> None:"""Print profile command usage."""- print('Usage: browser-use [-b real] profile <command>')+ print('Usage: browser-use profile <command>')print()print('Commands:')print(' list List local Chrome profiles')print(' get <id> Get profile details')- print(' cookies <id> Show cookies by domain (requires -b real)')+ print(' cookies <id> Show cookies by domain')# -----------------------------------------------------------------------------@@ -97,12 +97,6 @@ def _get_local_profile(args: argparse.Namespace) -> int:def _handle_cookies(args: argparse.Namespace) -> int:"""Handle 'profile cookies <id>' command."""- browser_mode = getattr(args, 'browser', None)- if browser_mode and browser_mode != 'real':- print('Error: Cookie listing is only available for local Chrome profiles.', file=sys.stderr)- print('Use -b real to access local profile cookies.', file=sys.stderr)- return 1-return _list_profile_cookies(args)@@ -137,7 +131,7 @@ def _list_profile_cookies(args: argparse.Namespace) -> int:print(f'Loading cookies from: {selected_profile["name"]} ({selected_profile["email"]})')async def get_cookies():- local_session = await create_browser_session('real', headed=False, profile=profile_id)+ local_session = await create_browser_session(headed=False, profile=profile_id)await local_session.start()try:cookies = await local_session._cdp_get_cookies()diff --git a/browser_use/skill_cli/daemon.py b/browser_use/skill_cli/daemon.pyindex 87f7f02d6..7f40190bf 100644--- a/browser_use/skill_cli/daemon.py+++ b/browser_use/skill_cli/daemon.py@@ -34,11 +34,9 @@ class Daemon:def __init__(self,- browser_mode: str,headed: bool,profile: str | None,) -> None:- self.browser_mode = browser_modeself.headed = headedself.profile = profileself.running = True@@ -54,14 +52,13 @@ class Daemon:from browser_use.skill_cli.sessions import SessionInfo, create_browser_session- logger.info(f'Creating session (mode={self.browser_mode}, headed={self.headed})')+ logger.info(f'Creating session (headed={self.headed}, profile={self.profile})')- bs = await create_browser_session(self.browser_mode, self.headed, self.profile)+ bs = await create_browser_session(self.headed, self.profile)await bs.start()self._session = SessionInfo(name='default',- browser_mode=self.browser_mode,headed=self.headed,profile=self.profile,browser_session=bs,@@ -135,7 +132,6 @@ class Daemon:'id': req_id,'success': True,'data': {- 'browser_mode': self.browser_mode,'headed': self.headed,'profile': self.profile,},@@ -241,15 +237,13 @@ class Daemon:def main() -> None:"""Main entry point for daemon process."""parser = argparse.ArgumentParser(description='Browser-use daemon')- parser.add_argument('--browser', default='chromium', choices=['chromium', 'real'])parser.add_argument('--headed', action='store_true', help='Show browser window')- parser.add_argument('--profile', help='Chrome profile (real browser mode)')+ parser.add_argument('--profile', help='Chrome profile (triggers real Chrome mode)')args = parser.parse_args()- logger.info(f'Starting daemon: browser={args.browser}, headed={args.headed}')+ logger.info(f'Starting daemon: headed={args.headed}, profile={args.profile}')daemon = Daemon(- browser_mode=args.browser,headed=args.headed,profile=args.profile,)diff --git a/browser_use/skill_cli/install.sh b/browser_use/skill_cli/install.shindex 8c48ba5f0..89c7da79e 100755--- a/browser_use/skill_cli/install.sh+++ b/browser_use/skill_cli/install.sh@@ -78,7 +78,7 @@## 7. Debugging daemon issues# To see actual error messages instead of "Failed to start daemon":-# & "$env:USERPROFILE\.browser-use-env\Scripts\python.exe" -m browser_use.skill_cli.daemon --browser chromium+# & "$env:USERPROFILE\.browser-use-env\Scripts\python.exe" -m browser_use.skill_cli.daemon# This runs the daemon in foreground and shows all errors.## =============================================================================@@ -595,39 +595,6 @@ install_dependencies() {fi}-# =============================================================================-# Write install configuration-# =============================================================================--write_install_config() {- # Determine installed modes and default- local modes=""- local default_mode=""-- if [ "$INSTALL_LOCAL" = true ] && [ "$INSTALL_REMOTE" = true ]; then- modes='["chromium", "real", "remote"]'- default_mode="chromium"- elif [ "$INSTALL_REMOTE" = true ]; then- modes='["remote"]'- default_mode="remote"- else- modes='["chromium", "real"]'- default_mode="chromium"- fi-- # Write config file- mkdir -p "$HOME/.browser-use"- cat > "$HOME/.browser-use/install-config.json" << EOF-{- "installed_modes": $modes,- "default_mode": "$default_mode"-}-EOF-- local mode_names=$(echo $modes | tr -d '[]"' | tr ',' ' ')- log_success "Configured: $mode_names"-}-# =============================================================================# PATH configuration# =============================================================================@@ -853,19 +820,16 @@ main() {# Step 5: Install dependenciesinstall_dependencies- # Step 6: Write install config- write_install_config-- # Step 7: Configure PATH+ # Step 6: Configure PATHconfigure_path- # Step 8: Run setup wizard+ # Step 7: Run setup wizardrun_setup- # Step 9: Validate+ # Step 8: Validatevalidate- # Step 10: Show next steps+ # Step 9: Show next stepsprint_next_steps}diff --git a/browser_use/skill_cli/install_config.py b/browser_use/skill_cli/install_config.pydeleted file mode 100644index ff2ad4c18..000000000--- a/browser_use/skill_cli/install_config.py+++ /dev/null@@ -1,111 +0,0 @@-"""Install configuration - tracks which browser modes are available.--This module manages the installation configuration that determines which browser-modes (chromium, real, remote) are available based on how browser-use was installed.--Config file: ~/.browser-use/install-config.json--When no config file exists (e.g., pip install users), all modes are available by default.-"""--import json-from pathlib import Path-from typing import Literal--CONFIG_PATH = Path.home() / '.browser-use' / 'install-config.json'--ModeType = Literal['chromium', 'real', 'remote']--# Local modes (both require Chromium to be installed)-LOCAL_MODES: set[str] = {'chromium', 'real'}---def get_config() -> dict:- """Read install config. Returns default if not found.-- Default config enables all modes (for pip install users).- """- if not CONFIG_PATH.exists():- return {- 'installed_modes': ['chromium', 'real', 'remote'],- 'default_mode': 'chromium',- }-- try:- return json.loads(CONFIG_PATH.read_text())- except (json.JSONDecodeError, OSError):- # Config file corrupt, return default- return {- 'installed_modes': ['chromium', 'real', 'remote'],- 'default_mode': 'chromium',- }---def save_config(installed_modes: list[str], default_mode: str) -> None:- """Save install config."""- CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)- CONFIG_PATH.write_text(- json.dumps(- {- 'installed_modes': installed_modes,- 'default_mode': default_mode,- },- indent=2,- )- )---def is_mode_available(mode: str) -> bool:- """Check if a browser mode is available based on installation config.-- Args:- mode: The browser mode to check ('chromium', 'real', or 'remote')-- Returns:- True if the mode is available, False otherwise- """- config = get_config()- installed = config.get('installed_modes', [])-- # Map 'real' to same category as 'chromium' (both are local)- # If either local mode is installed, both are available- if mode in LOCAL_MODES:- return bool(LOCAL_MODES & set(installed))-- return mode in installed---def get_default_mode() -> str:- """Get the default browser mode based on installation config."""- return get_config().get('default_mode', 'chromium')---def get_available_modes() -> list[str]:- """Get list of available browser modes."""- return get_config().get('installed_modes', ['chromium', 'real', 'remote'])---def get_mode_unavailable_error(mode: str) -> str:- """Generate a helpful error message when a mode is not available.-- Args:- mode: The unavailable mode that was requested-- Returns:- A formatted error message with instructions for reinstalling- """- available = get_available_modes()-- if mode in LOCAL_MODES:- install_flag = '--full'- mode_desc = 'Local browser mode'- else:- install_flag = '--full'- mode_desc = 'Remote browser mode'-- return (- f"Error: {mode_desc} '{mode}' not installed.\n"- f'Available modes: {", ".join(available)}\n\n'- f'To install all modes, reinstall with:\n'- f' curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- {install_flag}'- )diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pyindex 09b727bf7..ee87fbe34 100755--- a/browser_use/skill_cli/main.py+++ b/browser_use/skill_cli/main.py@@ -123,7 +123,7 @@ if '--template' in sys.argv:# Keep --force/-f and --list/-l flagselif arg in ('--force', '-f', '--list', '-l'):new_argv.append(arg)- # Skip other flags (--browser, --headed, etc.)+ # Skip other flags (--headed, etc.)i += 1sys.argv = new_argv@@ -175,7 +175,6 @@ def _is_daemon_alive() -> bool:def ensure_daemon(- browser: str,headed: bool,profile: str | None,api_key: str | None,@@ -187,12 +186,12 @@ def ensure_daemon(if not explicit_config:return # Daemon is alive, user didn't request specific config — reuse it- # User explicitly set --browser/--headed/--profile — check config matches+ # User explicitly set --headed/--profile — check config matchestry:response = send_command('ping', {})if response.get('success'):data = response.get('data', {})- if data.get('browser_mode') == browser and data.get('headed') == headed and data.get('profile') == profile:+ if data.get('headed') == headed and data.get('profile') == profile:return # Already running with correct config# Config mismatch — shutdown and restart@@ -206,8 +205,6 @@ def ensure_daemon(sys.executable,'-m','browser_use.skill_cli.daemon',- '--browser',- browser,]if headed:cmd.append('--headed')@@ -283,14 +280,6 @@ def send_command(action: str, params: dict) -> dict:def build_parser() -> argparse.ArgumentParser:"""Build argument parser with all commands."""- # Import install config to get available modes and default- from browser_use.skill_cli.install_config import get_available_modes, get_default_mode-- available_modes = [m for m in get_available_modes() if m != 'remote']- default_mode = get_default_mode()- if default_mode == 'remote':- default_mode = 'chromium'-# Build epilogepilog_parts = []@@ -312,15 +301,14 @@ Setup:)# Global flags+ parser.add_argument('--headed', action='store_true', help='Show browser window')parser.add_argument(- '--browser',- '-b',- choices=available_modes,- default=default_mode,- help=f'Browser mode (available: {", ".join(available_modes)})',+ '--profile',+ nargs='?',+ const='Default',+ default=None,+ help='Use real Chrome with profile (bare --profile uses "Default")',)- parser.add_argument('--headed', action='store_true', help='Show browser window')- parser.add_argument('--profile', help='Browser profile (local name)')parser.add_argument('--json', action='store_true', help='Output as JSON')parser.add_argument('--api-key', help='LLM API key')parser.add_argument('--mcp', action='store_true', help='Run as MCP server (JSON-RPC via stdin/stdout)')@@ -548,10 +536,10 @@ Setup:subparsers.add_parser('close', help='Close browser and stop daemon')# -------------------------------------------------------------------------- # Profile Management (local only, use -b real)+ # Profile Management# -------------------------------------------------------------------------- profile_p = subparsers.add_parser('profile', help='Manage local browser profiles (use -b real)')+ profile_p = subparsers.add_parser('profile', help='Manage local browser profiles')profile_sub = profile_p.add_subparsers(dest='profile_command')# profile list@@ -562,7 +550,7 @@ Setup:p.add_argument('id', help='Profile ID or name')# profile cookies <id>- p = profile_sub.add_parser('cookies', help='List cookies by domain (requires -b real)')+ p = profile_sub.add_parser('cookies', help='List cookies by domain')p.add_argument('id', help='Profile ID or name (e.g. "Default", "Profile 1")')return parser@@ -606,7 +594,6 @@ def main() -> int:else:if result.get('status') == 'success':print('\n✓ Setup complete!')- print(f'\nMode: {result["mode"]}')print('Next: browser-use open https://example.com')return 0@@ -724,33 +711,18 @@ def main() -> int:print('No active browser session')return 0- # Validate requested mode is available based on installation config- from browser_use.skill_cli.install_config import get_mode_unavailable_error, is_mode_available-- if not is_mode_available(args.browser):- print(get_mode_unavailable_error(args.browser), file=sys.stderr)- return 1-# Set API key in environment if providedif args.api_key:os.environ['BROWSER_USE_API_KEY'] = args.api_key- # Validate --profile flag usage- if args.profile and args.browser == 'chromium':- print(- 'Error: --profile is not supported in chromium mode.\nUse -b real for local Chrome profiles.',- file=sys.stderr,- )- return 1-# Ensure daemon is running# Only restart on config mismatch if the user explicitly passed config flags- explicit_config = any(flag in sys.argv for flag in ('--browser', '-b', '--headed', '--profile'))- ensure_daemon(args.browser, args.headed, args.profile, args.api_key, explicit_config=explicit_config)+ explicit_config = any(flag in sys.argv for flag in ('--headed', '--profile'))+ ensure_daemon(args.headed, args.profile, args.api_key, explicit_config=explicit_config)# Build params from argsparams = {}- skip_keys = {'command', 'browser', 'headed', 'json', 'api_key'}+ skip_keys = {'command', 'headed', 'json', 'api_key'}for key, value in vars(args).items():if key not in skip_keys and value is not None:@@ -765,16 +737,10 @@ def main() -> int:# Output responseif args.json:- # Add mode to JSON output for browser-related commands- if args.command in ('open', 'run', 'state', 'click', 'type', 'input', 'scroll', 'screenshot'):- response['mode'] = args.browserprint(json.dumps(response))else:if response.get('success'):data = response.get('data')- # Show mode for browser-related commands (first line of output)- if args.command in ('open', 'run'):- print(f'mode: {args.browser}')if data is not None:if isinstance(data, dict):# Special case: raw text output (e.g., state command)diff --git a/browser_use/skill_cli/sessions.py b/browser_use/skill_cli/sessions.pyindex 014199f87..b60f3607f 100644--- a/browser_use/skill_cli/sessions.py+++ b/browser_use/skill_cli/sessions.py@@ -14,7 +14,6 @@ class SessionInfo:"""Information about a browser session."""name: str- browser_mode: strheaded: boolprofile: str | Nonebrowser_session: BrowserSession@@ -22,48 +21,33 @@ class SessionInfo:async def create_browser_session(- mode: str,headed: bool,profile: str | None,) -> BrowserSession:- """Create BrowserSession based on mode.+ """Create BrowserSession based on whether a profile is specified.- Modes:- - chromium: Playwright-managed Chromium (default)- - real: User's Chrome with profile-- Raises:- RuntimeError: If the requested mode is not available based on installation config+ - No profile: Playwright-managed Chromium (default)+ - With profile: User's real Chrome with the specified profile"""- from browser_use.skill_cli.install_config import get_mode_unavailable_error, is_mode_available-- # Validate mode is available based on installation config- if not is_mode_available(mode):- raise RuntimeError(get_mode_unavailable_error(mode))-- if mode == 'chromium':+ if profile is None:return BrowserSession(headless=not headed,)- elif mode == 'real':- from browser_use.skill_cli.utils import find_chrome_executable, get_chrome_profile_path+ 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')+ chrome_path = find_chrome_executable()+ if not chrome_path:+ raise RuntimeError('Could not find Chrome executable. Please install Chrome or omit --profile to use Chromium.')- # Always get the Chrome user data directory (not the profile subdirectory)- user_data_dir = get_chrome_profile_path(None)- # Profile directory defaults to 'Default', or use the specified profile name- profile_directory = profile if profile else 'Default'-- return BrowserSession(- executable_path=chrome_path,- user_data_dir=user_data_dir,- profile_directory=profile_directory,- headless=not headed, # Headless by default, --headed for visible- )+ # Always get the Chrome user data directory (not the profile subdirectory)+ user_data_dir = get_chrome_profile_path(None)+ # Profile directory defaults to 'Default', or use the specified profile name+ profile_directory = profile- else:- raise ValueError(f'Unknown browser mode: {mode}')+ return BrowserSession(+ executable_path=chrome_path,+ user_data_dir=user_data_dir,+ profile_directory=profile_directory,+ headless=not headed,+ )diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdindex c09a3d6cc..bc5619c0b 100644--- a/skills/browser-use/SKILL.md+++ b/skills/browser-use/SKILL.md@@ -29,14 +29,14 @@ For more information, see https://github.com/browser-use/browser-use/blob/main/b## Browser Modes```bash-browser-use --browser chromium open <url> # Default: headless Chromium-browser-use --browser chromium --headed open <url> # Visible Chromium window-browser-use --browser real open <url> # Real Chrome (no profile = fresh)-browser-use --browser real --profile "Default" open <url> # Real Chrome with your login sessions+browser-use open <url> # Default: headless Chromium+browser-use --headed open <url> # Visible Chromium window+browser-use --profile open <url> # Real Chrome with Default profile+browser-use --profile "Profile 1" open <url> # Real Chrome with named profile```-- **chromium**: Fast, isolated, headless by default-- **real**: Uses a real Chrome binary. Without `--profile`, uses a persistent but empty CLI profile at `~/.config/browseruse/profiles/cli/`. With `--profile "ProfileName"`, copies your actual Chrome profile (cookies, logins, extensions)+- **Default (no --profile)**: Fast, isolated Chromium, headless by default+- **With --profile**: Uses your real Chrome binary with the specified profile (cookies, logins, extensions). Bare `--profile` uses "Default".## Essential Commands@@ -189,11 +189,11 @@ browser-use close # Close browser session### Profile Management-#### Local Chrome Profiles (`--browser real`)+#### Local Chrome Profiles```bash-browser-use -b real profile list # List local Chrome profiles-browser-use -b real profile get "Default" # Get profile details-browser-use -b real profile cookies "Default" # Show cookie domains in profile+browser-use profile list # List local Chrome profiles+browser-use profile get "Default" # Get profile details+browser-use profile cookies "Default" # Show cookie domains in profile```## Common Workflows@@ -212,7 +212,7 @@ Use when a task requires browsing a site the user is already logged into (e.g. G#### Step 1: Check existing profiles```bash-browser-use -b real profile list+browser-use profile list# → Default: Person 1 ([email protected])# → Profile 1: Work ([email protected])```@@ -220,15 +220,15 @@ browser-use -b real profile list#### Step 2: Browse with the chosen profile```bash-# Real browser — uses local Chrome with existing login sessions-browser-use --browser real --profile "Default" open https://github.com+# Real Chrome — uses existing login sessions from the chosen profile+browser-use --profile "Default" open https://github.com```The user is already authenticated — no login needed.#### Check what cookies a profile has```bash-browser-use -b real profile cookies "Default"+browser-use profile cookies "Default"# → youtube.com: 23# → google.com: 18# → github.com: 2@@ -258,9 +258,8 @@ browser-use screenshot| Option | Description ||--------|-------------|-| `--browser MODE` | Browser mode: chromium, real |-| `--headed` | Show browser window (chromium mode) |-| `--profile NAME` | Browser profile (local Chrome profile name) |+| `--headed` | Show browser window |+| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") || `--json` | Output as JSON || `--mcp` | Run as MCP server via stdin/stdout |diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.mdindex ffeb02373..58b7e0268 100644--- a/skills/remote-browser/SKILL.md+++ b/skills/remote-browser/SKILL.md@@ -211,7 +211,8 @@ browser-use screenshot| Option | Description ||--------|-------------|-| `--browser MODE` | Browser mode: chromium, real |+| `--headed` | Show browser window |+| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") || `--json` | Output as JSON |## Tipsdiff --git a/tests/ci/test_cli_coordinate_click.py b/tests/ci/test_cli_coordinate_click.pyindex f4dc22da6..21a17a996 100644--- a/tests/ci/test_cli_coordinate_click.py+++ b/tests/ci/test_cli_coordinate_click.py@@ -70,7 +70,6 @@ class TestClickCommandHandler:session_info = SessionInfo(name='test',- browser_mode='chromium',headed=False,profile=None,browser_session=session,@@ -102,7 +101,6 @@ class TestClickCommandHandler:session_info = SessionInfo(name='test',- browser_mode='chromium',headed=False,profile=None,browser_session=session,@@ -124,7 +122,6 @@ class TestClickCommandHandler:# 3-arg error branch before doing anything with the session.session_info = SessionInfo(name='test',- browser_mode='chromium',headed=False,profile=None,browser_session=BrowserSession(headless=True),diff --git a/tests/ci/test_cli_headed_flag.py b/tests/ci/test_cli_headed_flag.pyindex 7145fa4f6..2a3b1f400 100644--- a/tests/ci/test_cli_headed_flag.py+++ b/tests/ci/test_cli_headed_flag.py@@ -19,16 +19,6 @@ def test_headed_flag_before_open_subcommand():assert args.command == 'open'-def test_headed_flag_with_browser():- """Test that --headed works with other global flags like --browser."""- parser = build_parser()-- args = parser.parse_args(['--headed', '-b', 'chromium', 'open', 'http://example.com'])- assert args.headed is True- assert args.browser == 'chromium'- assert args.url == 'http://example.com'--def test_headed_flag_default_is_false():"""Test that --headed defaults to False when not specified."""parser = build_parser()@@ -37,10 +27,41 @@ def test_headed_flag_default_is_false():assert args.headed is False, '--headed should default to False'-def test_headed_flag_with_browser_mode():- """Test --headed works with --browser flag."""+def test_headed_flag_with_profile():+ """Test --headed works with --profile flag."""parser = build_parser()- args = parser.parse_args(['--headed', '--browser', 'chromium', 'open', 'http://example.com'])+ args = parser.parse_args(['--headed', '--profile', 'Default', 'open', 'http://example.com'])assert args.headed is True- assert args.browser == 'chromium'+ assert args.profile == 'Default'+++def test_profile_bare_flag():+ """Test bare --profile defaults to 'Default'.++ Note: bare --profile only works when followed by another flag (not a subcommand),+ because argparse nargs='?' greedily consumes the next non-flag token as the value.+ """+ parser = build_parser()++ # Bare --profile before another flag: const='Default' is used+ args = parser.parse_args(['--profile', '--headed', 'open', 'http://example.com'])+ assert args.profile == 'Default'+ assert args.headed is True+ assert args.command == 'open'+++def test_profile_with_name():+ """Test --profile with an explicit name."""+ parser = build_parser()++ args = parser.parse_args(['--profile', 'Profile 1', 'open', 'http://example.com'])+ assert args.profile == 'Profile 1'+++def test_no_profile_defaults_to_none():+ """Test that profile defaults to None when not specified."""+ parser = build_parser()++ args = parser.parse_args(['open', 'http://example.com'])+ assert args.profile is Nonediff --git a/tests/ci/test_install_config.py b/tests/ci/test_install_config.pydeleted file mode 100644index 02b389e1e..000000000--- a/tests/ci/test_install_config.py+++ /dev/null@@ -1,179 +0,0 @@-"""Tests for install configuration module."""--import json-from pathlib import Path-from unittest.mock import patch--import pytest---class TestInstallConfig:- """Tests for browser_use.skill_cli.install_config module."""-- @pytest.fixture- def temp_config_dir(self, tmp_path: Path):- """Create a temporary config directory and patch CONFIG_PATH."""- config_path = tmp_path / 'install-config.json'- with patch('browser_use.skill_cli.install_config.CONFIG_PATH', config_path):- yield config_path-- def test_get_config_default_all_modes(self, temp_config_dir: Path):- """If no config file, all modes available (pip install users)."""- from browser_use.skill_cli.install_config import get_config-- # Config file doesn't exist- assert not temp_config_dir.exists()-- config = get_config()- assert config['installed_modes'] == ['chromium', 'real', 'remote']- assert config['default_mode'] == 'chromium'-- def test_get_config_reads_existing_file(self, temp_config_dir: Path):- """Config is read from existing file."""- from browser_use.skill_cli.install_config import get_config-- # Create config file with remote-only mode- temp_config_dir.parent.mkdir(parents=True, exist_ok=True)- temp_config_dir.write_text(json.dumps({'installed_modes': ['remote'], 'default_mode': 'remote'}))-- config = get_config()- assert config['installed_modes'] == ['remote']- assert config['default_mode'] == 'remote'-- def test_get_config_handles_corrupt_file(self, temp_config_dir: Path):- """Corrupt config file returns default."""- from browser_use.skill_cli.install_config import get_config-- # Create corrupt config file- temp_config_dir.parent.mkdir(parents=True, exist_ok=True)- temp_config_dir.write_text('not valid json {{{')-- config = get_config()- # Should return default- assert config['installed_modes'] == ['chromium', 'real', 'remote']- assert config['default_mode'] == 'chromium'-- def test_save_config_creates_file(self, temp_config_dir: Path):- """save_config creates the config file."""- from browser_use.skill_cli.install_config import save_config-- assert not temp_config_dir.exists()-- save_config(['remote'], 'remote')-- assert temp_config_dir.exists()- config = json.loads(temp_config_dir.read_text())- assert config['installed_modes'] == ['remote']- assert config['default_mode'] == 'remote'-- def test_save_config_creates_parent_directories(self, tmp_path: Path):- """save_config creates parent directories if needed."""- from browser_use.skill_cli.install_config import save_config-- nested_path = tmp_path / 'deep' / 'nested' / 'install-config.json'- with patch('browser_use.skill_cli.install_config.CONFIG_PATH', nested_path):- save_config(['chromium', 'real'], 'chromium')-- assert nested_path.exists()-- def test_is_mode_available_remote_only(self, temp_config_dir: Path):- """Config with only remote mode blocks local modes."""- from browser_use.skill_cli.install_config import is_mode_available, save_config-- save_config(['remote'], 'remote')-- assert is_mode_available('remote') is True- assert is_mode_available('chromium') is False- assert is_mode_available('real') is False-- def test_is_mode_available_local_only(self, temp_config_dir: Path):- """Config with only local modes blocks remote mode."""- from browser_use.skill_cli.install_config import is_mode_available, save_config-- save_config(['chromium', 'real'], 'chromium')-- assert is_mode_available('chromium') is True- assert is_mode_available('real') is True- assert is_mode_available('remote') is False-- def test_is_mode_available_full_install(self, temp_config_dir: Path):- """Config with all modes allows everything."""- from browser_use.skill_cli.install_config import is_mode_available, save_config-- save_config(['chromium', 'real', 'remote'], 'chromium')-- assert is_mode_available('chromium') is True- assert is_mode_available('real') is True- assert is_mode_available('remote') is True-- def test_is_mode_available_local_modes_linked(self, temp_config_dir: Path):- """If chromium is installed, real is also available (and vice versa)."""- from browser_use.skill_cli.install_config import is_mode_available, save_config-- # Only chromium in the list, but real should also work- save_config(['chromium'], 'chromium')-- assert is_mode_available('chromium') is True- assert is_mode_available('real') is True # Linked to chromium-- # Only real in the list- save_config(['real'], 'real')-- assert is_mode_available('chromium') is True # Linked to real- assert is_mode_available('real') is True-- def test_get_default_mode(self, temp_config_dir: Path):- """Default --browser value comes from config."""- from browser_use.skill_cli.install_config import get_default_mode, save_config-- # Remote-only install- save_config(['remote'], 'remote')- assert get_default_mode() == 'remote'-- # Local-only install- save_config(['chromium', 'real'], 'chromium')- assert get_default_mode() == 'chromium'-- def test_get_available_modes(self, temp_config_dir: Path):- """get_available_modes returns list from config."""- from browser_use.skill_cli.install_config import get_available_modes, save_config-- save_config(['remote'], 'remote')- assert get_available_modes() == ['remote']-- save_config(['chromium', 'real', 'remote'], 'chromium')- assert get_available_modes() == ['chromium', 'real', 'remote']-- def test_get_mode_unavailable_error_message(self, temp_config_dir: Path):- """Clear error when requesting unavailable mode."""- from browser_use.skill_cli.install_config import get_mode_unavailable_error, save_config-- save_config(['remote'], 'remote')-- error = get_mode_unavailable_error('chromium')- assert 'chromium' in error- assert 'not installed' in error.lower()- assert 'remote' in error # Shows available modes- assert '--full' in error # Shows reinstall instructions-- def test_no_config_file_means_all_modes_available(self, temp_config_dir: Path):- """pip install users (no config file) have all modes available."""- from browser_use.skill_cli.install_config import (- get_available_modes,- get_default_mode,- is_mode_available,- )-- # Ensure no config exists- assert not temp_config_dir.exists()-- # All modes should be available- assert is_mode_available('chromium') is True- assert is_mode_available('real') is True- assert is_mode_available('remote') is True-- # Default should be chromium- assert get_default_mode() == 'chromium'-- # All modes should be in the list- assert get_available_modes() == ['chromium', 'real', 'remote']