browse 0.8.1 → 0.8.2-alpha-e7d3b55

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Browserbase, Inc.
+Copyright (c) 2024 Browserbase Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,49 @@
-# Browse CLI
+<div align="center">
 
-> Single CLI your AI agents need to access the internet reliably.
+# >_ browse
+
+### The single CLI your AI agents need to access the internet reliably.
+
+[![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/stagehand/blob/main/packages/cli/LICENSE)
 
 ```bash
 npm install -g browse
 ```
 
-## Main features:
-1. **Browser interactions** — Navigate tricky and complex websites with `browse click`, `browse mouse scroll`, `browse type`, `browse select`, and 20+ more DOM manipulation commands.
-2. **Web skills catalog** — `browse` is the official CLI for [browse.sh](https://browse.sh), the largest open web catalog. Your agent can run `browse skills add apartments.com` to learn how to use that website and APIs.
-3. **Rich debugging** — Arm your agents with network, console, and other web telemetry.
-4. **Cloud features** — Optionally use Browserbase cloud features, such as loading cookies via saved [Contexts](https://docs.browserbase.com/platform/browser/core-features/contexts), using [Verified Browsers](https://www.browserbase.com/verified), and the [Fetch and Search APIs](https://www.browserbase.com/search).
+<img src="https://github.com/browserbase/stagehand/blob/main/packages/cli/media/browse.gif?raw=true" alt="browse CLI demo" width="100%" />
+
+</div>
+
+---
+
+`browse` gives any agent — or any terminal — a reliable way to drive a real browser, learn how to use specific websites, and tap into Browserbase's cloud. One command to navigate the open web, capture telemetry while you do it, and reuse skills the community has already built.
+
+## Why browse
+
+- **Browser interactions** — Navigate tricky, complex websites with `browse click`, `browse mouse scroll`, `browse type`, `browse select`, and 20+ 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).
+
+## Quick start
+
+```bash
+npm install -g browse
+
+browse open https://example.com
+browse snapshot --compact
+browse click @0-12
+browse fill @0-8 "hello"
+browse get title
+browse screenshot --path page.png
+browse stop
+```
 
+## Driver commands
 
-## Driver Commands
+Drive a real browser from the terminal — locally, over CDP, or on a remote Browserbase session.
 
 ```bash
 browse open https://example.com
@@ -38,61 +68,49 @@ 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.
 
-[!NOTE]
-Security 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, so use network capture only on trusted machines and run `browse network clear` when done.
+> [!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.
 
-## Open Web Skills Catalog
-
-Your CLI can directly use [browse.sh](https://browse.sh), the largest open-source catalog of skills to reliably perform any task on the internet. For example, find a specialized skill to navigate `apartments.com` and reduce your agent time and token costs drastically.
+## 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.
 
 ```bash
-browse skills install
-browse skills list
-browse skills find reviews
+browse skills install                                       # install the bundled browse CLI skill
+browse skills list                                          # list the public Browse.sh catalog
+browse skills find reviews                                  # search by slug, domain, title, tag…
 browse skills find yelp.com/extract-reviews
-browse skills add yelp.com/extract-reviews
+browse skills add yelp.com/extract-reviews                  # install a catalog skill
 browse skills add mcdonalds.order.online/order-delivery-42q71n
 ```
 
-`browse skills install` installs the bundled `browse` CLI skill from this package.
-`browse skills list` lists the public Browse.sh skill catalog.
-`browse skills find` searches the public Browse.sh skill catalog by slug, domain, title, description, category, alias, or tag.
-`browse skills add` installs catalog skills from `browserbase/browse.sh` or generated skills from Browserbase-hosted public storage.
+## Browserbase cloud commands
 
-## Browserbase Cloud Commands
+Manage projects, sessions, contexts, and extensions, or call the Fetch and Search APIs directly.
 
 ```bash
-browse --help
-browse cloud --help
 browse cloud projects list
 browse cloud projects get <project-id>
 browse cloud projects usage <project-id>
 browse cloud sessions list
 browse cloud sessions get <session-id>
 browse cloud sessions create
-browse cloud sessions update <session-id>
 browse cloud sessions debug <session-id>
 browse cloud sessions logs <session-id>
 browse cloud sessions downloads get <session-id>
 browse cloud sessions uploads create <session-id> <file>
 browse cloud contexts create
 browse cloud contexts get <context-id>
-browse cloud contexts update <context-id>
-browse cloud contexts delete <context-id>
 browse cloud extensions upload <file>
-browse cloud extensions get <extension-id>
-browse cloud extensions delete <extension-id>
 browse cloud fetch <url>
 browse cloud search <query>
 ```
 
-`browse cloud fetch` requests markdown-formatted page content by default. Use `--format raw` for the original response body, or `--format json --schema <schema>` for structured extraction.
-
-## Functions Commands
+`browse cloud fetch` returns markdown-formatted page content by default. Use `--format raw` for the original response body, or `--format json --schema <schema>` for structured extraction.
 
-Browserbase [Functions](https://docs.browserbase.com/platform/runtime/overview) let you deploy browser agents or automation scripts directly onto Browserbase’s infrastructure. Start in your local environment, configure agents or write browser scripts, test them instantly, and deploy directly as cloud functions invokable as APIs.
+## Functions
 
+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
@@ -102,3 +120,23 @@ browse functions publish index.ts --dry-run
 browse functions invoke <function-id> --params '{"url":"https://example.com"}'
 browse functions invoke --check-status <invocation-id>
 ```
+
+## Configuration
+
+Set your Browserbase API key to enable remote sessions and cloud commands:
+
+```bash
+export BROWSERBASE_API_KEY=bb_live_...
+```
+
+Local driver commands (`--local`) work without an API key.
+
+## Links
+
+- [browse.sh](https://browse.sh) — open web skills catalog
+- [Browserbase docs](https://docs.browserbase.com)
+- [GitHub](https://github.com/browserbase/stagehand/tree/main/packages/cli) · [Issues](https://github.com/browserbase/stagehand/issues)
+
+## 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 {