smooth-browser

# Smooth Browser

Smooth CLI is a browser for AI agents to interact with websites, authenticate, scrape data, and perform complex web-based tasks using natural language.

## Prerequisites

Assume the Smooth CLI is already installed. If not, you can install it by running:

```bash
pip install smooth-py
```

Assume an API key is already configured. If you encounter authentication errors, configure it with:

```bash
smooth config --api-key <api-key>
```

To verify the configuration:
```bash
smooth config --show
```

Get an API key at https://app.smooth.sh

If the account is out of credits, ask the user to upgrade their plan at https://app.smooth.sh

## Basic Workflow

### 1. Create a Profile (Optional)

Profiles are useful to persist cookies, login sessions, and browser state between sessions.

```bash
smooth create-profile --profile-id "my-profile"
```

List existing profiles:
```bash
smooth list-profiles
```

### 2. Start a Browser Session

```bash
smooth start-session --profile-id "my-profile" --url "https://example.com"
```

**Options:**
- `--profile-id` - Use a specific profile (optional, creates anonymous session if not provided)
- `--url` - Initial URL to navigate to (optional)
- `--files` - Comma-separated file IDs to make available in the session (optional)
- `--device mobile|desktop` - Device type (default: mobile)
- `--profile-read-only` - Load profile without saving changes
- `--allowed-urls` - Comma-separated URL patterns to restrict access to certain URLs only (e.g., "https://*example.com/*,https://*api.example.com/*")
- `--no-proxy` - Disable the default proxy (see note below)

**Important:** Save the session ID from the output - you'll need it for all subsequent commands.

**Proxy behavior:** By default, the CLI automatically configures a built-in proxy for the browser session. If a website blocks the proxy or you need direct connections, disable it with `--no-proxy`.

### 3. Run Tasks in the Session

Execute tasks using natural language:

```bash
smooth run -- <session-id> "Go to the LocalLLM subreddit and find the top 3 posts"
```

**With structured output (for tasks requiring interaction):**
```bash
smooth run -- <session-id> "Search for 'wireless headphones', filter by 4+ stars, sort by price, and extract the top 3 results" \
  --url "https://shop.example.com" \
  --response-model '{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","description":"Thenameoftheproductbeingdescribed."},"sentiment":{"type":"string","enum":["positive","negative","neutral"],"description":"The overall sentiment about the product."}},"required":["product","sentiment"]}}'
```

**With metadata (the agent will be):**
```bash
smooth run -- <session-id> "Fill out the form with user information" \
  --metadata '{"email":"user@example.com","name":"John Doe"}'
```

**Options:**
- `--url` - Navigate to this URL before running the task
- `--metadata` - JSON object with variables for the task
- `--response-model` - JSON schema for structured output
- `--max-steps` - Maximum agent steps (default: 32)
- `--json` - Output results as JSON

**Notes:**
It's important that you give tasks at the right level of abstraction. Not too prescriptive - e.g. single-step actions - and not too broad or vague.

Good tasks:
- "Search on Linkedin for people working as SDEs at Amazon, and return 5 profile urls"
- "Find the price of an iPhone 17 on Amazon"

Bad tasks:
- "Click search" -> too prescriptive!
- "Load google.com, write 'restaurants near me', click search, wait for the page to load, extract the top 5 results, and return them." -> too prescriptive! you can say "search restaurants near me on google and return the top 5 results"
- "Find software engineers that would be a good fit for our company" -> too broad! YOU need to plan how to achieve the goal and run well-defined tasks that compose into the given goal

IMPORTANT: Smooth is powered by an intelligent agent, DO NOT over-controll it, and give it well-defined goal-oriented tasks instead of steps.

### 4. Close the Session

You must close the session when you're done.

```bash
smooth close-session -- <session-id>
```

**Important:** Wait 5 seconds after closing to ensure cookies and state are saved to the profile if you need it for another session.

---

## Common Use Cases

### Authentication & Persistent Sessions

**Create a profile for a specific website:**
```bash
# Create profile
smooth create-profile --profile-id "github-account"

# Start session
smooth start-session --profile-id "github-account" --url "https://github.com/login"

# Get live view to authenticate manually
smooth live-view -- <session-id>
# Give the URL to the user so it can open it in the browser and log in

# When the user confirms the login you can then close the session to save the profile data
smooth close-session -- <session-id>
# Save the profile-id somewhere to later reuse it
```

**Reuse authenticated profile:**
```bash
# Next time, just start a session with the same profile
smooth start-session --profile-id "github-account"
smooth run -- <session-id> "Create a new issue in my repo 'my-project'"
```

**Keep profiles organized:** Save to memory which profiles authenticate to which services so you can reuse them efficiently in the future.

---

### Sequential Tasks on Same Browser

Execute multiple tasks in sequence without closing the session:

```bash
SESSION_ID=$(smooth start-session --profile-id "my-profile" --json | jq -r .session_id)

# Task 1: Login
smooth run $SESSION_ID "Log into the website with the given credentials"

# Task 2: First action
smooth run $SESSION_ID "Find the settings and change the notifications preferences to email only"

# Task 3: Second action
smooth run $SESSION_ID "Find the billing section and give me the url of the latest invoice"

smooth close-session $SESSION_ID
```

**Important:** `run` preserves the browser state (cookies, URL, page content) but **not** the browser agent's memory. If you need to carry information from one task to the next, you should pass it explicitly in the prompt.

**Example - Passing context between tasks:**
```bash
# Task 1: Get information
RESULT=$(smooth run $SESSION_ID "Find the product name on this page" --json | jq -r .output)

# Task 2: Use information from Task 1
smooth run $SESSION_ID "Consider the product with name '$RESULT'. Now find 3 similar products offered by this online store."
```

**Notes:** 
- The run command is blocking. If you need to carry out multiple tasks at the same time, you MUST use subagents (Task tool).
- All tasks will use the current tab, you cannot request to run tasks in a new tab. If you need to preserve the current tab’s state, you can open a new session.
- Each session can run only one task at a time. To run tasks simultaneously, use subagents with one session each.
- The maximum number of concurrent sessions depends on the user plan.
- If useful, remind the user that they can upgrade the plan to give you more concurrent sessions.

---

### Web Scraping with Structured Output

**Option 1: Using `run` with structured output:**

```bash
smooth start-session --url "https://news.ycombinator.com"
smooth run -- <session-id> "Extract the top 10 posts" \
  --response-model '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }'
```

**Option 2: Using `extract` for direct data extraction:**

The `extract` command is more efficient for pure data extraction as it doesn't use agent steps. 

It's like a smart fetch that can extract structured data from dynamically rendered websites:

```bash
smooth start-session
smooth extract -- <session-id> \
  --url "https://news.ycombinator.com" \
  --schema '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }' \
  --prompt "Extract the top 10 posts"
```

**When to use each:**
- Use `extract` when you're on the right page or know the right url and just need to pull structured data
- Use `run` when you need the agent to navigate, interact, or perform complex actions before extracting

---

### Working with Files

**Upload files for use in sessions:**

Files must be uploaded before starting a session, then passed to the session via file IDs:

```bash
# Step 1: Upload files
FILE_ID=$(smooth upload-file /path/to/document.pdf --purpose "Contract to analyze" --json | jq -r .file_id)

# Step 2: Start session with the file
smooth start-session --files "$FILE_ID" --url "https://example.com"

# Step 3: The agent can now access the file in tasks
smooth run -- <session-id> "Analyze the contract document and extract key terms"
```

**Upload multiple files:**
```bash
# Upload files
FILE_ID_1=$(smooth upload-file /path/to/invoice.pdf --json | jq -r .file_id)
FILE_ID_2=$(smooth upload-file /path/to/screenshot.png --json | jq -r .file_id)

# Start session with multiple files
smooth start-session --files "$FILE_ID_1,$FILE_ID_2"
```

**Download files from session:**
```bash
smooth run -- <session-id> "Download the monthly report PDF" --url
smooth close-session -- <session-id>

# After session closes, get download URL
smooth downloads -- <session-id>
# Visit the URL to download files
```

---

### Live View & Manual Intervention

When automation needs human input (CAPTCHA, 2FA, complex authentication):

```bash
smooth start-session --profile-id "my-profile"
smooth run -- <session-id> "Go to secure-site.com and log in"

# If task encounters CAPTCHA or requires manual action:
smooth live-view -- <session-id>
# Open the URL and complete the manual steps

# Continue automation after manual intervention:
smooth run -- <session-id> "Now navigate to the dashboard and export data"
```

---

### Direct Browser Actions

**Extract data from current page:**

```bash
smooth start-session --url "https://example.com/products"
smooth extract -- <session-id> \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}' \
  --prompt "Extract all product names and prices"
```

**Navigate to URL then extract:**

```bash
smooth extract -- <session-id> \
  --url "https://example.com/products" \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}'
```

**Execute JavaScript in the browser:**

```bash
# Simple JavaScript
smooth evaluate-js -- <session-id> "document.title"

# With arguments
smooth evaluate-js -- <session-id> "(args) => {return args.x + args.y;}" --args '{"x": 5, "y": 10}'

# Complex DOM manipulation
smooth evaluate-js -- <session-id> \
  "document.querySelectorAll('a').length"
```

---

## Profile Management

**List all profiles:**
```bash
smooth list-profiles
```

**Delete a profile:**
```bash
smooth delete-profile <profile-id>
```

**When to use profiles:**
- ✅ Websites requiring authentication
- ✅ Maintaining session state across multiple task runs
- ✅ Avoiding repeated logins
- ✅ Preserving cookies and local storage

**When to skip profiles:**
- Public websites that don't require authentication
- One-off scraping tasks
- Testing scenarios

---

## File Management

**Upload files:**
```bash
smooth upload-file /path/to/file.pdf --name "document.pdf" --purpose "Contract for review"
```

**Delete files:**
```bash
smooth delete-file <file-id>
```

---

## Best Practices

1. **Always save session IDs** - You'll need them for subsequent commands
2. **Use profiles for authenticated sessions** - Track which profile is for which website
3. **Wait 5 seconds after closing sessions** - Ensures state is properly saved
4. **Use descriptive profile IDs** - e.g., "linkedin-personal", "twitter-company"
5. **Close sessions when done** - Graceful close (default) ensures proper cleanup
6. **Use structured output for data extraction** - Provides clean, typed results
7. **Run sequential tasks in the same session** - Keep the session continuous when steps rely on previous work.
8. **Use subagents with one session each for independent tasks** - Run tasks in parallel to speed up work.
9. **Coordinate resources** - When working with subagents, you must create and assign ONE section to each subagent without having them creating them.
10. **Do not add url query parameters to urls, e.g. avoid `?filter=xyz`** - Start at the base URL and let the agent navigate the UI to apply filters.
11. **Smooth is powered by an intelligent agent** - Give it tasks, not individual steps.

---

## Troubleshooting

**"Session not found"** - The session may have timed out or been closed. Start a new one.

**"Profile not found"** - Check `smooth list-profiles` to see available profiles.

**CAPTCHA or authentication issues** - Use `smooth live-view -- <session-id>` to let the user manually intervene.

**Task timeout** - Increase `--max-steps` or break the task into smaller steps.

---

## Command Reference

### Profile Commands
- `smooth create-profile [--profile-id ID]` - Create a new profile
- `smooth list-profiles` - List all profiles
- `smooth delete-profile <profile-id>` - Delete a profile

### File Commands
- `smooth upload-file <path> [--name NAME] [--purpose PURPOSE]` - Upload a file
- `smooth delete-file <file-id>` - Delete an uploaded file

### Session Commands
- `smooth start-session [OPTIONS]` - Start a browser session
- `smooth close-session -- <session-id> [--force]` - Close a session
- `smooth run -- <session-id> "<task>" [OPTIONS]` - Run a task
- `smooth extract -- <session-id> --schema SCHEMA [OPTIONS]` - Extract structured data
- `smooth evaluate-js -- <session-id> "code" [--args JSON]` - Execute JavaScript
- `smooth live-view -- <session-id>` - Get interactive live URL
- `smooth recording-url -- <session-id>` - Get recording URL
- `smooth downloads -- <session-id>` - Get downloads URL

All commands support `--json` flag for JSON output.