@browserbasehq/cli 0.0.1

package/README.md

@@ -0,0 +1,20 @@
+# Browserbase CLI
+
+Browserbase's Bun-native development repo for the `bb` CLI.
+
+## Development
+
+```bash
+bun install
+bun run check
+bun run cli -- --help
+```
+
+## Build
+
+```bash
+bun run build
+```
+
+The published artifact is Node-compatible JavaScript in `dist/`, even though local
+development stays Bun-native.

package/dist/cli.js

@@ -0,0 +1,54 @@
+import { Command, CommanderError } from "commander";
+import { attachBrowseCommand } from "./commands/browse.js";
+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";
+import { attachProjectsCommand } from "./commands/projects.js";
+import { attachSessionsCommand } from "./commands/sessions.js";
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name("bb")
+        .description("Browserbase CLI for platform APIs, functions, and browse passthrough.")
+        .version("0.1.0")
+        .helpCommand(false)
+        .showHelpAfterError()
+        .showSuggestionAfterError()
+        .enablePositionalOptions()
+        .exitOverride();
+    attachDashboardCommand(program);
+    attachBrowseCommand(program);
+    attachFunctionsCommand(program);
+    attachSessionsCommand(program);
+    attachProjectsCommand(program);
+    attachContextsCommand(program);
+    attachExtensionsCommand(program);
+    attachFetchCommand(program);
+    return program;
+}
+export async function run(argv) {
+    const program = buildProgram();
+    process.exitCode = 0;
+    if (argv.length === 0) {
+        program.outputHelp();
+        return 0;
+    }
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return process.exitCode ?? 0;
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            const commanderError = error;
+            if (commanderError.code === "commander.helpDisplayed" ||
+                commanderError.code === "commander.version") {
+                return 0;
+            }
+            return commanderError.exitCode;
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        return error?.exitCode ?? 1;
+    }
+}

package/dist/commands/browse.js

@@ -0,0 +1,27 @@
+import { fail } from "../lib/command.js";
+import { findExecutable, spawnPassthrough } from "../lib/process.js";
+export function attachBrowseCommand(program) {
+    program
+        .command("browse")
+        .description("Forward commands to the standalone @browserbasehq/browse-cli binary.")
+        .argument("[args...]", "Arguments to forward to browse")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .passThroughOptions()
+        .action(async (args) => {
+        const browsePath = await findExecutable("browse");
+        if (!browsePath) {
+            fail([
+                "`browse` is not installed.",
+                "Install it with:",
+                "npm install -g @browserbasehq/browse-cli",
+                "",
+                "Then rerun your `bb browse ...` command.",
+            ].join("\n"));
+        }
+        const exitCode = await spawnPassthrough(browsePath, args ?? []);
+        if (exitCode !== 0) {
+            process.exitCode = exitCode;
+        }
+    });
+}

package/dist/commands/contexts.js

@@ -0,0 +1,42 @@
+import { addCommonApiOptions, createBrowserbaseClient, mergeProjectIdIntoBody, outputJson, parseOptionalJsonObjectArg, requestBrowserbase, requestBrowserbaseJson, resolveProjectId, } from "../lib/command.js";
+export function attachContextsCommand(program) {
+    const contexts = program
+        .command("contexts")
+        .description("Create, inspect, update, and delete Browserbase contexts.")
+        .helpCommand(false);
+    contexts.action(() => {
+        contexts.outputHelp();
+    });
+    addCommonApiOptions(contexts
+        .command("create")
+        .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"));
+        outputJson(await client.contexts.create(body));
+    });
+    addCommonApiOptions(contexts
+        .command("get <id>")
+        .description("Get a context by ID.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.contexts.retrieve(id));
+    });
+    addCommonApiOptions(contexts
+        .command("update <id>")
+        .description("Refresh the upload URL for a context.")).action(async (id, options) => {
+        outputJson(await requestBrowserbaseJson(options, `/v1/contexts/${id}`, {
+            method: "PUT",
+        }));
+    });
+    addCommonApiOptions(contexts
+        .command("delete <id>")
+        .description("Delete a context.")).action(async (id, options) => {
+        await requestBrowserbase(options, `/v1/contexts/${id}`, {
+            method: "DELETE",
+            headers: {
+                Accept: "*/*",
+            },
+        });
+        outputJson({ ok: true, id });
+    });
+}

package/dist/commands/dashboard.js

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

package/dist/commands/extensions.js

@@ -0,0 +1,35 @@
+import { addCommonApiOptions, createBrowserbaseClient, outputJson, requestBrowserbase, resolveUploadableFile, } from "../lib/command.js";
+export function attachExtensionsCommand(program) {
+    const extensions = program
+        .command("extensions")
+        .description("Upload and manage Browserbase extensions.")
+        .helpCommand(false);
+    extensions.action(() => {
+        extensions.outputHelp();
+    });
+    addCommonApiOptions(extensions
+        .command("upload <file>")
+        .description("Upload an extension ZIP file.")).action(async (file, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.extensions.create({
+            file: await resolveUploadableFile(file, "extension"),
+        }));
+    });
+    addCommonApiOptions(extensions
+        .command("get <id>")
+        .description("Get an extension by ID.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.extensions.retrieve(id));
+    });
+    addCommonApiOptions(extensions
+        .command("delete <id>")
+        .description("Delete an extension.")).action(async (id, options) => {
+        await requestBrowserbase(options, `/v1/extensions/${id}`, {
+            method: "DELETE",
+            headers: {
+                Accept: "*/*",
+            },
+        });
+        outputJson({ ok: true, id });
+    });
+}

package/dist/commands/fetch.js

@@ -0,0 +1,35 @@
+import { addCommonApiOptions, createBrowserbaseClient, outputJson, writeOutputFile, } from "../lib/command.js";
+export function attachFetchCommand(program) {
+    addCommonApiOptions(program
+        .command("fetch <url>")
+        .description("Fetch a page with the 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) => {
+        const client = createBrowserbaseClient(options);
+        const result = await client.fetchAPI.create({
+            url,
+            allowInsecureSsl: options.allowInsecureSsl,
+            allowRedirects: options.allowRedirects,
+            proxies: options.proxies,
+        });
+        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}`);
+            return;
+        }
+        if (options.json) {
+            outputJson(result);
+            return;
+        }
+        process.stdout.write(result.content);
+        if (!result.content.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+    });
+}

package/dist/commands/functions.js

@@ -0,0 +1,70 @@
+import { Option } from "commander";
+import { 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";
+import { publishFunction } from "../lib/functions/publish.js";
+const packageManagers = ["npm", "pnpm"];
+export function attachFunctionsCommand(program) {
+    const functions = program
+        .command("functions")
+        .description("Develop, publish, and invoke Browserbase Functions.")
+        .helpCommand(false);
+    functions.action(() => {
+        functions.outputHelp();
+    });
+    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) => {
+        await initFunctionsProject({
+            projectName: projectName ?? "my-browserbase-function",
+            packageManager: options.packageManager ?? "pnpm",
+        });
+    });
+    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) => {
+        await startFunctionsDevServer({
+            entrypoint,
+            port: Number(options.port ?? "14113"),
+            host: options.host ?? "127.0.0.1",
+            apiKey: options.apiKey,
+            projectId: options.projectId,
+            apiUrl: options.apiUrl,
+            verbose: options.verbose ?? false,
+        });
+    });
+    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) => {
+        await publishFunction({
+            entrypoint,
+            apiKey: options.apiKey,
+            projectId: options.projectId,
+            apiUrl: options.apiUrl,
+            dryRun: options.dryRun ?? false,
+        });
+    });
+    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) => {
+        await invokeFunction({
+            functionId,
+            params: options.params,
+            apiKey: options.apiKey,
+            apiUrl: options.apiUrl,
+            noWait: options.wait === false,
+            checkStatus: options.checkStatus,
+        });
+    });
+}

package/dist/commands/projects.js

@@ -0,0 +1,28 @@
+import { addCommonApiOptions, createBrowserbaseClient, outputJson } from "../lib/command.js";
+export function attachProjectsCommand(program) {
+    const projects = program
+        .command("projects")
+        .description("List and inspect Browserbase projects.")
+        .helpCommand(false);
+    projects.action(() => {
+        projects.outputHelp();
+    });
+    addCommonApiOptions(projects
+        .command("list")
+        .description("List projects visible to the current API key.")).action(async (options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.projects.list());
+    });
+    addCommonApiOptions(projects
+        .command("get <id>")
+        .description("Get a project by ID.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.projects.retrieve(id));
+    });
+    addCommonApiOptions(projects
+        .command("usage <id>")
+        .description("Get project usage.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.projects.usage(id));
+    });
+}

package/dist/commands/sessions.js

@@ -0,0 +1,99 @@
+import { Option } from "commander";
+import { addCommonApiOptions, createBrowserbaseClient, fail, mergeProjectIdIntoBody, outputJson, parseOptionalJsonObjectArg, resolveProjectId, resolveUploadableFile, writeBinaryOutput, } from "../lib/command.js";
+export function attachSessionsCommand(program) {
+    const sessions = program
+        .command("sessions")
+        .description("Create, inspect, and manage Browserbase sessions.")
+        .helpCommand(false);
+    sessions.action(() => {
+        sessions.outputHelp();
+    });
+    addCommonApiOptions(sessions
+        .command("list")
+        .description("List sessions.")
+        .option("--q <q>", "Session metadata query.")).action(async (options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.sessions.list(options.q ? { q: options.q } : {}));
+    });
+    addCommonApiOptions(sessions
+        .command("get <id>")
+        .description("Get a session by ID.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.sessions.retrieve(id));
+    });
+    addCommonApiOptions(sessions
+        .command("create")
+        .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"));
+        outputJson(await client.sessions.create(body));
+    });
+    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) => {
+        const client = createBrowserbaseClient(options);
+        const sessionId = id || fail("Session ID is required.");
+        const body = mergeProjectIdIntoBody(resolveProjectId(options), {
+            ...parseOptionalJsonObjectArg(options.body, "body"),
+            status: options.status ?? "REQUEST_RELEASE",
+        });
+        outputJson(await client.sessions.update(sessionId, body));
+    });
+    addCommonApiOptions(sessions
+        .command("debug <id>")
+        .description("Get live debugger URLs for a session.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.sessions.debug(id));
+    });
+    addCommonApiOptions(sessions
+        .command("logs <id>")
+        .description("Get session logs.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.sessions.logs.list(id));
+    });
+    addCommonApiOptions(sessions
+        .command("recording <id>")
+        .description("Get rrweb session recording events.")).action(async (id, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.sessions.recording.retrieve(id));
+    });
+    const downloads = sessions
+        .command("downloads")
+        .description("Download session artifacts as a ZIP file.")
+        .helpCommand(false);
+    downloads.action(() => {
+        downloads.outputHelp();
+    });
+    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) => {
+        const client = createBrowserbaseClient(options);
+        const response = await client.sessions.downloads.list(id);
+        const defaultPath = `${id}-downloads.zip`;
+        const outputPath = options.output ?? defaultPath;
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        await writeBinaryOutput(outputPath, bytes);
+        outputJson({ ok: true, outputPath, sizeBytes: bytes.byteLength });
+    });
+    const uploads = sessions
+        .command("uploads")
+        .description("Upload files to a running session.")
+        .helpCommand(false);
+    uploads.action(() => {
+        uploads.outputHelp();
+    });
+    addCommonApiOptions(uploads
+        .command("create <id> <file>")
+        .description("Upload a file to a session.")).action(async (id, file, options) => {
+        const client = createBrowserbaseClient(options);
+        outputJson(await client.sessions.uploads.create(id, {
+            file: await resolveUploadableFile(file, "session upload"),
+        }));
+    });
+}

package/dist/lib/command.js

@@ -0,0 +1,162 @@
+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";
+const defaultBrowserbaseApiUrl = "https://api.browserbase.com";
+export class CommandFailure extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "CommandFailure";
+        this.exitCode = exitCode;
+    }
+}
+export function fail(message, exitCode = 1) {
+    throw new CommandFailure(message, exitCode);
+}
+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.");
+}
+export function addFunctionsApiOptions(command, options = {}) {
+    const { includeProjectId = false, includeVerbose = false } = options;
+    command
+        .option("--api-key <apiKey>", "Override the Browserbase API key.")
+        .option("--api-url <apiUrl>", "Override the Browserbase API base URL.");
+    if (includeProjectId) {
+        command.option("--project-id <projectId>", "Override the Browserbase project ID.");
+    }
+    if (includeVerbose) {
+        command.option("--verbose", "Print verbose server and runtime logs.");
+    }
+    return command;
+}
+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.");
+}
+export function resolveBaseUrl(args) {
+    return args.baseUrl ?? process.env.BROWSERBASE_BASE_URL;
+}
+export function resolveApiBaseUrl(args) {
+    return resolveBaseUrl(args) ?? defaultBrowserbaseApiUrl;
+}
+export function resolveProjectId(args, options = {}) {
+    const projectId = args.projectId ?? process.env.BROWSERBASE_PROJECT_ID;
+    if (options.required && !projectId) {
+        fail("Missing Browserbase project ID. Set BROWSERBASE_PROJECT_ID or pass --project-id.");
+    }
+    return projectId;
+}
+export function createBrowserbaseClient(args) {
+    return new Browserbase({
+        apiKey: resolveApiKey(args),
+        baseURL: resolveBaseUrl(args),
+    });
+}
+export function parseOptionalJsonObjectArg(rawValue, label) {
+    if (!rawValue) {
+        return {};
+    }
+    if (typeof rawValue !== "string") {
+        fail(`${label} must be provided as a JSON string.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawValue);
+    }
+    catch (error) {
+        fail(`Invalid JSON for ${label}: ${error.message}`);
+    }
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+        fail(`${label} must be a JSON object.`);
+    }
+    return parsed;
+}
+export function parseOptionalJsonValueArg(rawValue, label) {
+    if (!rawValue) {
+        return {};
+    }
+    if (typeof rawValue !== "string") {
+        fail(`${label} must be provided as a JSON string.`);
+    }
+    try {
+        return JSON.parse(rawValue);
+    }
+    catch (error) {
+        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));
+}
+export async function resolveUploadableFile(filePath, label) {
+    const absolutePath = resolve(filePath);
+    try {
+        await access(absolutePath, constants.R_OK);
+    }
+    catch {
+        fail(`Could not read ${label} file: ${absolutePath}`);
+    }
+    return createReadStream(absolutePath);
+}
+export async function readBrowserbaseError(response) {
+    try {
+        const data = await response.json();
+        if (typeof data === "object" && data !== null) {
+            const message = data.message || data.error;
+            if (message) {
+                return message;
+            }
+        }
+    }
+    catch {
+        try {
+            const text = await response.text();
+            if (text) {
+                return text;
+            }
+        }
+        catch {
+            return `${response.status} ${response.statusText}`;
+        }
+    }
+    return `${response.status} ${response.statusText}`;
+}
+export async function requestBrowserbase(args, pathname, init = {}) {
+    const response = await fetch(new URL(pathname, resolveApiBaseUrl(args)), {
+        ...init,
+        headers: {
+            "x-bb-api-key": resolveApiKey(args),
+            ...(init.headers ?? {}),
+        },
+    });
+    if (!response.ok) {
+        fail(await readBrowserbaseError(response));
+    }
+    return response;
+}
+export async function requestBrowserbaseJson(args, pathname, init = {}) {
+    const response = await requestBrowserbase(args, pathname, init);
+    return (await response.json());
+}
+export async function writeOutputFile(pathname, contents) {
+    const absolutePath = resolve(pathname);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, contents, "utf8");
+}
+export async function writeBinaryOutput(pathname, contents) {
+    const absolutePath = resolve(pathname);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, contents);
+}