Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

changes

ShawnPana4be221386b1b
diff --git a/browser_use/skill_cli/README.md b/browser_use/skill_cli/README.md
index 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
```bash
browser-use doctor # Validate installation
browser-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 window
browser-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 model
Requires 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 browser
npm run dev & # localhost:3000
browser-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 Skill
For [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.py
index 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.py
index 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_mode
self.headed = headed
self.profile = profile
self.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.sh
index 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 dependencies
install_dependencies
- # Step 6: Write install config
- write_install_config
-
- # Step 7: Configure PATH
+ # Step 6: Configure PATH
configure_path
- # Step 8: Run setup wizard
+ # Step 7: Run setup wizard
run_setup
- # Step 9: Validate
+ # Step 8: Validate
validate
- # Step 10: Show next steps
+ # Step 9: Show next steps
print_next_steps
}
diff --git a/browser_use/skill_cli/install_config.py b/browser_use/skill_cli/install_config.py
deleted file mode 100644
index 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.py
index 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 flags
elif arg in ('--force', '-f', '--list', '-l'):
new_argv.append(arg)
- # Skip other flags (--browser, --headed, etc.)
+ # Skip other flags (--headed, etc.)
i += 1
sys.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 matches
try:
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 epilog
epilog_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 provided
if 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 args
params = {}
- 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 response
if 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.browser
print(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.py
index 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: str
headed: bool
profile: str | None
browser_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.md
index 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.md
index 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 |
## Tips
diff --git a/tests/ci/test_cli_coordinate_click.py b/tests/ci/test_cli_coordinate_click.py
index 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.py
index 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 None
diff --git a/tests/ci/test_install_config.py b/tests/ci/test_install_config.py
deleted file mode 100644
index 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']