---
title: "CLI"
description: "Start using the Browser Use CLI"
icon: "terminal"
---
# CLI Usage
The `browser-use` command-line interface provides multiple modes of operation for browser automation.
## Installation
Get started with browser-use immediately using `uvx`:
```bash
uvx 'browser-use[cli]' --help
```
Or install it globally:
```bash
uv tool install 'browser-use[cli]'
```
## Modes of Operation
### 1. Interactive TUI Mode (Default)
Launch an interactive terminal UI where you can chat with the browser automation agent:
```bash
uvx 'browser-use[cli]'
```
This opens a chat interface where you can:
- Type natural language commands to control the browser
- See real-time feedback from the agent
- View browser state and actions being performed
### 2. One-Shot Mode
Execute a single task without entering interactive mode:
```bash
uvx browser-use -p "Search for OpenAI documentation and take a screenshot"
```
Options:
- `-p, --prompt`: The task to execute
- `--headless`: Run browser in headless mode
- `--model`: Specify LLM model (default: gpt-4o)
### 3. MCP Server Mode
Run browser-use as a Model Context Protocol server:
```bash
uvx 'browser-use[cli]' --mcp # expects MCP JSON RPC over stdio
```
This mode exposes browser automation capabilities as MCP tools that can be used by:
- Claude Desktop
- Other MCP-compatible clients
- Custom applications using the MCP SDK
For MCP integration details, see:
- [MCP Server Documentation](/customize/mcp-server)
- [MCP Client Documentation](/customize/mcp-client)
## Configuration
Browser-use can be configured through environment variables and a configuration file.
### Configuration File Location
The default configuration file is located at:
- `~/.config/browseruse/config.json`
You can override this location with:
- `BROWSER_USE_CONFIG_PATH` environment variable
- `BROWSER_USE_CONFIG_DIR` environment variable (directory containing `config.json`)
### Configuration File Format
The configuration uses a database-style format with UUID entries:
```json
{
"browser_profile": {
"550e8400-e29b-41d4-a716-446655440000": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"default": true,
"created_at": "2024-01-01T00:00:00",
"headless": false,
"user_data_dir": null,
"allowed_domains": ["example.com"],
"downloads_path": "~/Downloads/browser-use"
}
},
"llm": {
"6ba7b810-9dad-11d1-80b4-00c04fd430c8": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"default": true,
"created_at": "2024-01-01T00:00:00",
"api_key": "your-openai-api-key-here",
"model": "gpt-4o",
"temperature": 0.7
}
},
"agent": {
"6ba7b812-9dad-11d1-80b4-00c04fd430c8": {
"id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
"default": true,
"created_at": "2024-01-01T00:00:00",
"max_steps": 100,
"use_vision": true
}
}
}
```
Each configuration type (browser_profile, llm, agent) can have multiple entries, with one marked as `default: true`.
### Environment Variables
Environment variables always override config.json values:
#### General Settings
- `BROWSER_USE_LOGGING_LEVEL`: Logging level (debug, info, warning, error)
- `BROWSER_USE_CONFIG_PATH`: Full path to config.json file
- `BROWSER_USE_CONFIG_DIR`: Directory containing config.json
#### Browser Profile Settings
- `BROWSER_USE_HEADLESS`: Run browser in headless mode (true/false)
- `BROWSER_USE_ALLOWED_DOMAINS`: Comma-separated list of allowed domains
- `BROWSER_USE_USER_DATA_DIR`: Chrome user data directory path
#### LLM Settings
- `OPENAI_API_KEY`: OpenAI API key
- `ANTHROPIC_API_KEY`: Anthropic API key
- `BROWSER_USE_LLM_MODEL`: LLM model to use (e.g., gpt-4o, claude-3-opus)
#### MCP-Specific Settings
When running in MCP mode, these environment variables are particularly useful:
- `BROWSER_USE_HEADLESS`: Control browser visibility
- `OPENAI_API_KEY`: Required for agent-based tools
### Browser Profiles Directory
Browser profiles are stored in:
```
~/.config/browseruse/profiles/
├── default/ # Default browser profile
├── work/ # Custom profile example
└── research/ # Another custom profile
```
Each profile directory contains Chrome user data, allowing you to:
- Maintain separate browser sessions
- Keep cookies and local storage isolated
- Use different extensions per profile
## Examples
### Basic Usage
```bash
# Interactive mode
uvx 'browser-use[cli]'
# One-shot task
uvx 'browser-use[cli]' -p "Go to github.com and search for browser-use"
# Headless one-shot
uvx 'browser-use[cli]' --headless -p "Extract prices from example.com/products"
```
### With Configuration
```bash
# Use specific config file
BROWSER_USE_CONFIG_PATH=~/my-config.json uvx 'browser-use[cli]'
# Override settings via environment
BROWSER_USE_HEADLESS=true OPENAI_API_KEY=sk-... uvx 'browser-use[cli]' -p "Check my email"
# Use different LLM model
BROWSER_USE_LLM_MODEL=gpt-4-turbo uvx 'browser-use[cli]'
```
### MCP Server Usage
```bash
# Start MCP server
uvx 'browser-use[cli]' --mcp
# With custom settings
BROWSER_USE_HEADLESS=false OPENAI_API_KEY=sk-... uvx 'browser-use[cli]' --mcp
```
For Claude Desktop integration, add to your Claude Desktop config:
```json
{
"mcpServers": {
"browser-use": {
"command": "uvx",
"args": ["browser-use[cli]", "--mcp"],
"env": {
"OPENAI_API_KEY": "sk-...",
"BROWSER_USE_HEADLESS": "false"
}
}
}
}
```
## Troubleshooting
### Common Issues
1. **Browser not launching**: Ensure Chrome/Chromium is installed
2. **API key errors**: Set appropriate API key environment variables
3. **Permission errors**: Check file permissions in `~/.config/browseruse/`
### Debug Mode
Enable debug logging for troubleshooting:
```bash
BROWSER_USE_LOGGING_LEVEL=debug uvx 'browser-use[cli]'
```
## See Also
- [Getting Started](/quickstart)
- [MCP Server Documentation](/customize/mcp-server)
- [MCP Client Documentation](/customize/mcp-client)
- [Browser Settings](/customize/browser-settings)
