Skip to content

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

docs(cli): add missing commands and flags to skill documentation

ShawnPanaada8b77d0b40
diff --git a/browser_use/skill_cli/README.md b/browser_use/skill_cli/README.md
index 15d338256..b39faa4a8 100644
--- a/browser_use/skill_cli/README.md
+++ b/browser_use/skill_cli/README.md
@@ -36,6 +36,17 @@ curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --api-key bu_xxx
```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
+```bash
+browser-use init # Interactive template selection
+browser-use init --list # List available templates
+browser-use init --template basic # Generate specific template
+browser-use init --output my_script.py # Specify output file
+browser-use init --force # Overwrite existing files
```
### From Source
@@ -147,6 +158,8 @@ browser-use --browser remote open https://example.com
| `cookies get --url <url>` | Get cookies for URL |
| `cookies set <name> <value>` | Set a cookie |
| `cookies set name val --domain .example.com --secure` | Set with options |
+| `cookies set name val --same-site Strict` | SameSite: Strict, Lax, None |
+| `cookies set name val --expires 1735689600` | Set expiration timestamp |
| `cookies clear` | Clear all cookies |
| `cookies clear --url <url>` | Clear cookies for URL |
| `cookies export <file>` | Export to JSON file |
@@ -207,11 +220,26 @@ 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`.
@@ -224,10 +252,13 @@ Manage cloud tasks when using `--browser remote`.
|---------|-------------|
| `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 |
@@ -242,6 +273,15 @@ Manage cloud browser sessions.
| `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
@@ -275,8 +315,10 @@ browser-use -b remote open https://abc.trycloudflare.com
| Command | Description |
|---------|-------------|
| `profile list` | List cloud profiles |
+| `profile list --page 2 --page-size 50` | Pagination |
| `profile get <id>` | Get profile details |
-| `profile create --name <name>` | Create profile |
+| `profile create` | Create profile |
+| `profile create --name "My Profile"` | Create with name |
| `profile update <id> --name <name>` | Rename profile |
| `profile delete <id>` | Delete profile |
@@ -301,6 +343,7 @@ browser-use -b remote open https://abc.trycloudflare.com
| `--profile NAME` | Browser profile (local name or cloud ID) |
| `--json` | Output as JSON |
| `--api-key KEY` | Override API key |
+| `--mcp` | Run as MCP server via stdin/stdout |
**Session behavior**: All commands without `--session` use the same "default" session. The browser stays open and is reused across commands. Use `--session NAME` to run multiple browsers in parallel.
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.md
index 4504926bb..5203041ac 100644
--- a/skills/browser-use/SKILL.md
+++ b/skills/browser-use/SKILL.md
@@ -55,6 +55,25 @@ curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only --a
browser-use doctor
```
+**Setup wizard (first-time configuration):**
+```bash
+browser-use setup # Interactive setup
+browser-use setup --mode local # Configure for local browser only
+browser-use setup --mode remote # Configure for cloud browser only
+browser-use setup --mode full # Configure all modes
+browser-use setup --api-key bu_xxx # Set API key during setup
+browser-use setup --yes # Skip interactive prompts
+```
+
+**Generate template files:**
+```bash
+browser-use init # Interactive template selection
+browser-use init --list # List available templates
+browser-use init --template basic # Generate specific template
+browser-use init --output my_script.py # Specify output file
+browser-use init --force # Overwrite existing files
+```
+
**Manual cloudflared install (for tunneling):**
```bash
# macOS:
@@ -107,6 +126,7 @@ browser-use open <url> # Navigate to URL
browser-use back # Go back in history
browser-use scroll down # Scroll down
browser-use scroll up # Scroll up
+browser-use scroll down --amount 1000 # Scroll by specific pixels (default: 500)
```
### Page State
@@ -146,6 +166,8 @@ browser-use cookies get # Get all cookies
browser-use cookies get --url <url> # Get cookies for specific URL
browser-use cookies set <name> <value> # Set a cookie
browser-use cookies set name val --domain .example.com --secure --http-only
+browser-use cookies set name val --same-site Strict # SameSite: Strict, Lax, or None
+browser-use cookies set name val --expires 1735689600 # Expiration timestamp
browser-use cookies clear # Clear all cookies
browser-use cookies clear --url <url> # Clear cookies for specific URL
browser-use cookies export <file> # Export all cookies to JSON file
@@ -193,12 +215,17 @@ browser-use 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.html` - Get page HTML
- `browser.goto(url)` - Navigate
- `browser.click(index)` - Click element
- `browser.type(text)` - Type text
+- `browser.input(index, text)` - Click element, then type
+- `browser.keys(keys)` - Send keyboard keys (e.g., "Enter", "Control+a")
- `browser.screenshot(path)` - Take screenshot
-- `browser.scroll()` - Scroll page
-- `browser.html` - Get page HTML
+- `browser.scroll(direction, amount)` - Scroll page
+- `browser.back()` - Go back in history
+- `browser.wait(seconds)` - Sleep/pause execution
+- `browser.extract(query)` - Extract data using LLM
### Agent Tasks (Requires API Key)
```bash
@@ -239,9 +266,22 @@ browser-use -b remote run "task" --flash # Fast execution mode
browser-use -b remote run "task" --thinking # Extended reasoning mode
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" --wait # Wait for completion (default: async)
# Use cloud profile (preserves cookies across sessions)
browser-use -b remote run "task" --profile <cloud-profile-id>
+
+# Task configuration
+browser-use -b remote run "task" --start-url https://example.com # Start from specific 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 for output
+browser-use -b remote run "task" --judge # Enable judge mode
+browser-use -b remote run "task" --judge-ground-truth "expected answer" # Expected answer for judge
```
### Task Management (Remote Mode)
@@ -252,12 +292,15 @@ Manage cloud tasks when using remote mode:
browser-use task list # List recent tasks
browser-use task list --limit 20 # Show more tasks
browser-use task list --status running # Filter by status
+browser-use task list --session <id> # Filter by session ID
browser-use task list --json # JSON output
browser-use task status <task-id> # Get task status (token efficient)
browser-use task status <task-id> -c # Show all steps with reasoning
browser-use task status <task-id> -v # Show all steps with URLs + actions
browser-use task status <task-id> --last 5 # Show only last 5 steps
+browser-use task status <task-id> --step 3 # Show specific step number
+browser-use task status <task-id> --reverse # Show steps newest first
browser-use task stop <task-id> # Stop a running task
browser-use task logs <task-id> # Get task execution logs
@@ -280,6 +323,19 @@ browser-use session get <session-id> --json
browser-use session stop <session-id> # Stop a session
browser-use session stop --all # Stop all active sessions
+
+# Create a new cloud session manually
+browser-use session create # Create with defaults
+browser-use session create --profile <id> # With cloud profile
+browser-use session create --proxy-country gb # With geographic proxy
+browser-use session create --start-url https://example.com # Start at URL
+browser-use session create --screen-size 1920x1080 # Custom screen size
+browser-use session create --keep-alive # Keep session alive
+browser-use session create --persist-memory # Persist memory between tasks
+
+# Share session publicly (for collaboration/debugging)
+browser-use session share <session-id> # Create public share URL
+browser-use session share <session-id> --delete # Delete public share
```
## Exposing Local Dev Servers
@@ -527,14 +583,16 @@ browser-use close --all # Close all sessions
```
### Profile Management
+
+#### Local Chrome Profiles (`--browser real`)
```bash
-browser-use profile list-local # List local Chrome profiles
+browser-use -b real profile list # List local Chrome profiles
```
-**Before opening a real browser (`--browser real`)**, always ask the user if they want to use a specific Chrome profile or no profile. Use `profile list-local` to show available profiles:
+**Before opening a real browser (`--browser real`)**, always ask the user if they want to use a specific Chrome profile or no profile. Use `profile list` to show available profiles:
```bash
-browser-use profile list-local
+browser-use -b real profile list
# Output: Default: Person 1 ([email protected])
# Profile 1: Work ([email protected])
@@ -550,15 +608,18 @@ browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
Each Chrome profile has its own cookies, history, and logged-in sessions. Choosing the right profile determines whether sites will be pre-authenticated.
-### Cloud Profiles
+#### Cloud Profiles (`--browser remote`)
Cloud profiles store browser state (cookies) in Browser-Use Cloud, persisting across sessions. Requires `BROWSER_USE_API_KEY`.
```bash
-browser-use profile list # List cloud profiles
-browser-use profile get <id> # Get profile details
-browser-use profile update <id> --name "New" # Rename profile
-browser-use profile delete <id> # Delete profile
+browser-use -b remote profile list # List cloud profiles
+browser-use -b remote profile list --page 2 --page-size 50 # Pagination
+browser-use -b remote profile get <id> # Get profile details
+browser-use -b remote profile create # Create new cloud profile
+browser-use -b remote profile create --name "My Profile" # Create with name
+browser-use -b remote profile update <id> --name "New" # Rename profile
+browser-use -b remote profile delete <id> # Delete profile
```
Use a cloud profile with `--browser remote --profile <id>`:
@@ -570,7 +631,7 @@ browser-use --browser remote --profile abc-123 open https://example.com
### Syncing Cookies to Cloud
**⚠️ IMPORTANT: Before syncing cookies from a local browser to the cloud, the agent MUST:**
-1. Ask the user which local Chrome profile to use (`browser-use profile list-local`)
+1. Ask the user which local Chrome profile to use (`browser-use -b real profile list`)
2. Ask which domain(s) to sync - do NOT default to syncing the full profile
3. Confirm before proceeding
@@ -580,12 +641,12 @@ browser-use --browser remote --profile abc-123 open https://example.com
```bash
# List local Chrome profiles
-browser-use profile list-local
+browser-use -b real profile list
# → Default: Person 1 ([email protected])
# → Profile 1: Work ([email protected])
# See what cookies are in a profile
-browser-use profile cookies "Default"
+browser-use -b real profile cookies "Default"
# → youtube.com: 23
# → google.com: 18
# → github.com: 2
@@ -661,6 +722,7 @@ browser-use install # Install Chromium and system dependen
| `--profile NAME` | Browser profile (local name or cloud ID) |
| `--json` | Output as JSON |
| `--api-key KEY` | Override API key |
+| `--mcp` | Run as MCP server via stdin/stdout |
**Session behavior**: All commands without `--session` use the same "default" session. The browser stays open and is reused across commands. Use `--session NAME` to run multiple browsers in parallel.
diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.md
index f20af006c..15400fee2 100644
--- a/skills/remote-browser/SKILL.md
+++ b/skills/remote-browser/SKILL.md
@@ -116,6 +116,7 @@ browser-use open <url> # Navigate to URL
browser-use back # Go back in history
browser-use scroll down # Scroll down
browser-use scroll up # Scroll up
+browser-use scroll down --amount 1000 # Scroll by specific pixels (default: 500)
```
### Page State
@@ -142,12 +143,14 @@ browser-use rightclick <index> # Right-click
### JavaScript & Data
```bash
browser-use eval "document.title" # Execute JavaScript
+browser-use extract "all prices" # Extract data using LLM
browser-use get title # Get page title
browser-use get html # Get page HTML
browser-use get html --selector "h1" # Scoped HTML
browser-use get text <index> # Get element text
browser-use get value <index> # Get input value
browser-use get attributes <index> # Get element attributes
+browser-use get bbox <index> # Get bounding box (x, y, width, height)
```
### Wait Conditions
@@ -161,8 +164,13 @@ browser-use wait selector "#btn" --timeout 5000 # Custom timeout (ms)
### Cookies
```bash
browser-use cookies get # Get all cookies
+browser-use cookies get --url <url> # Get cookies for specific URL
browser-use cookies set <name> <val> # Set a cookie
+browser-use cookies set name val --domain .example.com --secure # With options
+browser-use cookies set name val --same-site Strict # SameSite: Strict, Lax, None
+browser-use cookies set name val --expires 1735689600 # Expiration timestamp
browser-use cookies clear # Clear all cookies
+browser-use cookies clear --url <url> # Clear cookies for specific URL
browser-use cookies export <file> # Export to JSON
browser-use cookies import <file> # Import from JSON
```
@@ -174,6 +182,31 @@ browser-use close-tab # Close current tab
browser-use close-tab <tab> # Close specific tab
```
+### Python Execution (Persistent Session)
+```bash
+browser-use python "x = 42" # Set variable
+browser-use python "print(x)" # Access variable (prints: 42)
+browser-use python "print(browser.url)" # Access browser object
+browser-use python --vars # Show defined variables
+browser-use python --reset # Clear namespace
+browser-use python --file script.py # Run Python file
+```
+
+The Python session maintains state across commands. The `browser` object provides:
+- `browser.url` - Current page URL
+- `browser.title` - Page title
+- `browser.html` - Get page HTML
+- `browser.goto(url)` - Navigate
+- `browser.click(index)` - Click element
+- `browser.type(text)` - Type text
+- `browser.input(index, text)` - Click element, then type
+- `browser.keys(keys)` - Send keyboard keys
+- `browser.screenshot(path)` - Take screenshot
+- `browser.scroll(direction, amount)` - Scroll page
+- `browser.back()` - Go back in history
+- `browser.wait(seconds)` - Sleep/pause execution
+- `browser.extract(query)` - Extract data using LLM
+
### Agent Tasks
```bash
browser-use run "Fill the contact form with test data" # AI agent
@@ -195,6 +228,7 @@ browser-use run "task 2" --session-id abc-123
# Execution modes
browser-use run "task" --no-wait # Async, returns task_id immediately
+browser-use run "task" --wait # Wait for completion
browser-use run "task" --stream # Stream status updates
browser-use run "task" --flash # Fast execution mode
@@ -205,6 +239,18 @@ browser-use run "task" --no-vision # Disable vision
# Use cloud profile (preserves cookies across sessions)
browser-use run "task" --profile <cloud-profile-id>
+
+# Task configuration
+browser-use run "task" --start-url https://example.com # Start from specific URL
+browser-use run "task" --allowed-domain example.com # Restrict navigation (repeatable)
+browser-use run "task" --metadata key=value # Task metadata (repeatable)
+browser-use run "task" --secret API_KEY=xxx # Task secrets (repeatable)
+browser-use run "task" --skill-id skill-123 # Enable skills (repeatable)
+
+# Structured output and evaluation
+browser-use run "task" --structured-output '{"type":"object"}' # JSON schema for output
+browser-use run "task" --judge # Enable judge mode
+browser-use run "task" --judge-ground-truth "answer" # Expected answer for judge
```
### Task Management
@@ -216,9 +262,15 @@ browser-use task list # List recent tasks
browser-use task list --limit 20 # Show more tasks
browser-use task list --status running # Filter by status
browser-use task list --status finished
+browser-use task list --session <id> # Filter by session ID
browser-use task list --json # JSON output
-browser-use task status <task-id> # Get task status and output
+browser-use task status <task-id> # Get task status (latest step only)
+browser-use task status <task-id> -c # Compact: all steps with reasoning
+browser-use task status <task-id> -v # Verbose: full details with URLs + actions
+browser-use task status <task-id> --last 5 # Show only last 5 steps
+browser-use task status <task-id> --step 3 # Show specific step number
+browser-use task status <task-id> --reverse # Show steps newest first
browser-use task status <task-id> --json
browser-use task stop <task-id> # Stop a running task
@@ -236,11 +288,59 @@ browser-use session list --limit 20 # Show more sessions
browser-use session list --status active # Filter by status
browser-use session list --json # JSON output
-browser-use session get <session-id> # Get session details
+browser-use session get <session-id> # Get session details + live URL
browser-use session get <session-id> --json
browser-use session stop <session-id> # Stop a session
browser-use session stop --all # Stop all active sessions
+
+# Create a new cloud session manually
+browser-use session create # Create with defaults
+browser-use session create --profile <id> # With cloud profile
+browser-use session create --proxy-country gb # With geographic proxy
+browser-use session create --start-url https://example.com # Start at URL
+browser-use session create --screen-size 1920x1080 # Custom screen size
+browser-use session create --keep-alive # Keep session alive
+browser-use session create --persist-memory # Persist memory between tasks
+
+# Share session publicly (for collaboration/debugging)
+browser-use session share <session-id> # Create public share URL
+browser-use session share <session-id> --delete # Delete public share
+```
+
+### Cloud Profile Management
+
+Cloud profiles store browser state (cookies) persistently across sessions. Use profiles to maintain login sessions.
+
+```bash
+browser-use profile list # List cloud profiles
+browser-use profile list --page 2 --page-size 50 # Pagination
+browser-use profile get <id> # Get profile details
+browser-use profile create # Create new profile
+browser-use profile create --name "My Profile" # Create with name
+browser-use profile update <id> --name "New Name" # Rename profile
+browser-use profile delete <id> # Delete profile
+```
+
+**Using profiles:**
+```bash
+# Run task with profile (preserves cookies)
+browser-use run "Log into site" --profile <profile-id> --keep-alive
+
+# Create session with profile
+browser-use session create --profile <profile-id>
+
+# Open URL with profile
+browser-use open https://example.com --profile <profile-id>
+```
+
+**Import cookies to cloud profile:**
+```bash
+# Export cookies from current session
+browser-use cookies export /tmp/cookies.json
+
+# Import to cloud profile
+browser-use cookies import /tmp/cookies.json --profile <profile-id>
```
## Running Subagents