browse 0.8.3 → 0.8.4

package/README.md

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

package/dist/commands/skills/add.js

@@ -1,5 +1,6 @@
 import { Args } from "@oclif/core";
 import { BrowseCommand } from "../../base.js";
+import { fail } from "../../lib/errors.js";
 import { installSkill } from "../../lib/skills/install.js";
 export default class SkillsAdd extends BrowseCommand {
     static description = "Install a browser automation skill.";
@@ -8,16 +9,18 @@ export default class SkillsAdd extends BrowseCommand {
         "browse skills add mcdonalds.order.online/order-delivery-42q71n",
     ];
     static args = {
+        // Intentionally optional so we can emit actionable guidance instead of
+        // oclif's bare "Missing 1 required arg" error.
         skill: Args.string({
-            required: true,
+            required: false,
             description: "Skill id in the form <domain>/<task>.",
         }),
     };
     async run() {
         const { args } = await this.parse(SkillsAdd);
-        const exitCode = await installSkill(args.skill);
-        if (exitCode !== 0) {
-            this.exit(exitCode);
+        if (!args.skill) {
+            fail("Missing skill id. Pass a skill in the form <domain>/<task>, e.g. `browse skills add yelp.com/extract-reviews`. Run `browse skills find <query>` to discover skills.", 2, { resultCode: "invalid_skill_id" });
         }
+        await installSkill(args.skill);
     }
 }

package/dist/commands/skills/install.js

@@ -4,9 +4,6 @@ export default class SkillsInstall extends BrowseCommand {
     static description = "Install the bundled browse CLI skill.";
     static examples = ["browse skills install"];
     async run() {
-        const exitCode = await installBundledCliSkill();
-        if (exitCode !== 0) {
-            this.exit(exitCode);
-        }
+        await installBundledCliSkill();
     }
 }

package/dist/lib/skills/install.js

@@ -11,14 +11,19 @@ const generatedSkillSuffixPattern = /-[A-Za-z0-9]{6}$/;
 const domainPattern = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/;
 const taskPattern = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const maxSkillFiles = 100;
+const maxCapturedOutputBytes = 2048;
 export function parseSkillId(rawSkillId) {
     const parts = rawSkillId.split("/");
     if (parts.length !== 2) {
-        fail("Skill must be in the form <domain>/<task>.");
+        fail("Skill must be in the form <domain>/<task>.", 1, {
+            resultCode: "invalid_skill_id",
+        });
     }
     const [domain, task] = parts;
     if (!domain || !task) {
-        fail("Skill must be in the form <domain>/<task>.");
+        fail("Skill must be in the form <domain>/<task>.", 1, {
+            resultCode: "invalid_skill_id",
+        });
     }
     if (rawSkillId.includes("\\") ||
         domain === "." ||
@@ -27,7 +32,9 @@ export function parseSkillId(rawSkillId) {
         task === ".." ||
         !domainPattern.test(domain) ||
         !taskPattern.test(task)) {
-        fail(`Invalid skill id "${rawSkillId}". Use <domain>/<task>.`);
+        fail(`Invalid skill id "${rawSkillId}". Use <domain>/<task>.`, 1, {
+            resultCode: "invalid_skill_id",
+        });
     }
     return {
         domain,
@@ -42,20 +49,26 @@ export async function installSkill(rawSkillId) {
     const skillId = parseSkillId(rawSkillId);
     const npxPath = await findExecutable("npx");
     if (!npxPath) {
-        fail("`npx` is not installed. Install Node.js from https://nodejs.org, then rerun `browse skills add`.");
+        fail("`npx` is not installed. Install Node.js from https://nodejs.org, then rerun `browse skills add`.", 1, { resultCode: "npx_missing" });
     }
     const files = await fetchSkillFiles(skillId);
-    if (files) {
-        const result = await downloadBlobSkill(skillId, files);
+    if (files.status === "found") {
+        const result = await downloadBlobSkill(skillId, files.files);
         process.stdout.write(`Downloaded ${result.fileCount} skill file${result.fileCount === 1 ? "" : "s"} to ${result.installPath}\n`);
-        return await spawnPassthrough(npxPath, [
+        await runSkillsInstall(npxPath, [
             "--yes",
             "skills",
             "add",
             result.installPath,
         ]);
+        return;
+    }
+    if (files.status === "not_found") {
+        fail(`Skill "${skillId.id}" not found in the catalog. Run \`browse skills find ${skillId.domain}\` to discover available skills, or \`browse skills list\` to browse them.`, 1, { resultCode: "skill_not_found" });
     }
-    return await spawnPassthrough(npxPath, [
+    // Suffix-shaped (generated) ids, or a temporarily unavailable catalog, may
+    // still resolve through the browse.sh GitHub repo.
+    await runSkillsInstall(npxPath, [
         "--yes",
         "skills",
         "add",
@@ -67,9 +80,9 @@ export async function installSkill(rawSkillId) {
 export async function installBundledCliSkill() {
     const npxPath = await findExecutable("npx");
     if (!npxPath) {
-        fail("`npx` is not installed. Install Node.js from https://nodejs.org, then rerun `browse skills install`.");
+        fail("`npx` is not installed. Install Node.js from https://nodejs.org, then rerun `browse skills install`.", 1, { resultCode: "npx_missing" });
     }
-    return await spawnPassthrough(npxPath, [
+    await runSkillsInstall(npxPath, [
         "--yes",
         "skills",
         "add",
@@ -80,10 +93,30 @@ export async function installBundledCliSkill() {
         "*",
     ]);
 }
+// Runs `npx skills add ...` with live passthrough, but fails with a diagnostic
+// message (including a tail of the child's output) when the child exits nonzero
+// so the failure is recorded in telemetry instead of an opaque exit code.
+async function runSkillsInstall(npxPath, args) {
+    const result = await spawnPassthrough(npxPath, args);
+    if (result.exitCode === 0) {
+        return;
+    }
+    const detail = result.output.trim();
+    const reason = detail
+        ? `: ${detail}`
+        : " (see the output above for details).";
+    fail(`Could not install skill${reason}`, result.exitCode || 1, {
+        resultCode: "skill_install_failed",
+    });
+}
 export async function downloadBlobSkill(skillId, files) {
-    const filesToDownload = files ?? (await fetchSkillFiles(skillId));
+    let filesToDownload = files;
     if (!filesToDownload) {
-        fail(`Skill ${skillId.id} was not found as a generated skill.`);
+        const resolved = await fetchSkillFiles(skillId);
+        if (resolved.status !== "found") {
+            fail(`Skill ${skillId.id} was not found as a generated skill.`);
+        }
+        filesToDownload = resolved.files;
     }
     const installPath = localSkillPath(skillId);
     const parentDir = dirname(installPath);
@@ -121,19 +154,29 @@ function packageRoot() {
 async function fetchSkillFiles(skillId) {
     const apiResult = await fetchSkillFilesFromApi(skillId);
     if (apiResult.status === "found") {
-        return apiResult.files;
+        return { status: "found", files: apiResult.files };
     }
     if (apiResult.status === "unavailable" &&
         isBlobSkillId(skillId) &&
         (await directBlobSkillExists(skillId))) {
-        return [
-            {
-                path: "SKILL.md",
-                url: skillBlobUrl(skillId, "SKILL.md"),
-            },
-        ];
+        return {
+            status: "found",
+            files: [
+                {
+                    path: "SKILL.md",
+                    url: skillBlobUrl(skillId, "SKILL.md"),
+                },
+            ],
+        };
+    }
+    // Suffix-shaped ids correspond to generated catalog skills that live in the
+    // browse.sh repo even when the file API can't serve them directly, so keep
+    // the GitHub clone fallback for those. A plain 404 for a non-generated id is
+    // a definitive miss and should fail cleanly instead of cloning the repo.
+    if (apiResult.status === "not_found" && !isBlobSkillId(skillId)) {
+        return { status: "not_found" };
     }
-    return null;
+    return { status: "fallback" };
 }
 async function fetchSkillFilesFromApi(skillId) {
     const url = skillFilesApiUrl(skillId);
@@ -298,19 +341,45 @@ async function findExecutable(command) {
     }
     return null;
 }
+// Like `stdio: "inherit"` for the human watching, but the child's stdout/stderr
+// are also buffered (tail only) so a nonzero exit can surface a real reason to
+// telemetry instead of a bare exit code.
 async function spawnPassthrough(command, args) {
-    return await new Promise((resolvePromise, reject) => {
+    return await new Promise((resolvePromise) => {
         const child = spawn(command, args, {
-            stdio: "inherit",
+            stdio: ["inherit", "pipe", "pipe"],
             shell: shouldUseWindowsShell(command),
         });
-        child.on("error", reject);
-        child.on("close", (exitCode, signal) => {
-            if (signal) {
-                resolvePromise(1);
-                return;
+        let captured = "";
+        const capture = (chunk) => {
+            captured += chunk.toString();
+            if (captured.length > maxCapturedOutputBytes) {
+                captured = captured.slice(-maxCapturedOutputBytes);
             }
-            resolvePromise(exitCode ?? 0);
+        };
+        child.stdout?.on("data", (chunk) => {
+            process.stdout.write(chunk);
+            capture(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+            capture(chunk);
+        });
+        // Resolve (not reject) on spawn errors so the failure is classified as
+        // `skill_install_failed` by runSkillsInstall instead of escaping as an
+        // unclassified runtime error.
+        child.on("error", (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            resolvePromise({
+                exitCode: 1,
+                output: captured ? `${captured}\n${message}` : message,
+            });
+        });
+        child.on("close", (exitCode, signal) => {
+            resolvePromise({
+                exitCode: signal ? 1 : (exitCode ?? 0),
+                output: captured,
+            });
         });
     });
 }

package/dist/lib/templates/api.js

@@ -1,7 +1,11 @@
 import { fail } from "../errors.js";
 const defaultTemplatesApiUrl = "https://www.browserbase.com/api/templates";
 export async function listTemplates(options = {}) {
-    const payload = await requestTemplatesJson(templatesApiUrl(undefined, options));
+    const payload = await requestTemplatesJson(
+    // The CLI always requests the full template catalog. The templates API defaults to
+    // returning only `playgroundRunnable` templates — a website-playground concept that
+    // does not apply to the CLI — so we always opt out via `scope=all`.
+    templatesApiUrl(undefined, { ...options, scope: "all" }));
     return parseTemplatesResponse(payload);
 }
 export async function getTemplate(slug) {

package/oclif.manifest.json

@@ -3459,7 +3459,7 @@
         "skill": {
           "description": "Skill id in the form <domain>/<task>.",
           "name": "skill",
-          "required": true
+          "required": false
         }
       },
       "description": "Install a browser automation skill.",
@@ -5266,5 +5266,5 @@
       ]
     }
   },
-  "version": "0.8.3"
+  "version": "0.8.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,

package/skills/browse/SKILL.md

@@ -109,6 +109,8 @@ browse get title
 browse get text body
 browse get html "#main"
 browse get value "#email"
+browse get markdown body                   # page/element content as markdown
+browse eval "document.title"              # run JavaScript in the active page
 browse screenshot                         # print base64 JSON
 browse screenshot --path page.png
 ```
@@ -134,6 +136,7 @@ browse mouse hover 240 320
 browse mouse drag 80 80 310 100
 browse mouse scroll 500 300 0 600
 browse viewport 1280 720
+browse cursor                             # show a visible cursor overlay
 ```
 
 Tabs, network, and CDP:
@@ -144,6 +147,7 @@ browse tab new https://example.com
 browse tab switch <target-id>
 browse tab close <target-id>              # refuses to close the last tab
 browse network on
+browse network off
 browse network path
 browse network clear
 browse cdp 9222 --pretty