browse 0.8.2 → 0.8.3-alpha-95f9a9d

package/README.md

@@ -6,13 +6,13 @@
 
 [![npm version](https://img.shields.io/npm/v/browse.svg?style=flat-square&color=000000)](https://www.npmjs.com/package/browse)
 [![npm downloads](https://img.shields.io/npm/dm/browse.svg?style=flat-square&color=000000)](https://www.npmjs.com/package/browse)
-[![license](https://img.shields.io/npm/l/browse.svg?style=flat-square&color=000000)](https://github.com/browserbase/cli/blob/main/LICENSE)
+[![license](https://img.shields.io/badge/license-MIT-000000?style=flat-square)](https://github.com/browserbase/stagehand/blob/main/packages/cli/LICENSE)
 
 ```bash
 npm install -g browse
 ```
 
-<img src="https://github.com/browserbase/cli/blob/main/media/browse.gif" alt="browse CLI demo" width="100%" />
+<img src="https://github.com/browserbase/stagehand/blob/main/packages/cli/media/browse.gif?raw=true" alt="browse CLI demo" width="100%" />
 
 </div>
 
@@ -22,7 +22,7 @@ npm install -g browse
 
 ## Why browse
 
-- **Browser interactions** — Navigate tricky, complex websites with `browse click`, `browse mouse scroll`, `browse type`, `browse select`, and 20+ more DOM commands.
+- **Browser interactions** — Navigate tricky, complex websites with `browse click`, `browse mouse scroll`, `browse type`, `browse select`, and 30+ more DOM commands.
 - **Open web skills catalog** — `browse` is the official CLI for [browse.sh](https://browse.sh), the largest open web catalog. Run `browse skills add apartments.com` and your agent learns how to use that site and its APIs.
 - **Rich debugging** — Arm your agents with network, console, and other web telemetry.
 - **Cloud features** — Optionally use Browserbase cloud: load cookies via saved [Contexts](https://docs.browserbase.com/platform/browser/core-features/contexts), use [Verified Browsers](https://www.browserbase.com/verified), and call the [Fetch and Search APIs](https://www.browserbase.com/search).
@@ -41,36 +41,154 @@ browse screenshot --path page.png
 browse stop
 ```
 
-## Driver commands
+## How it works
 
-Drive a real browser from the terminal — locally, over CDP, or on a remote Browserbase session.
+`browse` runs a lightweight per-session daemon. The first command starts it, and subsequent commands reuse the same browser — so cookies, tabs, and snapshot refs persist between invocations. Run multiple isolated browsers at once with `--session <name>` (or the `BROWSE_SESSION` env var), and shut a session down with `browse stop`.
+
+### Browser targets
+
+Every driver command accepts the same flags to pick where the browser runs. Mix and match per command:
+
+| Flag | Target |
+|------|--------|
+| _(default)_ | Managed local browser, or remote when `BROWSERBASE_API_KEY` is set |
+| `--local` | Managed local browser (add `--headed` / `--headless`) |
+| `--remote` | Remote Browserbase session (uses `BROWSERBASE_API_KEY`) |
+| `--auto-connect` | Auto-discover and attach to a local Chrome with remote debugging enabled |
+| `--cdp <url\|port>` | Attach directly to a CDP endpoint (port, `http(s)://`, or `ws(s)://`) |
+| `--target-id <id>` | Select a specific CDP target when attaching to an existing browser |
 
 ```bash
-browse open https://example.com
+browse open https://example.com                 # default target
 browse open https://example.com --local --headed
 browse open https://example.com --remote
 browse open https://example.com --auto-connect
 browse open https://example.com --cdp 9222
 browse open https://example.com --cdp ws://127.0.0.1:9222/devtools/browser/<id> --target-id <target-id>
-browse snapshot --compact
-browse click @0-12
-browse fill @0-8 "hello"
-browse mouse click 240 320
-browse get title
-browse screenshot --path page.png
-browse tab list
-browse tab switch <target-id>
-browse network on
-browse cdp 9222 --pretty
-browse status
-browse stop
 ```
 
-Use `--local`, `--remote`, `--auto-connect`, or `--cdp <url|port>` per command to choose the browser target. Use `--target-id <id>` with `--cdp` when attaching to a specific CDP target. Driver commands use `BROWSERBASE_API_KEY` for remote Browserbase sessions.
+Run `browse doctor` to diagnose session and browser-connection prerequisites for any target.
+
+## Commands
+
+### Navigation
+
+```bash
+browse open <url>     # Open a URL (--wait load|domcontentloaded|networkidle, --timeout <ms>)
+browse reload         # Reload the active page
+browse back           # Navigate backward
+browse forward        # Navigate forward
+```
+
+### Snapshot & refs
+
+The accessibility snapshot is the recommended way for agents to discover elements. It prints a tree of refs like `@0-12` that the element commands accept directly.
+
+```bash
+browse snapshot                 # Accessibility snapshot + cached refs
+browse snapshot --compact       # Tree only, no ref maps
+browse snapshot --filter submit # Filter lines by text or /regex/, keeping ancestors
+browse snapshot --max-depth 4   # Trim output deeper than this depth
+browse refs                     # Show refs cached from the last snapshot
+```
+
+### Element actions
+
+Targets accept a snapshot ref (`@0-12`), an XPath, or a CSS selector.
+
+```bash
+browse click @0-12                          # Click (also accepts selectors)
+browse fill @0-8 "hello"                     # Fill an input (--press-enter to submit)
+browse select @0-9 "CA"                       # Select an option (--value for <option value>)
+browse type "hello world"                     # Type at the current focus (--delay, --mistakes)
+browse press Enter                            # Press a key (alias: browse key) e.g. Meta+K, Escape
+browse upload @0-4 ./resume.pdf               # Upload file(s) (repeat --file for more)
+browse highlight @0-12                         # Highlight an element (--duration <ms>)
+```
+
+### Mouse (raw coordinates)
+
+Use these when you need pixel coordinates instead of a ref. Add `--return-xpath` to get the XPath under the cursor.
+
+```bash
+browse mouse click 240 320      # Click coordinates (--button, --click-count)
+browse mouse hover 240 320      # Move the mouse
+browse mouse scroll 400 500 0 600   # Scroll from a point by (dx, dy)
+browse mouse drag 100 100 400 400   # Drag between two points (--steps, --delay)
+```
+
+### Page info & state
+
+```bash
+browse get url          # Read page data / element state:
+browse get title        #   url, title, text, html, value, box,
+browse get text @0-12   #   visible, checked, markdown
+browse get markdown body
+browse get box 'button[type=submit]'
+browse is visible @0-12       # Check element state: visible, checked
+browse eval 'document.title'  # Evaluate JavaScript in the page
+browse viewport 1280 720      # Set viewport size (--scale for device pixel ratio)
+browse cursor                 # Enable a visible cursor overlay
+browse screenshot --path page.png   # Screenshot (--full-page, --type, --quality, --clip)
+```
+
+### Waiting
+
+```bash
+browse wait load                          # Wait for a load state
+browse wait load networkidle --timeout 45000
+browse wait selector @0-12 --state visible  # visible|hidden|attached|detached
+browse wait timeout 1000                  # Wait a fixed number of ms
+```
+
+### Tabs
+
+```bash
+browse tab list             # List tabs (with stable targetIds)
+browse tab new [url]        # Open a new tab and make it active
+browse tab switch <target-id>  # Switch active tab (index or targetId)
+browse tab close [target-id]   # Close a tab (defaults to the active tab)
+```
+
+Prefer the `targetId` from `browse tab list` over the index for stable agent workflows.
+
+### Network capture
+
+Capture request/response traffic for the active session to a local directory.
+
+```bash
+browse network on       # Start capturing
+browse network off      # Stop capturing
+browse network path     # Print the capture directory
+browse network clear    # Clear captured requests
+```
 
 > [!NOTE]
 > `browse network on` writes request/response headers and bodies to a local owner-only capture directory. These files can include cookies, authorization headers, and other secrets — use network capture only on trusted machines and run `browse network clear` when done.
 
+### Session & daemon
+
+```bash
+browse status      # Show daemon status for a session
+browse stop        # Stop the daemon (--force to kill an unresponsive browser)
+browse doctor      # Diagnose session and browser-connection prerequisites
+browse cdp 9222    # Attach to a CDP endpoint and stream DevTools events (--domain, --pretty)
+```
+
+### Global flags
+
+These apply across driver commands:
+
+| Flag | Description |
+|------|-------------|
+| `-s, --session <name>` | Named browser session (or `BROWSE_SESSION` env var) |
+| `--local` / `--remote` | Choose a managed local or remote Browserbase browser |
+| `--headed` / `--headless` | Window visibility for managed local sessions |
+| `--auto-connect` | Attach to a local Chrome with remote debugging enabled |
+| `--cdp <url\|port>` | Attach directly to a CDP endpoint |
+| `--target-id <id>` | Select a specific CDP target |
+| `--json` | Emit machine-readable JSON (available on most commands) |
+
 ## Open web skills catalog
 
 Use [browse.sh](https://browse.sh), the largest open-source catalog of skills to reliably perform any task on the internet. Find a specialized skill to navigate `apartments.com`, for example, and drastically reduce your agent's time and token costs.
@@ -78,6 +196,7 @@ Use [browse.sh](https://browse.sh), the largest open-source catalog of skills to
 ```bash
 browse skills install                                       # install the bundled browse CLI skill
 browse skills list                                          # list the public Browse.sh catalog
+browse skills list --all                                    # include every catalog entry
 browse skills find reviews                                  # search by slug, domain, title, tag…
 browse skills find yelp.com/extract-reviews
 browse skills add yelp.com/extract-reviews                  # install a catalog skill
@@ -86,23 +205,37 @@ browse skills add mcdonalds.order.online/order-delivery-42q71n
 
 ## Browserbase cloud commands
 
-Manage projects, sessions, contexts, and extensions, or call the Fetch and Search APIs directly.
+Manage projects, sessions, contexts, and extensions, or call the Fetch and Search APIs directly. These commands use `BROWSERBASE_API_KEY`.
 
 ```bash
+# Projects
 browse cloud projects list
 browse cloud projects get <project-id>
 browse cloud projects usage <project-id>
-browse cloud sessions list
+
+# Sessions
+browse cloud sessions list                       # --limit, --status, --json
 browse cloud sessions get <session-id>
-browse cloud sessions create
-browse cloud sessions debug <session-id>
+browse cloud sessions create                     # --proxies, --verified, --region, --solve-captchas…
+browse cloud sessions update <session-id> --status REQUEST_RELEASE
+browse cloud sessions debug <session-id>         # live debugger URLs
 browse cloud sessions logs <session-id>
-browse cloud sessions downloads get <session-id>
-browse cloud sessions uploads create <session-id> <file>
+browse cloud sessions downloads get <session-id> # --output ./downloads.zip
+browse cloud sessions uploads create <session-id> ./file.pdf
+
+# Contexts
 browse cloud contexts create
 browse cloud contexts get <context-id>
-browse cloud extensions upload <file>
-browse cloud fetch <url>
+browse cloud contexts update <context-id>        # refresh the upload URL
+browse cloud contexts delete <context-id>
+
+# Extensions
+browse cloud extensions upload ./extension.zip
+browse cloud extensions get <extension-id>
+browse cloud extensions delete <extension-id>
+
+# Fetch & Search APIs
+browse cloud fetch <url>                          # markdown by default
 browse cloud search <query>
 ```
 
@@ -113,14 +246,24 @@ browse cloud search <query>
 Browserbase [Functions](https://docs.browserbase.com/platform/runtime/overview) let you deploy browser agents and automation scripts directly onto Browserbase's infrastructure. Build locally, test instantly, and deploy as APIs.
 
 ```bash
-browse functions init my-function
-browse functions dev index.ts
-browse functions publish index.ts
-browse functions publish index.ts --dry-run
+browse functions init my-function          # scaffold a new project (--package-manager)
+browse functions dev index.ts              # local development server (--port, --verbose)
+browse functions publish index.ts          # package and upload (--dry-run to preview)
 browse functions invoke <function-id> --params '{"url":"https://example.com"}'
 browse functions invoke --check-status <invocation-id>
 ```
 
+## Templates
+
+Discover and scaffold ready-to-run Browserbase example projects.
+
+```bash
+browse templates list                      # --tag, --source, --wide, --json
+browse templates find amazon               # search by slug, title, category, or tag
+browse templates clone google-trends-keywords
+browse templates clone amazon-product-scraping --language python ./my-scraper
+```
+
 ## Configuration
 
 Set your Browserbase API key to enable remote sessions and cloud commands:
@@ -131,12 +274,17 @@ export BROWSERBASE_API_KEY=bb_live_...
 
 Local driver commands (`--local`) work without an API key.
 
+| Variable | Description |
+|----------|-------------|
+| `BROWSERBASE_API_KEY` | Enables `--remote` sessions and all `browse cloud` / `functions` commands |
+| `BROWSE_SESSION` | Default session name (alternative to `-s, --session`) |
+
 ## Links
 
 - [browse.sh](https://browse.sh) — open web skills catalog
 - [Browserbase docs](https://docs.browserbase.com)
-- [GitHub](https://github.com/browserbase/cli) · [Issues](https://github.com/browserbase/cli/issues)
+- [GitHub](https://github.com/browserbase/stagehand/tree/main/packages/cli) · [Issues](https://github.com/browserbase/stagehand/issues)
 
 ## License
 
-[MIT](https://github.com/browserbase/cli/blob/main/LICENSE)
+[MIT](https://github.com/browserbase/stagehand/blob/main/packages/cli/LICENSE)

package/dist/commands/click.js

@@ -4,7 +4,6 @@ import { driverCommandFlags, runDriverCommandFromFlags, } from "../lib/driver/co
 export default class Click extends BrowseCommand {
     static description = "Click an element by snapshot ref, XPath, or selector. Use `browse mouse click` for raw coordinates.";
     static examples = [
-        "browse snapshot --compact",
         "browse click @0-12",
         "browse click 'button[type=submit]'",
         "browse click @0-12 --session research",

package/dist/commands/network/on.js

@@ -4,7 +4,6 @@ export default class NetworkOn extends BrowseCommand {
     static description = "Enable network capture for the active browser session.";
     static examples = [
         "browse network on",
-        "browse network path",
         "browse network on --session research",
     ];
     static flags = {

package/dist/lib/cloud/api.js

@@ -12,8 +12,11 @@ export function resolveApiKey(args) {
     const apiKey = args.apiKey ?? process.env.BROWSERBASE_API_KEY;
     return (apiKey ||
         fail([
-            "Missing Browserbase API key. Set BROWSERBASE_API_KEY or pass --api-key.",
-            `You can find your API key at ${browserbaseSettingsUrl}.`,
+            "Missing Browserbase API key. Cloud commands (search, fetch, sessions, functions, ...) need one.",
+            "Set BROWSERBASE_API_KEY or pass --api-key.",
+            `Get a key at ${browserbaseSettingsUrl}.`,
+            "",
+            "No key? Local browser automation needs none. Try: browse open <url> --local",
         ].join("\n"), 1, {
             resultCode: "missing_api_key",
             requestHadHttpResponse: false,

package/dist/lib/driver/doctor.js

@@ -6,6 +6,7 @@ import { isProcessAlive } from "./daemon/process.js";
 import { discoverLocalCdp, } from "./local-cdp-discovery.js";
 import { hasExplicitDriverTarget } from "./command-cli.js";
 import { resolveConnectionTarget, targetsCompatible } from "./mode.js";
+import { getRemote } from "./remote-binding.js";
 const DEFAULT_URL = "https://example.com";
 export async function buildDoctorReport(options, deps = {}) {
     const checks = [];
@@ -176,18 +177,12 @@ async function checkTargetPrerequisite(target, flags, session, env, deps) {
         };
     }
     if (target.kind === "remote") {
-        if (env.BROWSERBASE_API_KEY) {
-            return {
-                message: "BROWSERBASE_API_KEY is set",
-                name: "browserbase",
-                status: "ok",
-            };
-        }
+        const result = (await getRemote()).remoteDoctorCheck(env);
         return {
-            fix: "export BROWSERBASE_API_KEY=...",
-            message: "BROWSERBASE_API_KEY is not set",
+            ...(result.fix ? { fix: result.fix } : {}),
+            message: result.message,
             name: "browserbase",
-            status: "fail",
+            status: result.ok ? "ok" : "fail",
         };
     }
     if (target.kind === "auto-connect") {

package/dist/lib/driver/mode.js

@@ -1,4 +1,5 @@
 import { fail } from "../errors.js";
+import { getRemote } from "./remote-binding.js";
 import { resolveWsTarget } from "./resolve-ws.js";
 function resolveHeadless(flags) {
     if (flags.headed && flags.headless) {
@@ -45,17 +46,18 @@ export async function resolveConnectionTarget(flags) {
             flags.headed ? "--headed" : null,
             flags.headless ? "--headless" : null,
         ]);
-        return { kind: "remote" };
+        return (await getRemote()).resolveExplicitRemoteTarget(flags);
     }
     if (flags.local) {
         return { kind: "managed-local", headless: resolveHeadless(flags) };
     }
-    if (process.env.BROWSERBASE_API_KEY) {
+    const autoRemote = (await getRemote()).autoSelectRemoteTarget();
+    if (autoRemote) {
         failOnConflictingFlags("remote mode", [
             flags.headed ? "--headed" : null,
             flags.headless ? "--headless" : null,
         ]);
-        return { kind: "remote" };
+        return autoRemote;
     }
     return { kind: "managed-local", headless: resolveHeadless(flags) };
 }

package/dist/lib/driver/remote-binding.js

@@ -0,0 +1,27 @@
+let cached;
+/**
+ * Load the Browserbase capability. The full build ships `remote.js`; the
+ * local-only build omits it, so we fall back to `remote.disabled.js`. The full
+ * specifier is held in a variable so the local-only TypeScript program can
+ * exclude `remote.ts` without the compiler eagerly pulling it back in.
+ */
+export async function getRemote() {
+    if (cached)
+        return cached;
+    const fullModule = "./remote.js";
+    try {
+        cached = (await import(fullModule));
+    }
+    catch (error) {
+        // The full build ships remote.js; the local-only build omits it. Only fall
+        // back to the disabled stub when the module is genuinely absent — rethrow
+        // any other error so a real failure inside remote.ts isn't masked as
+        // "remote disabled".
+        const code = error?.code;
+        if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") {
+            throw error;
+        }
+        cached = (await import("./remote.disabled.js"));
+    }
+    return cached;
+}

package/dist/lib/driver/remote-types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/driver/remote.disabled.js

@@ -0,0 +1,18 @@
+/**
+ * Stub Browserbase capability used by `build:local-only`. It contains no API
+ * key handling and never reaches the cloud. Any attempt to use a remote target
+ * fails loudly.
+ */
+const DISABLED_MESSAGE = "Remote (Browserbase) mode is disabled in this local-only build of browse. Rebuild without local-only to use cloud sessions.";
+export function resolveExplicitRemoteTarget() {
+    throw new Error(DISABLED_MESSAGE);
+}
+export function autoSelectRemoteTarget() {
+    return null;
+}
+export function remoteStagehandOptions() {
+    throw new Error(DISABLED_MESSAGE);
+}
+export function remoteDoctorCheck() {
+    return { ok: true, message: "remote disabled (local-only build)" };
+}

package/dist/lib/driver/remote.js

@@ -0,0 +1,37 @@
+/**
+ * Real Browserbase capability. This is the ONLY module that reads
+ * `BROWSERBASE_API_KEY`; it is excluded from `build:local-only` so that
+ * local-only artifacts cannot reach Browserbase.
+ */
+export function resolveExplicitRemoteTarget() {
+    return { kind: "remote" };
+}
+export function autoSelectRemoteTarget() {
+    return process.env.BROWSERBASE_API_KEY ? { kind: "remote" } : null;
+}
+export function remoteStagehandOptions() {
+    const apiKey = process.env.BROWSERBASE_API_KEY;
+    if (!apiKey) {
+        throw new Error("Missing BROWSERBASE_API_KEY for remote mode. Pass --local to run a managed local browser (no key needed), or set BROWSERBASE_API_KEY for cloud sessions.");
+    }
+    return {
+        apiKey,
+        browserbaseSessionCreateParams: {
+            userMetadata: { browse_cli: "true" },
+        },
+        disableAPI: true,
+        disablePino: true,
+        env: "BROWSERBASE",
+        verbose: 0,
+    };
+}
+export function remoteDoctorCheck(env) {
+    if (env.BROWSERBASE_API_KEY) {
+        return { ok: true, message: "BROWSERBASE_API_KEY is set" };
+    }
+    return {
+        ok: false,
+        message: "BROWSERBASE_API_KEY is not set",
+        fix: "export BROWSERBASE_API_KEY=...",
+    };
+}

package/dist/lib/driver/session-manager.js

@@ -3,6 +3,7 @@ import { emptyRefMaps, resolveSelector as resolveCachedSelector, } from "./comma
 import { executeDriverCommand } from "./commands/registry.js";
 import { discoverLocalCdp } from "./local-cdp-discovery.js";
 import { NetworkCapture } from "./network-capture.js";
+import { getRemote } from "./remote-binding.js";
 const INIT_FAILURE_RETRY_MS = 5_000;
 export class DriverSessionManager {
     session;
@@ -182,7 +183,7 @@ export class DriverSessionManager {
     }
     async initialize() {
         const resolvedTarget = await this.resolveTarget();
-        const options = this.stagehandOptions(resolvedTarget);
+        const options = await this.stagehandOptions(resolvedTarget);
         const stagehand = new Stagehand(options);
         try {
             await stagehand.init();
@@ -203,21 +204,9 @@ export class DriverSessionManager {
         }
         return { kind: "cdp", endpoint: discovered.wsUrl };
     }
-    stagehandOptions(target) {
+    async stagehandOptions(target) {
         if (target.kind === "remote") {
-            if (!process.env.BROWSERBASE_API_KEY) {
-                throw new Error("Missing BROWSERBASE_API_KEY. Set it or pass --local for a managed local browser.");
-            }
-            return {
-                apiKey: process.env.BROWSERBASE_API_KEY,
-                browserbaseSessionCreateParams: {
-                    userMetadata: { browse_cli: "true" },
-                },
-                disableAPI: true,
-                disablePino: true,
-                env: "BROWSERBASE",
-                verbose: 0,
-            };
+            return (await getRemote()).remoteStagehandOptions();
         }
         if (target.kind === "managed-local") {
             return {