@browserbasehq/cli 0.3.0 → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,20 +1,181 @@
 # Browserbase CLI
 
-Browserbase's Bun-native development repo for the `bb` CLI.
+The official CLI for [Browserbase](https://browserbase.com). Manage sessions, deploy serverless functions, browse the web, and interact with the full Browserbase platform from your terminal.
 
-## Development
+## Installation
 
 ```bash
-bun install
-bun run check
-bun run cli -- --help
+npm install -g @browserbasehq/cli
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# Set your API key
+export BROWSERBASE_API_KEY=bb_live_...
+
+# Fetch a webpage
+bb fetch https://example.com
+
+# Search the web
+bb search "browserbase documentation"
+
+# Browse interactively
+bb browse https://example.com
+
+# List your sessions
+bb sessions list
 ```
 
-## Build
+## Commands
+
+### `bb fetch <url>`
+
+Retrieve webpage content without a full browser session.
 
 ```bash
-bun run build
+bb fetch https://example.com
+bb fetch https://example.com --output page.json
+bb fetch https://example.com --proxies --allow-redirects
 ```
 
-The published artifact is Node-compatible JavaScript in `dist/`, even though local
-development stays Bun-native.
+| Flag | Description |
+|------|-------------|
+| `--output <path>` | Write response to file |
+| `--proxies` | Enable Browserbase proxy support |
+| `--allow-redirects` | Follow HTTP redirects |
+| `--allow-insecure-ssl` | Bypass TLS certificate verification |
+
+### `bb search <query>`
+
+Search the web using the Browserbase Search API.
+
+```bash
+bb search "web automation tools"
+bb search "browserbase" --num-results 5
+```
+
+| Flag | Description |
+|------|-------------|
+| `--num-results <n>` | Number of results (1-25, default 10) |
+| `--output <path>` | Write results to file |
+
+### `bb browse [args...]`
+
+Launch a browser session. Forwards to the `@browserbasehq/browse-cli` package (auto-installs on first use).
+
+```bash
+bb browse https://example.com
+bb browse --yes  # skip install prompt
+```
+
+### `bb sessions`
+
+Manage remote browser sessions.
+
+```bash
+bb sessions list                    # List all sessions
+bb sessions list --q "status=RUNNING"  # Filter by metadata
+bb sessions get <session-id>        # Get session details
+bb sessions create --body '{"projectId":"..."}'
+bb sessions update <id> --status REQUEST_RELEASE
+bb sessions debug <id>              # Get debugger connection URLs
+bb sessions logs <id>               # View session logs
+bb sessions recording <id>          # Get rrweb recording events
+bb sessions downloads get <id>      # Download session artifacts (ZIP)
+bb sessions uploads create <id> <file>  # Upload a file to a session
+```
+
+### `bb functions`
+
+Write and deploy serverless browser automation to the cloud.
+
+```bash
+# Scaffold a new project
+bb functions init my-function
+
+# Run locally
+bb functions dev handler.ts --port 3000
+
+# Deploy to Browserbase
+bb functions publish handler.ts
+bb functions publish handler.ts --dry-run  # preview without deploying
+
+# Invoke a deployed function
+bb functions invoke <function-id> --params '{"url":"https://example.com"}'
+bb functions invoke --check-status <invocation-id>
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `init [name]` | Scaffold a Functions project (`--package-manager npm\|pnpm`) |
+| `dev <entry>` | Start local dev server (`--port`, `--host`, `--verbose`) |
+| `publish <entry>` | Deploy function (`--dry-run`) |
+| `invoke [id]` | Invoke a function (`--params`, `--no-wait`, `--check-status`) |
+
+### `bb projects`
+
+Manage Browserbase projects.
+
+```bash
+bb projects list
+bb projects get <project-id>
+bb projects usage <project-id>
+```
+
+### `bb contexts`
+
+Persist browser state (cookies, localStorage) across sessions.
+
+```bash
+bb contexts create --body '{"projectId":"..."}'
+bb contexts get <context-id>
+bb contexts update <context-id>   # Refresh upload URL
+bb contexts delete <context-id>
+```
+
+### `bb extensions`
+
+Manage Chrome extensions for remote sessions.
+
+```bash
+bb extensions upload extension.zip
+bb extensions get <extension-id>
+bb extensions delete <extension-id>
+```
+
+### `bb skills`
+
+Install Browserbase agent skills for Claude Code.
+
+```bash
+bb skills           # Interactive install
+bb skills install   # Non-interactive install
+bb skills --yes     # Auto-accept prompts
+```
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `BROWSERBASE_API_KEY` | Your Browserbase API key (required) |
+| `BROWSERBASE_PROJECT_ID` | Default project ID for Functions |
+| `BROWSERBASE_BASE_URL` | Custom API base URL |
+
+All environment variables can be overridden per-command with `--api-key`, `--project-id`, or `--base-url` flags.
+
+## Development
+
+```bash
+bun install
+bun run cli -- --help     # Run locally
+bun run check             # Type-check
+bun run build             # Build to dist/
+bun run test              # Build + run tests
+```
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

package/dist/cli.js

@@ -4,7 +4,6 @@ import { attachBrowseCommand } from "./commands/browse.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 import { attachContextsCommand } from "./commands/contexts.js";
-import { attachDashboardCommand } from "./commands/dashboard.js";
 import { attachExtensionsCommand } from "./commands/extensions.js";
 import { attachFetchCommand } from "./commands/fetch.js";
 import { attachFunctionsCommand } from "./commands/functions.js";
@@ -12,6 +11,7 @@ import { attachSearchCommand } from "./commands/search.js";
 import { attachProjectsCommand } from "./commands/projects.js";
 import { attachSessionsCommand } from "./commands/sessions.js";
 import { attachSkillsCommand } from "./commands/skills.js";
+import { attachBCommand } from "./commands/b.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -27,12 +27,12 @@ export function buildProgram() {
     attachFetchCommand(program);
     attachSearchCommand(program);
     attachSessionsCommand(program);
-    attachDashboardCommand(program);
     attachFunctionsCommand(program);
     attachProjectsCommand(program);
     attachContextsCommand(program);
     attachExtensionsCommand(program);
     attachSkillsCommand(program);
+    attachBCommand(program);
     return program;
 }
 export async function run(argv) {

package/dist/commands/b.js

@@ -0,0 +1,19 @@
+const B_LINES = [
+    "██████╗ ",
+    "██╔══██╗",
+    "██████╔╝",
+    "██╔══██╗",
+    "██████╔╝",
+    "╚═════╝ ",
+];
+export function attachBCommand(program) {
+    program
+        .command("b [extra]", { hidden: true })
+        .description("🅱️")
+        .action((extra) => {
+        const count = 1 + (extra ? extra.length : 0);
+        for (const line of B_LINES) {
+            console.log(Array(count).fill(line).join("  "));
+        }
+    });
+}

package/dist/commands/browse.js

@@ -1,5 +1,24 @@
+import * as readline from "node:readline/promises";
 import { fail } from "../lib/command.js";
 import { findExecutable, spawnPassthrough } from "../lib/process.js";
+async function installBrowseCli() {
+    const npmPath = await findExecutable("npm");
+    if (!npmPath) {
+        fail([
+            "`npm` is not installed.",
+            "Install Node.js from https://nodejs.org to get npm,",
+            "then rerun `bb browse`.",
+        ].join("\n"));
+    }
+    const exitCode = await spawnPassthrough(npmPath, [
+        "install",
+        "-g",
+        "@browserbasehq/browse-cli",
+    ]);
+    if (exitCode !== 0) {
+        process.exitCode = exitCode;
+    }
+}
 export function attachBrowseCommand(program) {
     program
         .command("browse")
@@ -8,18 +27,42 @@ export function attachBrowseCommand(program) {
         .allowUnknownOption(true)
         .allowExcessArguments(true)
         .passThroughOptions()
+        .helpOption(false)
         .action(async (args) => {
-        const browsePath = await findExecutable("browse");
+        let browsePath = await findExecutable("browse");
         if (!browsePath) {
-            fail([
+            console.log([
+                "",
                 "`browse` is not installed.",
-                "Install it with:",
-                "npm install -g @browserbasehq/browse-cli",
+                "Automate web browser interactions using natural language via CLI commands.",
+                "",
+                "  npm install -g @browserbasehq/browse-cli",
                 "",
-                "Then rerun your `bb browse ...` command.",
             ].join("\n"));
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            try {
+                const answer = await rl.question("Install now? [Y/n] ");
+                if (answer.trim().toLowerCase() === "n") {
+                    return;
+                }
+            }
+            finally {
+                rl.close();
+            }
+            await installBrowseCli();
+            browsePath = await findExecutable("browse");
+            if (!browsePath) {
+                fail([
+                    "Installation succeeded but `browse` was not found on PATH.",
+                    "You may need to restart your shell, then rerun your command.",
+                ].join("\n"));
+            }
         }
-        const exitCode = await spawnPassthrough(browsePath, args ?? []);
+        const forwardArgs = args && args.length > 0 ? args : ["--help"];
+        const exitCode = await spawnPassthrough(browsePath, forwardArgs);
         if (exitCode !== 0) {
             process.exitCode = exitCode;
         }

package/dist/commands/contexts.js

@@ -1,4 +1,4 @@
-import { addCommonApiOptions, createBrowserbaseClient, mergeProjectIdIntoBody, outputJson, parseOptionalJsonObjectArg, requestBrowserbase, requestBrowserbaseJson, resolveProjectId, } from "../lib/command.js";
+import { addCommonApiOptions, createBrowserbaseClient, outputJson, parseOptionalJsonObjectArg, requestBrowserbase, requestBrowserbaseJson, } from "../lib/command.js";
 export function attachContextsCommand(program) {
     const contexts = program
         .command("contexts")
@@ -12,7 +12,7 @@ export function attachContextsCommand(program) {
         .description("Create a context.")
         .option("--body <body>", "Optional JSON request body.")).action(async (options) => {
         const client = createBrowserbaseClient(options);
-        const body = mergeProjectIdIntoBody(resolveProjectId(options), parseOptionalJsonObjectArg(options.body, "body"));
+        const body = parseOptionalJsonObjectArg(options.body, "body");
         outputJson(await client.contexts.create(body));
     });
     addCommonApiOptions(contexts

package/dist/commands/fetch.js

@@ -16,20 +16,15 @@ export function attachFetchCommand(program) {
         });
         if (options.output) {
             await writeOutputFile(options.output, result.content);
-            if (options.json) {
-                outputJson({ ...result, outputPath: options.output });
-                return;
-            }
-            console.log(`Saved fetched content to ${options.output}`);
+            outputJson({
+                ok: true,
+                outputPath: options.output,
+                contentType: result.contentType,
+                statusCode: result.statusCode,
+                sizeBytes: Buffer.byteLength(result.content, "utf8"),
+            });
             return;
         }
-        if (options.json) {
-            outputJson(result);
-            return;
-        }
-        process.stdout.write(result.content);
-        if (!result.content.endsWith("\n")) {
-            process.stdout.write("\n");
-        }
+        outputJson(result);
     });
 }

package/dist/commands/search.js

@@ -13,30 +13,15 @@ export function attachSearchCommand(program) {
         });
         if (options.output) {
             await writeOutputFile(options.output, JSON.stringify(result, null, 2));
-            if (options.json) {
-                outputJson({ ...result, outputPath: options.output });
-                return;
-            }
-            console.log(`Saved search results to ${options.output}`);
+            outputJson({
+                ok: true,
+                outputPath: options.output,
+                requestId: result.requestId,
+                query: result.query,
+                resultCount: result.results.length,
+            });
             return;
         }
-        if (options.json) {
-            outputJson(result);
-            return;
-        }
-        for (const [i, r] of result.results.entries()) {
-            const num = i + 1;
-            console.log(`${String(num)}. ${r.title}`);
-            console.log(`   ${r.url}`);
-            const meta = [];
-            if (r.author)
-                meta.push(r.author);
-            if (r.publishedDate)
-                meta.push(r.publishedDate);
-            if (meta.length > 0) {
-                console.log(`   ${meta.join(" · ")}`);
-            }
-            console.log();
-        }
+        outputJson(result);
     });
 }

package/dist/commands/sessions.js

@@ -1,5 +1,5 @@
 import { Option } from "commander";
-import { addCommonApiOptions, createBrowserbaseClient, fail, mergeProjectIdIntoBody, outputJson, parseOptionalJsonObjectArg, resolveProjectId, resolveUploadableFile, writeBinaryOutput, } from "../lib/command.js";
+import { addCommonApiOptions, createBrowserbaseClient, fail, outputJson, parseOptionalJsonObjectArg, resolveUploadableFile, writeBinaryOutput, } from "../lib/command.js";
 export function attachSessionsCommand(program) {
     const sessions = program
         .command("sessions")
@@ -11,7 +11,7 @@ export function attachSessionsCommand(program) {
     addCommonApiOptions(sessions
         .command("list")
         .description("List sessions.")
-        .option("--q <q>", "Session metadata query.")).action(async (options) => {
+        .option("--q <q>", `Session metadata query (e.g. "user_metadata['env']:'staging'").`)).action(async (options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.sessions.list(options.q ? { q: options.q } : {}));
     });
@@ -26,7 +26,7 @@ export function attachSessionsCommand(program) {
         .description("Create a session.")
         .option("--body <body>", "Optional JSON request body.")).action(async (options) => {
         const client = createBrowserbaseClient(options);
-        const body = mergeProjectIdIntoBody(resolveProjectId(options), parseOptionalJsonObjectArg(options.body, "body"));
+        const body = parseOptionalJsonObjectArg(options.body, "body");
         outputJson(await client.sessions.create(body));
     });
     addCommonApiOptions(sessions
@@ -38,10 +38,10 @@ export function attachSessionsCommand(program) {
         .option("--body <body>", "Optional JSON request body. Merged with --status when provided.")).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         const sessionId = id || fail("Session ID is required.");
-        const body = mergeProjectIdIntoBody(resolveProjectId(options), {
+        const body = {
             ...parseOptionalJsonObjectArg(options.body, "body"),
             status: options.status ?? "REQUEST_RELEASE",
-        });
+        };
         outputJson(await client.sessions.update(sessionId, body));
     });
     addCommonApiOptions(sessions

package/dist/lib/command.js

@@ -17,10 +17,7 @@ export function fail(message, exitCode = 1) {
 export function addCommonApiOptions(command) {
     return command
         .option("--api-key <apiKey>", "Override the Browserbase API key.")
-        .option("--project-id <projectId>", "Override the Browserbase project ID.")
-        .option("--base-url <baseUrl>", "Override the Browserbase API base URL.")
-        .option("--json", "Print JSON output.")
-        .option("--verbose", "Enable verbose logging.");
+        .option("--base-url <baseUrl>", "Override the Browserbase API base URL.");
 }
 export function addFunctionsApiOptions(command, options = {}) {
     const { includeProjectId = false, includeVerbose = false } = options;
@@ -91,12 +88,6 @@ export function parseOptionalJsonValueArg(rawValue, label) {
         fail(`Invalid JSON for ${label}: ${error.message}`);
     }
 }
-export function mergeProjectIdIntoBody(projectId, body) {
-    if (projectId && body.projectId === undefined) {
-        return { ...body, projectId };
-    }
-    return body;
-}
 export function outputJson(value) {
     console.log(JSON.stringify(value, null, 2));
 }

package/dist/lib/functions/init.js

@@ -64,7 +64,7 @@ export async function initFunctionsProject({ projectName, packageManager, }) {
         type: "module",
         scripts: {
             dev: "bb functions dev index.ts",
-            publish: "bb functions publish index.ts",
+            deploy: "bb functions publish index.ts",
         },
     };
     await writeFile(join(projectRoot, "package.json"), JSON.stringify(packageJson, null, 2) + "\n");
@@ -90,6 +90,7 @@ export async function initFunctionsProject({ projectName, packageManager, }) {
     console.log(`  cd ${projectName}`);
     console.log("  Edit .env with your Browserbase credentials");
     console.log(`  ${packageManager === "pnpm" ? "pnpm" : "npm run"} dev`);
+    console.log(`  ${packageManager === "pnpm" ? "pnpm run deploy" : "npm run deploy"}`);
 }
 function runPackageManager(packageManager, args, cwd) {
     const result = spawnSync(packageManager, args, {

package/dist/lib/functions/publish.js

@@ -1,7 +1,8 @@
 import archiver from "archiver";
 import ignore from "ignore";
-import { createWriteStream, existsSync, readFileSync } from "node:fs";
+import { copyFileSync, createWriteStream, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { readFile, readdir, stat } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -25,21 +26,24 @@ const defaultIgnorePatterns = [
 export async function publishFunction(options) {
     const entrypoint = await resolveEntrypoint(options.entrypoint);
     const config = resolveFunctionsProjectConfig(options);
-    const archivePath = await createArchive(process.cwd(), options.dryRun);
-    const metadata = {
-        entrypoint: relative(process.cwd(), entrypoint),
-        projectId: config.projectId,
-    };
     if (options.dryRun) {
+        const { archivePath, entries } = await createArchive(process.cwd());
         console.log(JSON.stringify({
             dryRun: true,
             apiUrl: config.apiUrl,
             projectId: config.projectId,
-            entrypoint: metadata.entrypoint,
+            entrypoint: relative(process.cwd(), entrypoint),
             archivePath,
+            files: entries,
         }, null, 2));
         return;
     }
+    ensureNpmLockfile(process.cwd());
+    const { archivePath, entries } = await createArchive(process.cwd());
+    const metadata = {
+        entrypoint: relative(process.cwd(), entrypoint),
+        projectId: config.projectId,
+    };
     const formData = new FormData();
     formData.append("metadata", JSON.stringify(metadata));
     formData.append("archive", new Blob([await readFile(archivePath)], {
@@ -69,13 +73,10 @@ export async function publishFunction(options) {
         process.exitCode = 1;
     }
 }
-async function createArchive(root, dryRun) {
+async function createArchive(root) {
     const archivePath = join(tmpdir(), `browserbase-functions-${randomUUID()}.tar.gz`);
     const ignoreMatcher = await loadIgnoreMatcher(root);
     const entries = await listArchiveEntries(root, root, ignoreMatcher);
-    if (dryRun) {
-        console.log(JSON.stringify({ files: entries }, null, 2));
-    }
     await new Promise((resolve, reject) => {
         const output = createWriteStream(archivePath);
         const archive = archiver("tar", {
@@ -97,7 +98,27 @@ async function createArchive(root, dryRun) {
         }
         archive.finalize().catch(reject);
     });
-    return archivePath;
+    return { archivePath, entries };
+}
+function ensureNpmLockfile(root) {
+    if (existsSync(join(root, "package-lock.json"))) {
+        return;
+    }
+    // Generate in a temp directory to avoid conflicts with pnpm's node_modules
+    // structure, then copy the lockfile back.
+    const tmpDir = join(tmpdir(), `bb-lockgen-${randomUUID()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    copyFileSync(join(root, "package.json"), join(tmpDir, "package.json"));
+    const result = spawnSync("npm", ["install", "--package-lock-only"], {
+        cwd: tmpDir,
+        stdio: "pipe",
+    });
+    if (result.status !== 0) {
+        rmSync(tmpDir, { recursive: true, force: true });
+        fail("Failed to generate package-lock.json. The build server requires an npm lockfile.");
+    }
+    copyFileSync(join(tmpDir, "package-lock.json"), join(root, "package-lock.json"));
+    rmSync(tmpDir, { recursive: true, force: true });
 }
 async function loadIgnoreMatcher(root) {
     const matcher = ignore();

package/dist/lib/functions/shared.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { stat } from "node:fs/promises";
 import { extname, resolve } from "node:path";
-import { fail, outputJson, resolveApiKey, resolveProjectId } from "../command.js";
+import { fail, resolveApiKey, resolveProjectId } from "../command.js";
 const defaultFunctionsApiUrl = "https://api.browserbase.com";
 export function resolveFunctionsApiConfig(args) {
     return {
@@ -103,14 +103,3 @@ export function ensureCommand(command) {
         fail(`${command} is required but was not found on PATH.`);
     }
 }
-export function printFunctionsJsonOrMessage(value, options = {}) {
-    if (options.json) {
-        outputJson(value);
-        return;
-    }
-    if (options.message) {
-        console.log(options.message);
-        return;
-    }
-    outputJson(value);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Browserbase CLI for platform APIs, functions, and browse passthrough.",
   "type": "module",
   "private": false,

package/dist/commands/dashboard.js

@@ -1,11 +0,0 @@
-import { openUrl } from "../lib/open.js";
-export function attachDashboardCommand(program) {
-    program
-        .command("dashboard")
-        .description("Open the Browserbase web dashboard for your project.")
-        .action(async () => {
-        const url = "http://browserbase.com/overview";
-        await openUrl(url);
-        console.log(`Opened ${url}`);
-    });
-}