> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browser-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Use Terminal

> Use the terminal app for browser agents, or use the same runtime from Python.

Browser Use Terminal is a Codex-style assistant for the browser.

Coding assistants like Claude Code and Codex work well because they give the model autonomy and a real environment to operate in. They provide tools, files, shell commands, history, resumable sessions, and a terminal UI where you can watch and steer the work.

Browser Use Terminal brings that pattern to browser automation. It gives an AI agent its own browser environment: it can control Chrome, see screenshots, inspect pages, run page JavaScript, save files, use browser profiles, handle secrets, and keep a history of what happened.

Learn more on the [Browser Use Terminal site](https://browser-use.com/terminal?utm_source=docs) or view the [Terminal GitHub repo](https://github.com/browser-use/terminal?utm_source=docs).

In practice, this means you can ask for browser work from your terminal:

```text theme={null}
Find the cancellation policy for my current hotel reservation.
```

```text theme={null}
Give this employee admin permission in Azure.
```

```text theme={null}
Research the top Hacker News stories and summarize the points.
```

<video controls className="w-full aspect-video rounded-xl">
  <source src="https://media.githubusercontent.com/media/browser-use/sdk/rust-terminal-docs/docs/static/terminal_demo.mp4" type="video/mp4" />

  <source src="https://media.githubusercontent.com/media/browser-use/sdk/main/docs/static/terminal_demo.mp4" type="video/mp4" />
</video>

You can use Browser Use Terminal in four ways:

| Surface               | What it is for                                                                                                                                                                                |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TUI**               | The interactive terminal app you launch with `browser`. Best for normal, hands-on use.                                                                                                        |
| **CLI**               | Scriptable commands such as `browser-use-terminal run-openai`. Best for automation and one-off tasks.                                                                                         |
| **Python**            | `browser_use.beta.Agent`, backed by the same Rust runtime. Best when you want browser-use code with terminal runtime behavior.                                                                |
| **Coding assistants** | A skill plus the `browser-use-terminal browser` commands let Claude Code, Codex, OpenCode, and other agents drive the browser. See [Use From Coding Assistants](#use-from-coding-assistants). |

<Info>
  Browser Use Terminal is separate from the lower-level `browser-use` CLI. Use
  `browser` for the Terminal TUI, `browser-use-terminal` for Terminal task
  commands, and `browser-use` for direct browser-control commands.
</Info>

## Terms

* **TUI**: terminal user interface. This is the interactive app you open with `browser`.
* **CLI**: command-line interface. These are scriptable commands such as `browser-use-terminal run-openai`.
* **Headless browser**: a browser that runs without a visible window.
* **CDP**: Chrome DevTools Protocol. This lets Browser Use connect to an existing Chrome instance.
* **MCP**: Model Context Protocol. This lets the agent use tools from external MCP servers.
* **TOTP**: time-based one-time password. This is the six-digit code generated by authenticator apps for 2FA.

## Install

Install Browser Use Terminal:

```bash theme={null}
curl -fsSL https://browser-use.com/terminal/install.sh | sh
```

Restart your shell or source your shell profile if the installer updates your `PATH`.

Verify the two terminal executables:

```bash theme={null}
which browser
which browser-use-terminal
browser-use-terminal --help
```

Open the TUI:

```bash theme={null}
browser
```

Set up Python usage in the same project where you will write your agent code:

```bash theme={null}
uv venv --python 3.12
source .venv/bin/activate
uv pip install browser-use
```

## TUI Commands

In the TUI, type `/` to open the command palette. These are the main commands:

| Command             | What it does                                                      |
| ------------------- | ----------------------------------------------------------------- |
| `/task`             | Start a new task.                                                 |
| `/model`            | Choose the model and provider.                                    |
| `/auth`             | Sign in to a provider.                                            |
| `/browser`          | Change the browser backend.                                       |
| `/profile`          | Choose the default Chrome profile.                                |
| `/history`          | Browse previous tasks.                                            |
| `/context`          | Inspect context window attribution.                               |
| `/secrets`          | Save passwords and 2FA setup keys for website logins.             |
| `/import-passwords` | Import saved logins from 1Password.                               |
| `/domains`          | Allow or block which sites the agent can visit.                   |
| `/sync-cookies`     | Sync local cookies.                                               |
| `/email`            | Give the agent a disposable inbox for sign-ups, links, and codes. |
| `/goal`             | Set or view the goal for a long-running task.                     |
| `/feedback`         | Report a bug or share feedback.                                   |
| `/update`           | Install the latest release.                                       |
| `/reload`           | Restart the UI in this terminal.                                  |
| `/exit`             | Quit Browser Use Terminal.                                        |

## Run Browser Tasks

### TUI

The TUI is the main Browser Use Terminal experience:

```bash theme={null}
browser
```

Type a browser task. You can watch the agent work, interrupt it, steer it, and continue the same session later.

```text theme={null}
Open my company's dashboard and summarize failed jobs from today.
```

```text theme={null}
Log in to the vendor portal and download the latest invoice.
```

### CLI

Use one-shot commands for scripts, automation, and quick tasks:

```bash theme={null}
browser-use-terminal --help
```

```bash theme={null}
browser-use-terminal run-openai --model gpt-5.5 \
  "Go to https://news.ycombinator.com and return the top stories with points"
```

Other provider commands:

```bash theme={null}
browser-use-terminal run-anthropic --model claude-sonnet-4-6 "Research Browser Use"
browser-use-terminal run-openrouter --model openai/gpt-5.5 "Research Browser Use"
browser-use-terminal run-deepseek --model deepseek-v4-pro "Research Browser Use"
```

### Python

Use `browser_use.beta.Agent` to run Python code on top of the Rust terminal runtime:

```bash theme={null}
uv pip install browser-use
```

```python theme={null}
import asyncio

from browser_use.beta import Agent, BrowserProfile, ChatOpenAI


async def main():
    agent = Agent(
        task="Go to https://news.ycombinator.com and return the top stories with points.",
        llm=ChatOpenAI(model="gpt-5.5"),
        browser_profile=BrowserProfile(
            headless=True,
            window_size={"width": 1440, "height": 900},
            allowed_domains=["news.ycombinator.com"],
        ),
    )

    history = await agent.run(max_steps=12)
    print(history.final_result())


asyncio.run(main())
```

## Use From Coding Assistants

Browser Use Terminal plugs into any coding assistant that can run shell commands. A skill teaches the assistant the CLI, and the CLI gives it the full browser runtime: page interaction through Python helpers, screenshots saved as files, profiles, and more.

The fastest setup is to paste this URL into your assistant and let it bootstrap everything (install, skill registration, browser setup, verification):

```text theme={null}
https://browser-use.com/skill
```

To set it up manually instead:

```bash theme={null}
curl -fsSL https://browser-use.com/terminal/install.sh | sh
browser-use-terminal skill install
```

`skill install` writes the skill into every detected assistant home: `~/.claude/skills/` (Claude Code, also read by OpenCode), `~/.codex/skills/` (Codex), `~/.config/opencode/skills/`, and `~/.agents/skills/`. For other assistants, persist the output of `browser-use-terminal skill show` wherever that assistant reads instructions.

The assistant then drives the browser with commands:

```bash theme={null}
browser-use-terminal browser exec <<'PY'
new_tab("https://example.com")
wait_for_load()
print(page_info()["title"])
print(capture_screenshot())
PY
```

How it works:

* The browser auto-connects per the remembered preference (`browser-use-terminal browser preference use local|cloud|managed-headless`) and persists across invocations; Python variables do not.
* Screenshots are saved as files and the absolute path is printed, so assistants view them with their native file tools: Claude Code `Read`, Codex `view_image`, OpenCode `read`, Gemini CLI `read_file`.
* `--session <name>` gives parallel workstreams isolated artifact dirs, event logs, and managed browsers.
* Stop persistent browsers with `browser-use-terminal browser recover stop-owned-browser` (managed) or `browser-use-terminal browser recover stop-owned-remote` (cloud).
* Everything is recorded in the same event log as the TUI: `browser-use-terminal events browser-cli-<session>`.

## Configure Models

### TUI

Use `/auth` to sign in and configure credentials, then `/model` to choose the model:

```text theme={null}
/auth
/model
```

This is the recommended setup path for normal interactive use.

### CLI

For one-shot commands and CI, set the provider key for the provider command you are using:

```bash theme={null}
export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export OPENROUTER_API_KEY=...
export DEEPSEEK_API_KEY=...
export BROWSER_USE_API_KEY=...
```

Then choose a provider command and model:

```bash theme={null}
browser-use-terminal run-openai --model gpt-5.5 "Research Browser Use"
browser-use-terminal run-anthropic --model claude-sonnet-4-6 "Research Browser Use"
browser-use-terminal run-openrouter --model openai/gpt-5.5 "Research Browser Use"
browser-use-terminal run-deepseek --model deepseek-v4-pro "Research Browser Use"
```

### Python

Pass a supported browser-use model class to `Agent`:

```python theme={null}
from browser_use.beta import Agent, ChatAnthropic

agent = Agent(
    task="Find the latest Browser Use docs update",
    llm=ChatAnthropic(model="claude-sonnet-4-6"),
)
```

Supported Python model classes:

| Python model class | Example                                    |
| ------------------ | ------------------------------------------ |
| `ChatOpenAI`       | `ChatOpenAI(model="gpt-5.5")`              |
| `ChatAnthropic`    | `ChatAnthropic(model="claude-sonnet-4-6")` |
| `ChatLiteLLM`      | `ChatLiteLLM(model="openai/gpt-5.5")`      |
| `ChatDeepSeek`     | `ChatDeepSeek(model="deepseek-v4-pro")`    |
| `ChatOpenRouter`   | `ChatOpenRouter(model="openai/gpt-5.5")`   |

## Choose A Browser

### TUI

Use `/browser` to choose how the agent should run the browser:

```text theme={null}
/browser
```

Common choices are your local Chrome, a headless browser, or Browser Use Cloud.

Browser Use Cloud is the easiest option to get started: it gives you a free, one-click browser setup without managing a local Chrome profile.

Use `/profile` to choose the default Chrome profile:

```text theme={null}
/profile
```

### CLI

Use terminal config or one-off config overrides for browser settings:

```bash theme={null}
browser-use-terminal \
  --config 'browser.headless=true' \
  --config 'browser.window_size={width=1440,height=900}' \
  run-openai "Open Hacker News"
```

### Python

Managed local browser:

```python theme={null}
from browser_use.beta import Agent, BrowserProfile, ChatOpenAI

agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(
        headless=True,
        user_data_dir="./browser-profile",
        window_size={"width": 1280, "height": 900},
    ),
)
```

Headed browser:

```python theme={null}
agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(headless=False),
)
```

Browser Use Cloud:

Browser Use Cloud is the simplest remote browser option for Python too. Set `BROWSER_USE_API_KEY`, pass `use_cloud=True`, and the terminal runtime handles the cloud browser session.

```python theme={null}
from browser_use.beta import Agent, BrowserSession, ChatOpenAI

agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_session=BrowserSession(
        use_cloud=True,
        cloud_profile_id="profile-id",
        cloud_proxy_country_code="US",
        keep_alive=False,
    ),
)
```

Existing browser over CDP:

```python theme={null}
from browser_use.beta import Agent, BrowserProfile, ChatOpenAI

agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(
        cdp_url="http://127.0.0.1:9333",
        user_agent="BrowserUseRemoteCDP/1.0",
    ),
)
```

## Use Secrets And Login

Secrets let the agent fill credentials without exposing raw values to the model.

### TUI

Use `/auth` for Browser Use account and model-provider authentication:

```text theme={null}
/auth
```

Use `/secrets` to save website login secrets and 2FA setup keys:

```text theme={null}
/secrets
```

Inside `/secrets`, press `Ctrl-O` to import logins from 1Password. You can also run:

```text theme={null}
/import-passwords
```

Name a TOTP secret `otp` and paste the authenticator setup key, not the current six-digit code.

### CLI

Store a password:

```bash theme={null}
printf '%s' "$PASSWORD" | browser-use-terminal secrets set \
  --domain example.com \
  --name password \
  --stdin
```

Store a TOTP seed for 2FA:

```bash theme={null}
printf '%s' "$TOTP_SEED" | browser-use-terminal secrets set \
  --domain example.com \
  --name otp \
  --totp \
  --stdin
```

Import saved logins from 1Password:

```bash theme={null}
browser-use-terminal secrets import
browser-use-terminal secrets list
```

The import command uses the `op` CLI. `secrets list` prints metadata only, never secret values.

### Python

Python runs use the same terminal runtime and terminal state. Configure website secrets with the terminal commands above, then run the Python agent against the matching domain.

```python theme={null}
from browser_use.beta import Agent, BrowserProfile, ChatOpenAI

agent = Agent(
    task="Log in to example.com and summarize my dashboard.",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(allowed_domains=["example.com"]),
)
```

## Restrict Domains

Domain policy controls where the browser can navigate.

### TUI

Use `/domains` to allow or block sites from the TUI:

```text theme={null}
/domains
```

### CLI

```bash theme={null}
browser-use-terminal domains allow news.ycombinator.com
browser-use-terminal domains deny '*.tracking.example'
browser-use-terminal domains list
browser-use-terminal domains clear
```

### Python

Pass domain policy through `BrowserProfile`:

```python theme={null}
from browser_use.beta import BrowserProfile

profile = BrowserProfile(
    allowed_domains=["news.ycombinator.com"],
    prohibited_domains=["*.tracking.example"],
)
```

## Use MCP Servers

MCP servers add external tools to the agent.

### TUI

Add MCP servers to terminal config, then run the TUI normally:

```bash theme={null}
browser
```

### CLI

Create an MCP config:

```toml theme={null}
[mcp_servers.local]
transport = "stdio"
command = "python"
args = ["./server.py"]
```

Pass it when you run a task:

```bash theme={null}
browser-use-terminal --mcp-config ./mcp.toml run-openai \
  "Use the browser and MCP tools to complete this task"
```

### Python

Python terminal-backed runs can use terminal MCP configuration through the same terminal runtime. Configure MCP servers in terminal config before starting the Python run.

## Use Profiles And Config

Profiles let you keep separate terminal settings for different accounts, browsers, models, or workflows.

### TUI

Use `/profile` to choose the default Chrome profile:

```text theme={null}
/profile
```

Open the terminal with a named terminal config profile:

```bash theme={null}
browser --profile work
```

### CLI

The terminal reads config from:

```text theme={null}
$BROWSER_USE_TERMINAL_HOME/config.toml
```

If `BROWSER_USE_TERMINAL_HOME` is not set, it uses:

```text theme={null}
~/.browser-use-terminal
```

Use a named profile to layer `$BROWSER_USE_TERMINAL_HOME/<name>.config.toml` on top of the base config:

```bash theme={null}
browser-use-terminal --profile work run-openai "Research this pricing page"
```

Use `--state-dir` for an isolated run:

```bash theme={null}
browser-use-terminal --state-dir /tmp/browser-use-terminal run-openai \
  "Open Hacker News and summarize the front page"
```

### Python

Point Python at a terminal state directory:

```bash theme={null}
export BROWSER_USE_TERMINAL_HOME=/path/to/state
```

Use a specific terminal binary:

```bash theme={null}
export BROWSER_USE_TERMINAL_BINARY=/path/to/browser-use-terminal
```

## Troubleshooting Setup

### `browser` Or `browser-use-terminal` Not Found

Restart your terminal, then check whether the install location is on your `PATH`:

```bash theme={null}
which browser
which browser-use-terminal
echo "$PATH"
```

If the commands are still missing, rerun the installer and copy any `PATH` instructions it prints:

```bash theme={null}
curl -fsSL https://browser-use.com/terminal/install.sh | sh
```

### Which Command Should I Use?

| Goal                                      | Command                                 |
| ----------------------------------------- | --------------------------------------- |
| Open the interactive Terminal app         | `browser`                               |
| Run a one-shot Terminal agent task        | `browser-use-terminal run-openai "..."` |
| Use Terminal runtime from Python          | `browser_use.beta.Agent`                |
| Drive the browser from a coding assistant | `browser-use-terminal browser exec`     |
| Register the skill with coding assistants | `browser-use-terminal skill install`    |
| Directly control a browser with Python    | `browser-use <<'PY' ... PY`             |

### Python Cannot Find `browser_use.beta`

Install or upgrade the Python package in the same environment you are running:

```bash theme={null}
uv pip install --upgrade browser-use
python -c "from browser_use.beta import Agent; print('ok')"
```

## Forwarded Python Settings

When you use `browser_use.beta.Agent`, these Python settings are forwarded to the Rust terminal SDK:

| Python setting                                   | Terminal SDK field           |
| ------------------------------------------------ | ---------------------------- |
| `llm.provider`, inferred from the chat model     | `llm.provider`               |
| `llm.model`                                      | `llm.model`                  |
| `llm_timeout`                                    | `llm.timeout`                |
| `headless`                                       | `browser.headless`           |
| `keep_alive`                                     | `browser.keep_alive`         |
| `cloud_profile_id`, `profile_id`                 | `browser.profile_id`         |
| `cloud_proxy_country_code`, `proxy_country_code` | `browser.proxy_country_code` |
| `cdp_url`                                        | `browser.cdp_url`            |
| `headers` / CDP headers                          | `browser.cdp_headers`        |
| `user_agent`                                     | `browser.user_agent`         |
| `viewport`                                       | `browser.viewport`           |
| `window_size`                                    | `browser.window_size`        |
| `storage_state`                                  | `browser.storage_state`      |
| `downloads_path`                                 | `browser.downloads_path`     |
| `allowed_domains`                                | `browser.allowed_domains`    |
| `prohibited_domains`                             | `browser.blocked_domains`    |
| `state_dir`                                      | `browser.state_dir`          |
| `no_viewport`                                    | `browser.no_viewport`        |
| `accept_downloads`                               | `browser.accept_downloads`   |
| `output_model_schema`                            | `output_schema`              |
| `calculate_cost`                                 | `calculate_cost`             |
| `max_actions_per_step`                           | `max_actions_per_step`       |

The same Python `Agent` instance can continue a terminal-backed session across follow-up runs.

### Cloud Browser Setup

Set `BROWSER_USE_API_KEY` and pass the cloud profile or proxy settings through `BrowserSession`.

### 1Password Import Setup

Install and sign in to the 1Password CLI:

```bash theme={null}
op account list
```

Then import:

```bash theme={null}
browser-use-terminal secrets import
```

### TOTP Setup

Store the base32 TOTP seed with `--totp`, not the current six-digit code:

```bash theme={null}
printf '%s' "$BASE32_TOTP_SEED" | browser-use-terminal secrets set \
  --domain example.com \
  --name otp \
  --totp \
  --stdin
```