@thinkbrowse/cli

CLI for ThinkBrowse browser automation.

thinkbrowse is the single CLI for controlling browsers via ThinkBrowse cloud and local (native host) infrastructure.

Requirements

• Node.js 18+ (uses native fetch)

OS Support

• macOS, Linux, Windows

Installation

npm install -g @thinkbrowse/cli   # works with npm, bun, pnpm, yarn
thinkbrowse setup                  # download native host + register Chrome extension

Install directly from this repository on your machine:

npm install -g /path/to/mech-browse/packages/cli
thinkbrowse setup

Quick Start

# 1. Install native host and configure API key
thinkbrowse setup

# 2. Configure API key (if not done during setup)
thinkbrowse config set-key tb_your_api_key_here

# 3. Start a cloud browser session (waits for provisioning)
thinkbrowse cloud start

# 4. Navigate and interact
thinkbrowse navigate "https://example.com"
thinkbrowse snapshot                    # Get accessibility tree
thinkbrowse click "button.submit"
thinkbrowse screenshot --output page.png

# 5. Stop the session
thinkbrowse cloud stop

Stateless page cache (no session)

One-shot HTML, text, or screenshot via POST /api/cache/* (uses your configured API URL and key — same as cloud commands):

thinkbrowse cache text https://example.com --json
thinkbrowse cache html https://example.com --provider local --sensitive
thinkbrowse cache screenshot https://example.com --json

Local Endpoint Quick Start (mech-browser-service)

# 1. Point CLI at local server
thinkbrowse config set apiUrl http://localhost:3009

# 2. Use local TEST_API_KEY from mech-browser-service/.env (often ak_...)
thinkbrowse config set-key ak_your_local_test_key

# 3. Start/select session, then run actions
thinkbrowse cloud start
thinkbrowse navigate http://localhost:3000

Use thinkbrowse doctor anytime to verify endpoint mode, health, bridge status, and active session.

AI Agent Workflow

The snapshot command returns an accessibility tree — ideal for AI agents that need to understand page structure without screenshots:

thinkbrowse cloud start
thinkbrowse navigate "https://github.com/trending"
thinkbrowse snapshot                    # Returns accessibility tree
thinkbrowse click "a.repo-name"         # AI decides what to click
thinkbrowse wait-for-text "README"      # Wait for content
thinkbrowse extract "article" --format json
thinkbrowse cloud stop

Commands

Session Management

| Command | Description | |---------|-------------| | cloud start | Start a new cloud browser session | | cloud stop | Stop the active session | | cloud list | List all active sessions | | cloud status | Show session details | | cloud artifacts | List session artifacts (screenshots, logs, actions) | | cloud use <id> | Switch active session | | doctor | Diagnose endpoint/auth/session setup |

Cloud Start Options

thinkbrowse cloud start [options]

Options:
  -b, --browser <type>  Browser: chromium (default), firefox, webkit
  --proxy               Enable proxy rotation
  --stealth             Enable anti-detection mode
  --no-wait             Return immediately without waiting for ready

Navigation

| Command | Description | |---------|-------------| | navigate <url> | Navigate to a URL | | back | Go back in browser history | | forward | Go forward in browser history |

thinkbrowse navigate "https://example.com" --wait-until networkidle
thinkbrowse back
thinkbrowse forward

Interaction

| Command | Description | |---------|-------------| | click <selector> | Click an element | | type <selector> <text> | Type text (appends) | | fill <selector> <value> | Fill form field (clears first) | | press <key> | Press keyboard key | | scroll | Scroll the page | | hover <selector> | Hover over element | | select <selector> <value> | Select dropdown option |

thinkbrowse fill "#email" "[email protected]"
thinkbrowse fill "#password" "secret123"
thinkbrowse press Enter
thinkbrowse click ".submit-btn" --timeout 5000
thinkbrowse hover ".dropdown-trigger"
thinkbrowse select "#country" "US"
thinkbrowse scroll --down 500
thinkbrowse scroll --to "#footer"

Waiting

| Command | Description | |---------|-------------| | wait <condition> | Wait for element or time (ms) | | wait-for-text <text> | Wait for text on page |

thinkbrowse wait 2000                              # Wait 2 seconds
thinkbrowse wait ".loading-complete"                # Wait for element
thinkbrowse wait ".spinner" --hidden                # Wait for element to hide
thinkbrowse wait-for-text "Success" --timeout 10000 # Wait for text

Observation

| Command | Description | |---------|-------------| | snapshot | Get accessibility tree | | screenshot | Capture screenshot | | extract <selector> | Extract content from elements | | evaluate [script] | Execute JavaScript in page | | url | Get the current page URL (cloud) | | title | Get the current page title (cloud) | | html | Get the full page HTML (cloud) |

thinkbrowse snapshot
thinkbrowse screenshot --output page.png --full-page
thinkbrowse extract "h1"
thinkbrowse extract ".item" --all --format json
thinkbrowse extract "a" --attr href --all
thinkbrowse evaluate "document.title"
thinkbrowse evaluate --file script.js
thinkbrowse url
thinkbrowse title
thinkbrowse html > page.html

Dialog Handling

| Command | Description | |---------|-------------| | dialog get | Check for pending dialog | | dialog accept [text] | Accept dialog | | dialog dismiss | Dismiss dialog |

thinkbrowse dialog get                    # Check for alerts/confirms/prompts
thinkbrowse dialog accept                 # Accept alert/confirm
thinkbrowse dialog accept "my answer"     # Accept prompt with text
thinkbrowse dialog dismiss                # Dismiss/cancel dialog

Monitoring

| Command | Description | |---------|-------------| | console | Get browser console messages | | network | Get network requests | | clear-logs | Clear console and network logs (cloud) |

thinkbrowse console      # View console.log, warnings, errors
thinkbrowse network      # View XHR, fetch, and other requests
thinkbrowse clear-logs   # Reset logs for the active session

Local Mode (Native Host)

These commands require the native host to be running (thinkbrowse doctor will confirm).

| Command | Description | |---------|-------------| | tabs | List open Chrome tabs | | attach <tabId> | Attach to a tab and set it as the active session | | switch-tab <tabId> | Switch active Chrome tab without changing session config |

# List all open tabs
thinkbrowse tabs

# Attach to a specific tab by ID, then run actions against it
thinkbrowse attach 12345
thinkbrowse snapshot
thinkbrowse navigate "https://example.com"

# Switch which tab is active in Chrome without updating the session config
thinkbrowse switch-tab 12345

Configuration

thinkbrowse config set-key <api-key>     # Set API key
thinkbrowse config show                  # Show current config
thinkbrowse config set apiUrl <url>      # Set custom API URL
thinkbrowse config set defaultBrowser firefox
thinkbrowse config reset                 # Reset all config

Config file: ~/.thinkbrowse/config.json

Global Options

• --json — Force JSON output (auto-enabled for non-TTY)
• --quiet — Suppress non-error output
• --verbose — Show debugging info

Examples

Web Scraping

thinkbrowse cloud start
thinkbrowse navigate "https://news.ycombinator.com"
thinkbrowse extract ".titleline > a" --all --format json > titles.json
thinkbrowse screenshot --output hn.png
thinkbrowse cloud stop

Form Automation

thinkbrowse cloud start
thinkbrowse navigate "https://example.com/login"
thinkbrowse fill "#email" "[email protected]"
thinkbrowse fill "#password" "secret123"
thinkbrowse click "button[type=submit]"
thinkbrowse wait-for-text "Dashboard"
thinkbrowse screenshot --output logged-in.png
thinkbrowse cloud stop

Debugging a Page

thinkbrowse cloud start
thinkbrowse navigate "https://myapp.com"
thinkbrowse console     # Check for JS errors
thinkbrowse network     # Check failed requests
thinkbrowse snapshot    # See page structure
thinkbrowse url         # Confirm current URL
thinkbrowse title       # Confirm page title
thinkbrowse cloud stop

Error Handling

The CLI returns structured errors with suggestions:

Error: API key not configured
Tip: Run: thinkbrowse config set-key <your-api-key>

Retryable errors (502, 503) are automatically retried with exponential backoff.

Troubleshooting

| Issue | Solution | |-------|----------| | API key not configured | Run thinkbrowse config set-key <key> | | Invalid API key (local URL) | Use local TEST_API_KEY from mech-browser-service/.env | | No active session | Run thinkbrowse cloud start, or thinkbrowse cloud list then thinkbrowse cloud use <id> | | Session provisioning timed out | Check thinkbrowse cloud status, try again | | fetch is not defined | Upgrade to Node.js 18+ | | All requests return 404 | Update to latest CLI version |

License

MIT