Browserbase CLI Configuration Guide

BrowserbaseCLIClaudeSkills pluginConfiguration

I spent 4 hours configuring Browserbase CLI and skills plugin for Claude Code — and hit 5 real problems. Here's the complete breakdown of each pitfall and how to solve it.

Problem 1: "Authentication failed" Due to API Key Format Error

First step after installation is setting up your API key:

npm install -g @browserbasehq/browse-cli
browse auth --key YOUR_API_KEY

The first error I hit:

Error: Authentication failed. Please check your API key.

**Root cause**: Browserbase API keys come from the "Developer" tab at https://browserbase.com/settings — not from project settings. Also, the key format is sk-... but some people's environment variables incorrectly add quotes around it.

Fix:

# Correct: assign directly without quotes
export BROWSERBASE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# Verify authentication
browse auth status

Problem 2: local vs remote Mode Confusion

Browserbase CLI has two runtime modes, and many first-time users don't know which to pick:

**local mode**: `browse env local` — uses your local Chrome, no extra cost
**remote mode**: `browse env remote` — uses Browserbase cloud browsers, billed per time

Pitfall: I assumed remote mode was "more professional" and used it for all testing, which caused:

1. Every test cost money

2. CAPTCHA solving not included in Start plan (need Developer at $99/month)

3. Higher latency than local (~200ms vs instant local)

When to use which:

**Development/debugging** → local mode
**Production/scraping protected sites** → remote mode

# Use local for development
browse env local
browse open https://example.com

# Switch to remote for production
browse env remote
browse open --context-id my-session https://example.com

Problem 3: context ID Persistence Failure

One of Browserbase's core features is session persistence — save your login state and reuse it later.

# Save context (includes cookies, localStorage, etc.)
browse open --context-id my-session --persist https://mail.google.com

# Load this session later
browse open --context-id my-session

Pitfall: I followed the docs exactly, but the session was lost on second load.

**Root cause**: Context IDs on the Start (free) plan only persist for 7 days. After that, they're automatically purged. Also, the --persist flag only works in remote mode — local mode doesn't support it.

How to verify:

# List current contexts
bb contexts list

# Check remaining TTL for a context
bb contexts get

Problem 4: CAPTCHA Billing Traps

Browserbase's CAPTCHA solving is billed per attempt, but many people get hit on the free plan:

**Start plan (free)**: Does NOT include CAPTCHA solving
**Developer plan ($99/month)**: Includes CAPTCHA solving with usage limits ($5 credit/month)

Common pitfall: Using Start plan to test a site requiring CAPTCHA, tasks keep getting stuck at verification:

browse open https://example.com requiring-captcha
# Stuck at CAPTCHA page, no progress

I checked my billing and discovered every retry was being charged.

Correct approach:

1. First use browse what-antibot to detect if target site has CAPTCHA protection

2. If yes and you need auto-solving → upgrade to at least Developer plan

3. If just testing → use browse env local + manually solve CAPTCHA

# Detect site type first
browse what-antibot https://target-site.com

Problem 5: Proxy Region Restrictions

Browserbase's remote mode provides residential proxies, but IP geolocation is fixed by plan:

Plan	Proxy Regions
Start	US, Canada, Europe (random)
Developer	Same + can specify regions
Startup/Growth/Enterprise	More regions (Asia, Oceania, etc.)

Pitfall: Testing a site requiring Japanese IP, used Start plan, all requests routed to US nodes — site detected IP mismatch and blocked access.

Fix:

1. Need specific region → check if your plan supports it

2. Just need to bypass bot detection → use local mode + disable JavaScript detection

# Check proxy configuration
bb usage

# View current IP info
browse env remote --info

Complete Setup Checklist

Here's the verified complete setup flow:

# 1. Install CLI
npm install -g @browserbasehq/browse-cli

# 2. Set API KEY (get from https://browserbase.com/settings)
export BROWSERBASE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# 3. Verify authentication
browse auth status

# 4. Choose mode (use local for development)
browse env local

# 5. Test installation
browse open https://example.com
browse screenshot