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

# Browse CLI

> Use the Browse CLI to drive browser automation, Browserbase cloud APIs, and Browse.sh skills from AI coding agents.

The Browse CLI gives your agent a real browser and the full Browserbase platform from the terminal. Your agent can open pages, read accessibility snapshots, click and fill elements, capture network traffic, and manage sessions, contexts, Secrets, Functions, and skills without leaving the shell.

Commands return JSON, so your agent can chain steps like `browse open`, `browse snapshot`, and `browse click @0-4` without writing a script.

<Tip>
  Have your agent run `browse skills show` before its first command. It prints the bundled skill, which matches your installed CLI version and covers workflows, session management, and failure recovery.
</Tip>

## Choose the right skill

| Skill | Best for |
| - | - |
| `browser` | Interactive browser automation powered by the `browse` CLI |
| `fetch` | Lightweight page retrieval via the Browserbase Fetch API |
| `functions` | Focused Browserbase Functions workflows |
| `browse` | Bundled skill for unified `browse` workflows across browser automation, cloud APIs, functions, skills, and templates |

## Installation

<Tabs>
  <Tab title="Browse CLI">
    <Steps>
      <Step title="Install the Browse CLI">
        ```bash theme={null}
        npm install -g browse
        ```
      </Step>

      <Step title="Install the bundled skill">
        ```bash theme={null}
        browse skills install
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Vercel Skills CLI">
    <Steps>
      <Step title="Install the skill">
        ```bash theme={null}
        npx skills add browserbase/skills --skill browser
        ```
      </Step>

      <Step title="Install the Browse CLI">
        ```bash theme={null}
        npm install -g browse
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code plugins">
    <Steps>
      <Step title="Add the Browserbase marketplace">
        ```bash theme={null}
        claude plugin marketplace add browserbase/skills
        ```
      </Step>

      <Step title="Install the browse plugin">
        ```bash theme={null}
        claude plugin install browse@browserbase --scope local
        ```
      </Step>

      <Step title="Install the Browse CLI">
        ```bash theme={null}
        npm install -g browse
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Command reference

This is every command in the Browse CLI. Run `browse <command> --help` for arguments and flags.

Element commands accept a snapshot ref such as `@0-4`, an XPath, or a CSS selector. Run `browse snapshot` first to cache refs.

### Navigation

| Command | What it does |
| - | - |
| `browse open <url>` | Open a URL. Starts the browse daemon if it isn't running. |
| `browse back` | Navigate the active page backward. |
| `browse forward` | Navigate the active page forward. |
| `browse reload` | Reload the active page. |
| `browse wait <load\|selector\|timeout> [arg]` | Wait for a load state, a selector state, or a number of milliseconds. |

### Page inspection

| Command | What it does |
| - | - |
| `browse snapshot` | Print the accessibility snapshot and cache refs. Pass `--full` to include the XPath and URL ref maps. |
| `browse screenshot` | Capture a screenshot of the active page. |
| `browse get <what> [selector]` | Read `url`, `title`, `text`, `html`, `value`, `box`, `visible`, `checked`, or `markdown`. |
| `browse is <visible\|checked> <selector>` | Check an element's state. |
| `browse highlight <selector>` | Highlight an element on the page. |
| `browse eval <expression>` | Evaluate JavaScript in the active page. |

### Element interaction

| Command | What it does |
| - | - |
| `browse click <selector>` | Click an element. |
| `browse fill <selector> <value>` | Fill an input-like element. |
| `browse type <text>` | Type text at the current focus. |
| `browse select <selector> <value>` | Select an option on a select-like element. |
| `browse upload <selector> <files...>` | Upload one or more files into a file input. |
| `browse press <key>` | Press a key or chord, such as `Enter`, `Escape`, or `Meta+K`. |
| `browse key <key>` | Same as `browse press`. |

### Mouse

Use these when an element has no usable ref or selector.

| Command | What it does |
| - | - |
| `browse mouse click <x> <y>` | Click raw viewport coordinates. |
| `browse mouse hover <x> <y>` | Move the mouse to raw viewport coordinates. |
| `browse mouse drag <from-x> <from-y> <to-x> <to-y>` | Drag from one coordinate to another. |
| `browse mouse scroll <x> <y> <delta-x> <delta-y>` | Scroll by a delta from raw viewport coordinates. |

### Tabs

| Command | What it does |
| - | - |
| `browse tab list` | List tabs with their stable `targetId` values. |
| `browse tab new` | Open a new tab and make it active. |
| `browse tab switch <index\|targetId>` | Switch the active tab. Prefer `targetId` for stable workflows. |
| `browse tab close [index\|targetId]` | Close a tab. Closes the active tab when you omit the argument. |

### Network capture

| Command | What it does |
| - | - |
| `browse network on` | Start capturing network traffic for the active session. |
| `browse network off` | Stop capturing network traffic. |
| `browse network path` | Print the capture directory. |
| `browse network clear` | Delete captured request directories. |

### Session and debugging

| Command | What it does |
| - | - |
| `browse status` | Show the daemon status for a named session. |
| `browse stop` | Stop the daemon for a named session. Pass `--force` to clean up a crashed daemon. |
| `browse doctor` | Diagnose session and browser connection prerequisites. |
| `browse viewport <width> <height>` | Set the viewport size of the active page. |
| `browse cursor` | Show a visible cursor overlay in the active page. |
| `browse cdp <target>` | Attach to a CDP endpoint and stream DevTools Protocol events. |

### Browser target flags

Browser commands share these flags:

| Flag | What it does |
| - | - |
| `--remote` | Use a remote Browserbase browser session. |
| `--local` | Use a managed local browser session. |
| `--verified` | Open the remote session as a [Verified](/platform/identity/agent-identity) browser. Requires `--remote` and a Scale plan. |
| `--proxies` | Route the remote session through Browserbase proxies. Requires `--remote`. |
| `--headed` / `--headless` | Show or hide the window for managed local sessions. |
| `--cdp <url\|port>` | Attach to an existing CDP endpoint. |
| `--auto-connect` | Find and attach to a local browser with remote debugging enabled. |
| `--target-id <id>` | Select a specific CDP target when attaching to an existing browser. |
| `-s, --session <name>` | Use a named session. Defaults to `BROWSE_SESSION` or `default`. |
| `--chrome-arg <flag>` | Add a Chrome launch arg for managed local sessions. Repeatable. |
| `--ignore-default-chrome-arg <flag>` | Drop one of Chrome's default launch args. Repeatable. |
| `--no-default-chrome-args` | Launch managed local Chrome without its default args. |

### Cloud APIs

| Command | What it does |
| - | - |
| `browse cloud projects list` | List projects visible to your API key. |
| `browse cloud projects get <id>` | Get a project. |
| `browse cloud projects usage` | Get project usage. |
| `browse cloud sessions create` | Create a browser session. Use flags for common options, or `--body` or `--stdin` for the full API. |
| `browse cloud sessions list` | List sessions. |
| `browse cloud sessions get <id>` | Get a session. |
| `browse cloud sessions update <id>` | Update a session. |
| `browse cloud sessions debug <id>` | Get live debugger URLs for a session. |
| `browse cloud sessions logs <id>` | Get session logs. |
| `browse cloud sessions uploads create <id> <file>` | Upload a file to a session. |
| `browse cloud sessions downloads get <id>` | Download session files as a ZIP archive. |
| `browse cloud contexts create` | Create a context. Pass `--name` to save a local alias. |
| `browse cloud contexts add <name> <id>` | Save a local name for an existing context ID. |
| `browse cloud contexts get <id\|name>` | Get a context. |
| `browse cloud contexts list` | List contexts you saved locally by name. |
| `browse cloud contexts update <id\|name>` | Refresh a context's upload URL. |
| `browse cloud contexts delete <id\|name>` | Delete a context. |
| `browse cloud extensions upload <file>` | Upload a Chrome extension ZIP file. |
| `browse cloud extensions get <id>` | Get an extension. |
| `browse cloud extensions delete <id>` | Delete an extension. |
| `browse cloud secrets create <name>` | Create a Secret. The CLI encrypts the value locally. |
| `browse cloud secrets list` | List Secret metadata. |
| `browse cloud secrets get <id>` | Get Secret metadata. Never returns the value. |
| `browse cloud secrets update <id>` | Replace a Secret value. The CLI encrypts it locally. |
| `browse cloud secrets delete <id>` | Delete a Secret. |
| `browse cloud fetch <url>` | Retrieve page content with the Fetch API. |
| `browse cloud search <query>` | Search the web with the Search API. |

### Functions

| Command | What it does |
| - | - |
| `browse functions init [name]` | Create a Functions project. |
| `browse functions dev <entrypoint>` | Run the local development server. |
| `browse functions publish <entrypoint>` | Package and upload a Function build. |
| `browse functions invoke [function-id]` | Invoke a deployed Function or check invocation status. |
| `browse functions secrets attach <function-id> <secret-id>` | Attach a Secret to a Function. |
| `browse functions secrets detach <function-id> <secret-id>` | Detach a Secret without deleting it. |
| `browse functions secrets list <function-id>` | List Secrets attached to a Function. |

### Skills and templates

| Command | What it does |
| - | - |
| `browse skills show` | Print the bundled skill. Run it before using `browse` in an agent. |
| `browse skills install` | Install the bundled skill into your agent. |
| `browse skills list` | List Browse.sh catalog skills. |
| `browse skills find <query>` | Find catalog skills by slug, domain, title, category, or tag. |
| `browse skills add [skill]` | Install a catalog skill. |
| `browse templates list` | List Browserbase templates. |
| `browse templates find <query>` | Find templates by slug, title, category, or tag. |
| `browse templates clone <slug> [path]` | Scaffold a ready-to-run project from a template. |

## Authentication

Remote Browserbase commands require your API key:

```bash theme={null}
export BROWSERBASE_API_KEY="your_api_key"
```

The CLI reads `BROWSERBASE_API_KEY` from the environment on every command, including when a browse daemon is already running. You can export the key at any point or provide it to a single command without restarting the daemon:

```bash theme={null}
BROWSERBASE_API_KEY="your_api_key" browse open https://example.com --remote
```

## Daemon lifecycle

Browser commands start the browse daemon automatically. To start a session when no daemon is running, use the exact command below and add `--local` or `--remote` if you want to choose the browser target explicitly:

```bash theme={null}
browse open <url>
```

If a previous daemon stopped unexpectedly, clean up its state and start a fresh session:

```bash theme={null}
browse stop --force
browse open <url>
```

`browse stop` is idempotent. When no daemon is running, it returns `"stopped": false` and exits successfully with code `0`.

## Common workflows

### Browser automation

```bash theme={null}
browse open https://example.com
browse snapshot
browse click @0-4
browse fill @0-7 "hello@example.com"
browse screenshot
```

### Cloud APIs

```bash theme={null}
browse cloud projects list
browse cloud sessions get <session_id>
browse cloud contexts create
browse cloud extensions upload ./my-extension.zip
browse cloud fetch https://example.com
browse cloud search "browser automation tools" --num-results 5
```

### Functions

```bash theme={null}
browse functions init my-function
cd my-function
browse functions dev index.ts
browse functions publish index.ts
browse functions invoke <function_id> --params '{"url":"https://example.com"}'
```

### Secrets

Create an encrypted Secret, then list its metadata:

```bash theme={null}
browse cloud secrets create SERVICE_TOKEN
browse cloud secrets list
```

The CLI encrypts the value on your machine before it sends the value to Browserbase. See the [Secrets overview](/platform/secrets/overview) for the access model and the [getting started guide](/platform/secrets/getting-started) for the complete workflow.

### Skills

```bash theme={null}
browse skills show
browse skills install
browse skills list
browse skills find reviews
browse skills add yelp.com/extract-reviews
```

## Browse.sh

Browse.sh is an open-source catalog of skills for reliable web tasks.

It gives your agents researched playbooks for hundreds of sites.

## Further reading

<CardGroup cols={2}>
  <Card title="Skills repository" icon="github" iconType="sharp-solid" href="https://github.com/browserbase/skills">
    View the Browserbase skills source and installation instructions.
  </Card>

  <Card title="Browse.sh" icon="arrow-up-right-from-square" iconType="sharp-solid" href="https://browse.sh">
    Explore the public Browse.sh skill catalog.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.