@browserbasehq/cli 0.3.1 → 0.4.0

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/commands/browse.js

@@ -19,6 +19,19 @@ async function installBrowseCli() {
         process.exitCode = exitCode;
     }
 }
+function extractYesFlag(args) {
+    const remaining = [];
+    let yes = false;
+    for (const arg of args) {
+        if (arg === "--yes" || arg === "-y") {
+            yes = true;
+        }
+        else {
+            remaining.push(arg);
+        }
+    }
+    return { yes, remaining };
+}
 export function attachBrowseCommand(program) {
     program
         .command("browse")
@@ -28,7 +41,15 @@ export function attachBrowseCommand(program) {
         .allowExcessArguments(true)
         .passThroughOptions()
         .helpOption(false)
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  bb browse --url https://example.com",
+        '  bb browse --url https://example.com --text "Click Login"',
+        "  bb browse --yes  (auto-install if not present)",
+    ].join("\n"))
         .action(async (args) => {
+        const { yes, remaining: forwardArgs } = extractYesFlag(args ?? []);
         let browsePath = await findExecutable("browse");
         if (!browsePath) {
             console.log([
@@ -39,18 +60,23 @@ export function attachBrowseCommand(program) {
                 "  npm install -g @browserbasehq/browse-cli",
                 "",
             ].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;
+            if (!yes) {
+                if (!process.stdin.isTTY) {
+                    fail("Cannot prompt for install in non-interactive mode. Use --yes to auto-install.");
+                }
+                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();
                 }
-            }
-            finally {
-                rl.close();
             }
             await installBrowseCli();
             browsePath = await findExecutable("browse");
@@ -61,8 +87,8 @@ export function attachBrowseCommand(program) {
                 ].join("\n"));
             }
         }
-        const forwardArgs = args && args.length > 0 ? args : ["--help"];
-        const exitCode = await spawnPassthrough(browsePath, forwardArgs);
+        const finalArgs = forwardArgs.length > 0 ? forwardArgs : ["--help"];
+        const exitCode = await spawnPassthrough(browsePath, finalArgs);
         if (exitCode !== 0) {
             process.exitCode = exitCode;
         }

package/dist/commands/contexts.js

@@ -1,4 +1,4 @@
-import { addCommonApiOptions, createBrowserbaseClient, outputJson, parseOptionalJsonObjectArg, requestBrowserbase, requestBrowserbaseJson, } from "../lib/command.js";
+import { addCommonApiOptions, addExamples, createBrowserbaseClient, outputJson, resolveBody, requestBrowserbase, requestBrowserbaseJson, } from "../lib/command.js";
 export function attachContextsCommand(program) {
     const contexts = program
         .command("contexts")
@@ -7,30 +7,35 @@ export function attachContextsCommand(program) {
     contexts.action(() => {
         contexts.outputHelp();
     });
-    addCommonApiOptions(contexts
+    addExamples(addCommonApiOptions(contexts
         .command("create")
         .description("Create a context.")
-        .option("--body <body>", "Optional JSON request body.")).action(async (options) => {
+        .option("--body <body>", "Optional JSON request body.")
+        .option("--stdin", "Read JSON request body from stdin.")), [
+        "bb contexts create",
+        `bb contexts create --body '{"projectId":"proj_abc"}'`,
+        `echo '{"projectId":"proj_abc"}' | bb contexts create --stdin`,
+    ]).action(async (options) => {
         const client = createBrowserbaseClient(options);
-        const body = parseOptionalJsonObjectArg(options.body, "body");
+        const body = await resolveBody(options);
         outputJson(await client.contexts.create(body));
     });
-    addCommonApiOptions(contexts
+    addExamples(addCommonApiOptions(contexts
         .command("get <id>")
-        .description("Get a context by ID.")).action(async (id, options) => {
+        .description("Get a context by ID.")), ["bb contexts get <context-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.contexts.retrieve(id));
     });
-    addCommonApiOptions(contexts
+    addExamples(addCommonApiOptions(contexts
         .command("update <id>")
-        .description("Refresh the upload URL for a context.")).action(async (id, options) => {
+        .description("Refresh the upload URL for a context.")), ["bb contexts update <context-id>"]).action(async (id, options) => {
         outputJson(await requestBrowserbaseJson(options, `/v1/contexts/${id}`, {
             method: "PUT",
         }));
     });
-    addCommonApiOptions(contexts
+    addExamples(addCommonApiOptions(contexts
         .command("delete <id>")
-        .description("Delete a context.")).action(async (id, options) => {
+        .description("Delete a context.")), ["bb contexts delete <context-id>"]).action(async (id, options) => {
         await requestBrowserbase(options, `/v1/contexts/${id}`, {
             method: "DELETE",
             headers: {

package/dist/commands/extensions.js

@@ -1,4 +1,4 @@
-import { addCommonApiOptions, createBrowserbaseClient, outputJson, requestBrowserbase, resolveUploadableFile, } from "../lib/command.js";
+import { addCommonApiOptions, addExamples, createBrowserbaseClient, outputJson, requestBrowserbase, resolveUploadableFile, } from "../lib/command.js";
 export function attachExtensionsCommand(program) {
     const extensions = program
         .command("extensions")
@@ -7,23 +7,23 @@ export function attachExtensionsCommand(program) {
     extensions.action(() => {
         extensions.outputHelp();
     });
-    addCommonApiOptions(extensions
+    addExamples(addCommonApiOptions(extensions
         .command("upload <file>")
-        .description("Upload an extension ZIP file.")).action(async (file, options) => {
+        .description("Upload an extension ZIP file.")), ["bb extensions upload ./extension.zip"]).action(async (file, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.extensions.create({
             file: await resolveUploadableFile(file, "extension"),
         }));
     });
-    addCommonApiOptions(extensions
+    addExamples(addCommonApiOptions(extensions
         .command("get <id>")
-        .description("Get an extension by ID.")).action(async (id, options) => {
+        .description("Get an extension by ID.")), ["bb extensions get <extension-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.extensions.retrieve(id));
     });
-    addCommonApiOptions(extensions
+    addExamples(addCommonApiOptions(extensions
         .command("delete <id>")
-        .description("Delete an extension.")).action(async (id, options) => {
+        .description("Delete an extension.")), ["bb extensions delete <extension-id>"]).action(async (id, options) => {
         await requestBrowserbase(options, `/v1/extensions/${id}`, {
             method: "DELETE",
             headers: {

package/dist/commands/fetch.js

@@ -1,12 +1,16 @@
-import { addCommonApiOptions, createBrowserbaseClient, outputJson, writeOutputFile, } from "../lib/command.js";
+import { addCommonApiOptions, addExamples, createBrowserbaseClient, outputJson, writeOutputFile, } from "../lib/command.js";
 export function attachFetchCommand(program) {
-    addCommonApiOptions(program
+    addExamples(addCommonApiOptions(program
         .command("fetch <url>")
         .description("Retrieve webpage content without a full browser session using the lightweight Browserbase Fetch API.")
         .option("--allow-insecure-ssl", "Bypass TLS certificate verification.")
         .option("--allow-redirects", "Follow HTTP redirects.")
         .option("--proxies", "Enable Browserbase proxy support.")
-        .option("--output <output>", "Write the fetched content to a file.")).action(async (url, options) => {
+        .option("--output <output>", "Write the fetched content to a file.")), [
+        "bb fetch https://www.google.com",
+        "bb fetch https://example.com --allow-insecure-ssl --output page.html",
+        "bb fetch https://example.com --allow-redirects --proxies",
+    ]).action(async (url, options) => {
         const client = createBrowserbaseClient(options);
         const result = await client.fetchAPI.create({
             url,

package/dist/commands/functions.js

@@ -1,5 +1,5 @@
 import { Option } from "commander";
-import { addFunctionsApiOptions } from "../lib/command.js";
+import { addExamples, addFunctionsApiOptions } from "../lib/command.js";
 import { initFunctionsProject } from "../lib/functions/init.js";
 import { invokeFunction } from "../lib/functions/invoke.js";
 import { startFunctionsDevServer } from "../lib/functions/dev.js";
@@ -13,23 +13,28 @@ export function attachFunctionsCommand(program) {
     functions.action(() => {
         functions.outputHelp();
     });
-    functions
+    addExamples(functions
         .command("init [projectName]")
         .description("Initialize a new Browserbase Functions project.")
         .addOption(new Option("--package-manager <packageManager>", "Package manager to use.")
         .choices([...packageManagers])
-        .default("pnpm"))
-        .action(async (projectName, options) => {
+        .default("pnpm")), [
+        "bb functions init my-function",
+        "bb functions init my-function --package-manager npm",
+    ]).action(async (projectName, options) => {
         await initFunctionsProject({
             projectName: projectName ?? "my-browserbase-function",
             packageManager: options.packageManager ?? "pnpm",
         });
     });
-    addFunctionsApiOptions(functions
+    addExamples(addFunctionsApiOptions(functions
         .command("dev <entrypoint>")
         .description("Run the local Browserbase Functions development server.")
         .option("--port <port>", "Port to listen on.", "14113")
-        .option("--host <host>", "Host to bind to.", "127.0.0.1"), { includeProjectId: true, includeVerbose: true }).action(async (entrypoint, options) => {
+        .option("--host <host>", "Host to bind to.", "127.0.0.1"), { includeProjectId: true, includeVerbose: true }), [
+        "bb functions dev index.ts",
+        "bb functions dev index.ts --port 3000 --verbose",
+    ]).action(async (entrypoint, options) => {
         await startFunctionsDevServer({
             entrypoint,
             port: Number(options.port ?? "14113"),
@@ -40,10 +45,13 @@ export function attachFunctionsCommand(program) {
             verbose: options.verbose ?? false,
         });
     });
-    addFunctionsApiOptions(functions
+    addExamples(addFunctionsApiOptions(functions
         .command("publish <entrypoint>")
         .description("Package and upload a Browserbase Function build.")
-        .option("--dry-run", "Show what would be published without uploading."), { includeProjectId: true }).action(async (entrypoint, options) => {
+        .option("--dry-run", "Show what would be published without uploading."), { includeProjectId: true }), [
+        "bb functions publish index.ts --dry-run",
+        "bb functions publish index.ts",
+    ]).action(async (entrypoint, options) => {
         await publishFunction({
             entrypoint,
             apiKey: options.apiKey,
@@ -52,12 +60,16 @@ export function attachFunctionsCommand(program) {
             dryRun: options.dryRun ?? false,
         });
     });
-    addFunctionsApiOptions(functions
+    addExamples(addFunctionsApiOptions(functions
         .command("invoke [functionId]")
         .description("Invoke a deployed Browserbase Function or check invocation status.")
         .option("--params <params>", "JSON params to pass to the function.")
         .option("--no-wait", "Return immediately after creating the invocation.")
-        .option("--check-status <checkStatus>", "Invocation ID to inspect without creating a new invocation.")).action(async (functionId, options) => {
+        .option("--check-status <checkStatus>", "Invocation ID to inspect without creating a new invocation.")), [
+        `bb functions invoke <function-id> --params '{"url":"https://example.com"}'`,
+        "bb functions invoke <function-id> --no-wait",
+        "bb functions invoke --check-status <invocation-id>",
+    ]).action(async (functionId, options) => {
         await invokeFunction({
             functionId,
             params: options.params,

package/dist/commands/projects.js

@@ -1,4 +1,4 @@
-import { addCommonApiOptions, createBrowserbaseClient, outputJson } from "../lib/command.js";
+import { addCommonApiOptions, addExamples, createBrowserbaseClient, outputJson } from "../lib/command.js";
 export function attachProjectsCommand(program) {
     const projects = program
         .command("projects")
@@ -7,21 +7,21 @@ export function attachProjectsCommand(program) {
     projects.action(() => {
         projects.outputHelp();
     });
-    addCommonApiOptions(projects
+    addExamples(addCommonApiOptions(projects
         .command("list")
-        .description("List projects visible to the current API key.")).action(async (options) => {
+        .description("List projects visible to the current API key.")), ["bb projects list"]).action(async (options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.projects.list());
     });
-    addCommonApiOptions(projects
+    addExamples(addCommonApiOptions(projects
         .command("get <id>")
-        .description("Get a project by ID.")).action(async (id, options) => {
+        .description("Get a project by ID.")), ["bb projects get <project-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.projects.retrieve(id));
     });
-    addCommonApiOptions(projects
+    addExamples(addCommonApiOptions(projects
         .command("usage <id>")
-        .description("Get project usage.")).action(async (id, options) => {
+        .description("Get project usage.")), ["bb projects usage <project-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.projects.usage(id));
     });

package/dist/commands/search.js

@@ -1,10 +1,14 @@
-import { addCommonApiOptions, outputJson, requestBrowserbaseJson, writeOutputFile, } from "../lib/command.js";
+import { addCommonApiOptions, addExamples, outputJson, requestBrowserbaseJson, writeOutputFile, } from "../lib/command.js";
 export function attachSearchCommand(program) {
-    addCommonApiOptions(program
+    addExamples(addCommonApiOptions(program
         .command("search <query>")
         .description("Search the web using the Browserbase Search API.")
         .option("--num-results <count>", "Number of results to return (1-25, default 10).")
-        .option("--output <output>", "Write the search results as JSON to a file.")).action(async (query, options) => {
+        .option("--output <output>", "Write the search results as JSON to a file.")), [
+        `bb search "best restaurants in SF"`,
+        `bb search "web scraping tools" --num-results 5`,
+        `bb search "browserbase docs" --output results.json`,
+    ]).action(async (query, options) => {
         const numResults = options.numResults ? parseInt(options.numResults, 10) : undefined;
         const result = await requestBrowserbaseJson(options, "/v1/search", {
             method: "POST",

package/dist/commands/sessions.js

@@ -1,5 +1,5 @@
 import { Option } from "commander";
-import { addCommonApiOptions, createBrowserbaseClient, fail, outputJson, parseOptionalJsonObjectArg, resolveUploadableFile, writeBinaryOutput, } from "../lib/command.js";
+import { addCommonApiOptions, addExamples, createBrowserbaseClient, fail, outputJson, resolveBody, resolveUploadableFile, writeBinaryOutput, } from "../lib/command.js";
 export function attachSessionsCommand(program) {
     const sessions = program
         .command("sessions")
@@ -8,57 +8,69 @@ export function attachSessionsCommand(program) {
     sessions.action(() => {
         sessions.outputHelp();
     });
-    addCommonApiOptions(sessions
+    addExamples(addCommonApiOptions(sessions
         .command("list")
         .description("List sessions.")
-        .option("--q <q>", `Session metadata query (e.g. "user_metadata['env']:'staging'").`)).action(async (options) => {
+        .option("--q <q>", `Session metadata query (e.g. "user_metadata['env']:'staging'").`)), [
+        "bb sessions list",
+        `bb sessions list --q "user_metadata['env']:'staging'"`,
+    ]).action(async (options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.sessions.list(options.q ? { q: options.q } : {}));
     });
-    addCommonApiOptions(sessions
+    addExamples(addCommonApiOptions(sessions
         .command("get <id>")
-        .description("Get a session by ID.")).action(async (id, options) => {
+        .description("Get a session by ID.")), ["bb sessions get <session-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.sessions.retrieve(id));
     });
-    addCommonApiOptions(sessions
+    addExamples(addCommonApiOptions(sessions
         .command("create")
         .description("Create a session.")
-        .option("--body <body>", "Optional JSON request body.")).action(async (options) => {
+        .option("--body <body>", "Optional JSON request body.")
+        .option("--stdin", "Read JSON request body from stdin.")), [
+        "bb sessions create",
+        `bb sessions create --body '{"proxies":true}'`,
+        `echo '{"proxies":true}' | bb sessions create --stdin`,
+    ]).action(async (options) => {
         const client = createBrowserbaseClient(options);
-        const body = parseOptionalJsonObjectArg(options.body, "body");
+        const body = await resolveBody(options);
         outputJson(await client.sessions.create(body));
     });
-    addCommonApiOptions(sessions
+    addExamples(addCommonApiOptions(sessions
         .command("update <id>")
         .description("Update a session.")
         .addOption(new Option("--status <status>", "Session status update.")
         .choices(["REQUEST_RELEASE"])
         .default("REQUEST_RELEASE"))
-        .option("--body <body>", "Optional JSON request body. Merged with --status when provided.")).action(async (id, options) => {
+        .option("--body <body>", "Optional JSON request body. Merged with --status when provided.")
+        .option("--stdin", "Read JSON request body from stdin.")), [
+        "bb sessions update <session-id> --status REQUEST_RELEASE",
+        `bb sessions update <session-id> --body '{"status":"REQUEST_RELEASE"}'`,
+    ]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         const sessionId = id || fail("Session ID is required.");
         const body = {
-            ...parseOptionalJsonObjectArg(options.body, "body"),
+            ...(await resolveBody(options)),
             status: options.status ?? "REQUEST_RELEASE",
         };
         outputJson(await client.sessions.update(sessionId, body));
     });
-    addCommonApiOptions(sessions
+    addExamples(addCommonApiOptions(sessions
         .command("debug <id>")
-        .description("Get live debugger URLs for a session.")).action(async (id, options) => {
+        .description("Get live debugger URLs for a session.")), ["bb sessions debug <session-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.sessions.debug(id));
     });
-    addCommonApiOptions(sessions
+    addExamples(addCommonApiOptions(sessions
         .command("logs <id>")
-        .description("Get session logs.")).action(async (id, options) => {
+        .description("Get session logs.")), ["bb sessions logs <session-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.sessions.logs.list(id));
     });
-    addCommonApiOptions(sessions
+    addExamples(addCommonApiOptions(sessions
         .command("recording <id>")
-        .description("Get rrweb session recording events.")).action(async (id, options) => {
+        .description("Get rrweb session recording events.")), ["bb sessions recording <session-id>"]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.sessions.recording.retrieve(id));
     });
@@ -69,10 +81,13 @@ export function attachSessionsCommand(program) {
     downloads.action(() => {
         downloads.outputHelp();
     });
-    addCommonApiOptions(downloads
+    addExamples(addCommonApiOptions(downloads
         .command("get <id>")
         .description("Download session files as a ZIP archive.")
-        .option("--output <output>", "Path to write the ZIP file.")).action(async (id, options) => {
+        .option("--output <output>", "Path to write the ZIP file.")), [
+        "bb sessions downloads get <session-id>",
+        "bb sessions downloads get <session-id> --output ./downloads.zip",
+    ]).action(async (id, options) => {
         const client = createBrowserbaseClient(options);
         const response = await client.sessions.downloads.list(id);
         const defaultPath = `${id}-downloads.zip`;
@@ -88,9 +103,9 @@ export function attachSessionsCommand(program) {
     uploads.action(() => {
         uploads.outputHelp();
     });
-    addCommonApiOptions(uploads
+    addExamples(addCommonApiOptions(uploads
         .command("create <id> <file>")
-        .description("Upload a file to a session.")).action(async (id, file, options) => {
+        .description("Upload a file to a session.")), ["bb sessions uploads create <session-id> ./file.pdf"]).action(async (id, file, options) => {
         const client = createBrowserbaseClient(options);
         outputJson(await client.sessions.uploads.create(id, {
             file: await resolveUploadableFile(file, "session upload"),

package/dist/commands/skills.js

@@ -25,7 +25,15 @@ export function attachSkillsCommand(program) {
     const skills = program
         .command("skills")
         .description("Install Browserbase agent skills for Claude Code.")
-        .action(async () => {
+        .option("-y, --yes", "Auto-accept installation prompts.")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  bb skills              (interactive install prompt)",
+        "  bb skills --yes        (auto-install without prompting)",
+        "  bb skills install      (non-interactive install)",
+    ].join("\n"))
+        .action(async (options) => {
         console.log([
             "",
             "Browserbase Skills for Claude Code",
@@ -38,18 +46,23 @@ export function attachSkillsCommand(program) {
             "  Run:    npx skills add browserbase/skills --yes --global",
             "",
         ].join("\n"));
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-        });
-        try {
-            const answer = await rl.question("Install skills? [Y/n] ");
-            if (answer.trim().toLowerCase() === "n") {
-                return;
+        if (!options.yes) {
+            if (!process.stdin.isTTY) {
+                fail("Cannot prompt for install in non-interactive mode. Use --yes to auto-install.");
+            }
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            try {
+                const answer = await rl.question("Install skills? [Y/n] ");
+                if (answer.trim().toLowerCase() === "n") {
+                    return;
+                }
+            }
+            finally {
+                rl.close();
             }
-        }
-        finally {
-            rl.close();
         }
         await installSkills();
     });

package/dist/lib/command.js

@@ -2,6 +2,7 @@ import Browserbase from "@browserbasehq/sdk";
 import { createReadStream, constants } from "node:fs";
 import { access, mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { Readable } from "node:stream";
 const defaultBrowserbaseApiUrl = "https://api.browserbase.com";
 export class CommandFailure extends Error {
     exitCode;
@@ -151,3 +152,27 @@ export async function writeBinaryOutput(pathname, contents) {
     await mkdir(dirname(absolutePath), { recursive: true });
     await writeFile(absolutePath, contents);
 }
+export function addExamples(command, examples) {
+    const text = "\nExamples:\n" + examples.map((e) => `  ${e}`).join("\n");
+    return command.addHelpText("after", text);
+}
+export async function readStdin() {
+    if (process.stdin.isTTY) {
+        fail("--stdin requires piped input. Example: echo '{\"key\":\"value\"}' | bb <command> --stdin");
+    }
+    const chunks = [];
+    for await (const chunk of Readable.toWeb(process.stdin)) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+export async function resolveBody(options) {
+    if (options.body && options.stdin) {
+        fail("Cannot use both --body and --stdin. Provide one or the other.");
+    }
+    if (options.stdin) {
+        const input = await readStdin();
+        return parseOptionalJsonObjectArg(input, "stdin");
+    }
+    return parseOptionalJsonObjectArg(options.body, "body");
+}

package/package.json

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