browser-use

ブラウザー自動化のためのCLIの使用

browser-use コマンドは、高速で永続的なブラウザー自動化を提供します。コマンド間でブラウザーセッションを維持できるため、複雑な複数ステップのワークフローを実行できます。

前提条件

このスキルを使用する前に、browser-use をインストールして設定する必要があります。診断を実行して確認してください。

browser-use doctor

詳しくは、https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md をご覧ください。

基本的なワークフロー

1. 移動：browser-use open <url> — URLを開きます（必要に応じてブラウザーを起動します）
2. 確認：browser-use state — インデックス付きのクリック可能な要素を返します
3. 操作：state のインデックスを使って操作します（browser-use click 5、browser-use input 3 "text"）
4. 検証：browser-use state または browser-use screenshot で操作を確認します
5. 繰り返し：コマンド間でブラウザーは開いたままです

ブラウザーモード

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 --browser remote open <url>        # Cloud browser

• chromium：高速で分離されており、デフォルトではヘッドレスです
• real：実際の Chrome バイナリーを使用します。--profile を指定しない場合、~/.config/browseruse/profiles/cli/ にある、永続的ですが空のCLIプロファイルを使用します。--profile "ProfileName" を指定すると、実際の Chrome プロファイル（Cookie、ログイン情報、拡張機能）をコピーします
• remote：プロキシに対応したクラウドホスト型ブラウザーです

基本コマンド

# Navigation
browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back
browser-use scroll down                   # Scroll down (--amount N for pixels)

# Page State (always run state first to get element indices)
browser-use state                         # Get URL, title, clickable elements
browser-use screenshot                    # Take screenshot (base64)
browser-use screenshot path.png           # Save screenshot to file

# Interactions (use indices from state)
browser-use click <index>                 # Click element
browser-use type "text"                   # Type into focused element
browser-use input <index> "text"          # Click element, then type
browser-use keys "Enter"                  # Send keyboard keys
browser-use select <index> "option"       # Select dropdown option

# Data Extraction
browser-use eval "document.title"         # Execute JavaScript
browser-use get text <index>              # Get element text
browser-use get html --selector "h1"      # Get scoped HTML

# Wait
browser-use wait selector "h1"            # Wait for element
browser-use wait text "Success"           # Wait for text

# Session
browser-use sessions                      # List active sessions
browser-use close                         # Close current session
browser-use close --all                   # Close all sessions

# AI Agent
browser-use -b remote run "task"          # Run agent in cloud (async by default)
browser-use task status <id>              # Check cloud task progress

コマンド

ナビゲーションとタブ

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)
browser-use switch <tab>                  # Switch to tab by index
browser-use close-tab                     # Close current tab
browser-use close-tab <tab>              # Close specific tab

ページの状態

browser-use state                         # Get URL, title, and clickable elements
browser-use screenshot                    # Take screenshot (outputs base64)
browser-use screenshot path.png           # Save screenshot to file
browser-use screenshot --full path.png    # Full page screenshot

操作

browser-use click <index>                 # Click element
browser-use type "text"                   # Type text into focused element
browser-use input <index> "text"          # Click element, then type text
browser-use keys "Enter"                  # Send keyboard keys
browser-use keys "Control+a"              # Send key combination
browser-use select <index> "option"       # Select dropdown option
browser-use hover <index>                 # Hover over element (triggers CSS :hover)
browser-use dblclick <index>              # Double-click element
browser-use rightclick <index>            # Right-click element (context menu)

browser-use state のインデックスを使用します。

JavaScriptとデータ

browser-use eval "document.title"         # Execute JavaScript, return result
browser-use get title                     # Get page title
browser-use get html                      # Get full page HTML
browser-use get html --selector "h1"      # Get HTML of specific element
browser-use get text <index>              # Get text content of element
browser-use get value <index>             # Get value of input/textarea
browser-use get attributes <index>        # Get all attributes of element
browser-use get bbox <index>              # Get bounding box (x, y, width, height)

Cookie

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
browser-use cookies export <file> --url <url>  # Export cookies for specific URL
browser-use cookies import <file>         # Import cookies from JSON file

待機条件

browser-use wait selector "h1"            # Wait for element to be visible
browser-use wait selector ".loading" --state hidden  # Wait for element to disappear
browser-use wait selector "#btn" --state attached    # Wait for element in DOM
browser-use wait text "Success"           # Wait for text to appear
browser-use wait selector "h1" --timeout 5000  # Custom timeout in ms

Python実行

browser-use python "x = 42"               # Set variable
browser-use python "print(x)"             # Access variable (outputs: 42)
browser-use python "print(browser.url)"   # Access browser object
browser-use python --vars                 # Show defined variables
browser-use python --reset                # Clear Python namespace
browser-use python --file script.py       # Execute Python file

Pythonセッションではコマンド間で状態が維持されます。browser オブジェクトでは、次の操作ができます。

• browser.url、browser.title、browser.html — ページ情報
• browser.goto(url)、browser.back() — ナビゲーション
• browser.click(index)、browser.type(text)、browser.input(index, text)、browser.keys(keys) — 操作
• browser.screenshot(path)、browser.scroll(direction, amount) — 表示操作
• browser.wait(seconds)、browser.extract(query) — ユーティリティ

エージェントタスク

リモートモードのオプション

--browser remote を使用する場合、追加のオプションを利用できます。

# Specify LLM model
browser-use -b remote run "task" --llm gpt-4o
browser-use -b remote run "task" --llm claude-sonnet-4-20250514

# Proxy configuration (default: us)
browser-use -b remote run "task" --proxy-country uk

# Session reuse
browser-use -b remote run "task 1" --keep-alive        # Keep session alive after task
browser-use -b remote run "task 2" --session-id abc-123 # Reuse existing session

# Execution modes
browser-use -b remote run "task" --flash       # Fast execution mode
browser-use -b remote run "task" --wait        # Wait for completion (default: async)

# Advanced options
browser-use -b remote run "task" --thinking    # Extended reasoning mode
browser-use -b remote run "task" --no-vision   # Disable vision (enabled by default)

# Using a cloud profile (create session first, then run with --session-id)
browser-use session create --profile <cloud-profile-id> --keep-alive
# → returns session_id
browser-use -b remote run "task" --session-id <session-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" --skill-id skill-123             # Enable skills (repeatable)
browser-use -b remote run "task" --secret key=value               # Secret metadata (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"

タスク管理

browser-use task list                     # List recent tasks
browser-use task list --limit 20          # Show more tasks
browser-use task list --status finished   # Filter by status (finished, stopped)
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 (latest step only)
browser-use task status <task-id> -c      # All steps with reasoning
browser-use task status <task-id> -v      # All steps with URLs + actions
browser-use task status <task-id> --last 5  # Last N steps only
browser-use task status <task-id> --step 3  # Specific step number
browser-use task status <task-id> --reverse # Newest first

browser-use task stop <task-id>           # Stop a running task
browser-use task logs <task-id>           # Get task execution logs

クラウドセッション管理

browser-use session list                  # List cloud sessions
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 + 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

browser-use session create                          # Create with defaults
browser-use session create --profile <id>           # With cloud profile
browser-use session create --proxy-country uk       # With geographic proxy
browser-use session create --start-url https://example.com
browser-use session create --screen-size 1920x1080
browser-use session create --keep-alive
browser-use session create --persist-memory

browser-use session share <session-id>              # Create public share URL
browser-use session share <session-id> --delete     # Delete public share

トンネル

browser-use tunnel <port>           # Start tunnel (returns URL)
browser-use tunnel <port>           # Idempotent - returns existing URL
browser-use tunnel list             # Show active tunnels
browser-use tunnel stop <port>      # Stop tunnel
browser-use tunnel stop --all       # Stop all tunnels

セッション管理

browser-use sessions                      # List active sessions
browser-use close                         # Close current session
browser-use close --all                   # Close all sessions

プロファイル管理

ローカル Chrome プロファイル（--browser real）

browser-use -b real profile list          # List local Chrome profiles
browser-use -b real profile cookies "Default"  # Show cookie domains in profile

クラウドプロファイル（--browser remote）

browser-use -b remote profile list            # List cloud profiles
browser-use -b remote profile list --page 2 --page-size 50
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"
browser-use -b remote profile update <id> --name "New"
browser-use -b remote profile delete <id>

同期

browser-use profile sync --from "Default" --domain github.com  # Domain-specific
browser-use profile sync --from "Default"                      # Full profile
browser-use profile sync --from "Default" --name "Custom Name" # With custom name

サーバー制御

browser-use server logs                   # View server logs

一般的なワークフロー

ローカル開発サーバーの公開

ローカル開発サーバーがあり、クラウドブラウザーからアクセスする必要がある場合に使用します。

基本的なワークフロー： 開発サーバーを起動 → トンネルを作成 → リモートからトンネルURLを閲覧します。

# 1. Start your dev server
npm run dev &  # localhost:3000

# 2. Expose it via Cloudflare tunnel
browser-use tunnel 3000
# → url: https://abc.trycloudflare.com

# 3. Now the cloud browser can reach your local server
browser-use --browser remote open https://abc.trycloudflare.com
browser-use state
browser-use screenshot

注： トンネルはブラウザーセッションとは独立しています。browser-use close の実行後も維持され、個別に管理できます。Cloudflared をインストールする必要があります。browser-use doctor を実行して確認してください。

プロファイルを使った認証済みのブラウジング

ユーザーがすでにログインしているサイト（Gmail、GitHub、社内ツールなど）を閲覧する必要があるタスクで使用します。

基本的なワークフロー： 既存のプロファイルを確認 → 使用するプロファイルとブラウザーモードをユーザーに尋ねる → そのプロファイルを使って閲覧します。適切なプロファイルがない場合に限り、Cookieを同期します。

認証が必要なサイトを閲覧する前に、エージェントは必ず次の操作を行ってください。

1. real（ローカル Chrome）と remote（クラウド）のどちらのブラウザーを使うか、ユーザーに尋ねます
2. そのモードで利用できるプロファイルを一覧表示します
3. 使用するプロファイルをユーザーに尋ねます
4. 適切なCookieを含むプロファイルがない場合は、同期を提案します（以下を参照）

ステップ1：既存のプロファイルを確認する

# Option A: Local Chrome profiles (--browser real)
browser-use -b real profile list
# → Default: Person 1 ([email protected])
# → Profile 1: Work ([email protected])

# Option B: Cloud profiles (--browser remote)
browser-use -b remote profile list
# → abc-123: "Chrome - Default (github.com)"
# → def-456: "Work profile"

ステップ2：選択したプロファイルで閲覧する

# Real browser — uses local Chrome with existing login sessions
browser-use --browser real --profile "Default" open https://github.com

# Cloud browser — uses cloud profile with synced cookies
browser-use --browser remote --profile abc-123 open https://github.com

ユーザーはすでに認証済みのため、ログインは不要です。

注： クラウドプロファイルのCookieは、時間の経過とともに期限切れになることがあります。認証に失敗した場合は、ローカル Chrome プロファイルからCookieを再同期してください。

Step 3: Cookie の同期（必要な場合のみ）

クラウドブラウザーを使いたいものの、適切な Cookie を持つクラウドプロファイルがない場合は、ローカルの Chrome プロファイルから同期します。

同期する前に、エージェントは必ず以下を行う必要があります：

1. 使用するローカルの Chrome プロファイルを尋ねます
2. 同期するドメインを尋ねます。プロファイル全体の同期をデフォルトにしてはいけません
3. 実行前に確認します

ローカルプロファイルにある Cookie を確認する：

browser-use -b real profile cookies "Default"
# → youtube.com: 23
# → google.com: 18
# → github.com: 2

ドメインを指定して同期する（推奨）：

browser-use profile sync --from "Default" --domain github.com
# Creates new cloud profile: "Chrome - Default (github.com)"
# Only syncs github.com cookies

プロファイル全体を同期する（注意して使用）：

browser-use profile sync --from "Default"
# Syncs ALL cookies — includes sensitive data, tracking cookies, every session token

ユーザーがブラウザーの状態全体を明示的に必要としている場合にのみ使用してください。

詳細な制御（上級者向け）：

# Export cookies to file, manually edit, then import
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <id> cookies import /tmp/cookies.json

同期したプロファイルを使用する：

browser-use --browser remote --profile <id> open https://github.com

サブエージェントの実行

クラウドセッションを使用して、自律型ブラウザーエージェントを並行して実行します。

基本的なワークフロー： run でタスクを起動 → task status で状態を確認 → 結果を収集 → セッションをクリーンアップします。

• セッション = エージェント：各クラウドセッションは、独自の状態を持つブラウザーエージェントです
• タスク = 作業：エージェントに与えるジョブです。エージェントは複数のタスクを順番に実行できます
• セッションのライフサイクル：停止したセッションを再開することはできません。新しいセッションを開始してください

タスクの起動

# Single task (async by default — returns immediately)
browser-use -b remote run "Search for AI news and summarize top 3 articles"
# → task_id: task-abc, session_id: sess-123

# Parallel tasks — each gets its own session
browser-use -b remote run "Research competitor A pricing"
# → task_id: task-1, session_id: sess-a
browser-use -b remote run "Research competitor B pricing"
# → task_id: task-2, session_id: sess-b
browser-use -b remote run "Research competitor C pricing"
# → task_id: task-3, session_id: sess-c

# Sequential tasks in same session (reuses cookies, login state, etc.)
browser-use -b remote run "Log into example.com" --keep-alive
# → task_id: task-1, session_id: sess-123
browser-use task status task-1  # Wait for completion
browser-use -b remote run "Export settings" --session-id sess-123
# → task_id: task-2, session_id: sess-123 (same session)

管理と停止

browser-use task list --status finished      # See completed tasks
browser-use task stop task-abc               # Stop a task (session may continue if --keep-alive)
browser-use session stop sess-123            # Stop an entire session (terminates its tasks)
browser-use session stop --all               # Stop all sessions

モニタリング

タスクの状態確認は、トークン効率を考慮して設計されています。 デフォルトの出力は最小限です。必要な場合にのみ詳細を表示してください。

モード	フラグ	トークン数	使用する場面
デフォルト	（なし）	少	進捗の確認
コンパクト	-c	中	推論の詳細が必要な場合
詳細	-v	多	アクションのデバッグ

# For long tasks (50+ steps)
browser-use task status <id> -c --last 5   # Last 5 steps only
browser-use task status <id> -v --step 10  # Inspect specific step

ライブ表示：browser-use session get <session-id> は、エージェントを確認するためのライブ URL を返します。

停止したタスクの検出：task status のコストや実行時間が増加しなくなった場合、タスクが停止しています。タスクを停止して、新しいエージェントを開始してください。

ログ：browser-use task logs <task-id> — タスク完了後のみ利用できます。

グローバルオプション

オプション	説明
--session NAME	名前付きセッションを使用します（デフォルト："default"）
--browser MODE	ブラウザーモード：chromium、real、remote
--headed	ブラウザーウィンドウを表示します（chromium モード）
--profile NAME	ブラウザープロファイル（ローカル名またはクラウド ID）。open、session create などで使用できます。run では使用できません（代わりに --session-id を使用してください）
--json	JSON 形式で出力します
--mcp	標準入力／標準出力経由で MCP サーバーとして実行します

セッションの動作：--session を指定しないすべてのコマンドは、同じ "default" セッションを使用します。ブラウザーは開いたままになり、コマンド間で再利用されます。--session NAME を使用すると、複数のブラウザーを並行して実行できます。

ヒント

1. 最初に必ず browser-use state を実行して、利用可能な要素とそのインデックスを確認します
2. デバッグには --headed を使用して、ブラウザーの動作を確認します
3. セッションは維持されます — コマンド間でブラウザーは開いたままになります
4. プログラムで解析する場合は --json を使用します
5. Python の変数は、セッション内の browser-use python コマンド間で保持されます
6. CLI エイリアス：bu、browser、browseruse は、いずれも browser-use と同じように動作します

トラブルシューティング

まず診断を実行します：

browser-use doctor

ブラウザーが起動しない場合

browser-use close --all               # Close all sessions
browser-use --headed open <url>       # Try with visible window

要素が見つからない場合

browser-use state                     # Check current elements
browser-use scroll down               # Element might be below fold
browser-use state                     # Check again

セッションに問題がある場合

browser-use sessions                  # Check active sessions
browser-use close --all               # Clean slate
browser-use open <url>                # Fresh start

task stop 後にセッションを再利用できない場合： タスクを停止して、そのセッションを再利用しようとすると、新しいタスクが "created" 状態のまま停止することがあります。その場合は、新しいセッションを作成してください：

browser-use session create --profile <profile-id> --keep-alive
browser-use -b remote run "new task" --session-id <new-session-id>

タスクが "started" のまま停止する場合：task status でコストを確認します。増加していない場合、タスクが停止しています。session get でライブ URL を確認した後、タスクを停止して新しいエージェントを開始してください。

タスク完了後もセッションは維持されます：タスクが完了しても、セッションは自動的には停止しません。browser-use session stop --all を実行してクリーンアップしてください。

クリーンアップ

完了したら、必ずブラウザーを閉じてください：

browser-use close                     # Close browser session
browser-use session stop --all        # Stop cloud sessions (if any)
browser-use tunnel stop --all         # Stop tunnels (if any)