browse 0.9.3 → 0.9.5

package/README.md

@@ -33,7 +33,7 @@ npm install -g browse
 npm install -g browse
 
 browse open https://example.com
-browse snapshot --compact
+browse snapshot
 browse click @0-12
 browse fill @0-8 "hello"
 browse get title
@@ -89,8 +89,8 @@ browse forward        # Navigate forward
 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                 # Accessibility tree + cached refs (lean by default)
+browse snapshot --full          # Also include the ref maps (xpathMap, urlMap)
 browse snapshot --filter submit # Filter lines by text or /regex/, keeping ancestors
 browse snapshot --max-depth 4   # Trim output deeper than this depth
 ```

package/dist/commands/skills/show.js

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { BrowseCommand } from "../../base.js";
+import { fail } from "../../lib/errors.js";
+import { bundledCliSkillPath } from "../../lib/skills/install.js";
+export default class SkillsShow extends BrowseCommand {
+    static description = "Print the bundled browse skill (usage patterns, workflows, gotchas) to stdout. Run before using browse in an agent.";
+    static examples = ["browse skills show"];
+    async run() {
+        const skillMdPath = join(bundledCliSkillPath(), "SKILL.md");
+        let contents;
+        try {
+            contents = await readFile(skillMdPath, "utf8");
+        }
+        catch (error) {
+            fail(`Could not read the bundled browse skill (SKILL.md): ${error.message}`, 1, { resultCode: "skill_show_missing" });
+        }
+        this.log(contents);
+    }
+}

package/dist/commands/snapshot.js

@@ -2,17 +2,20 @@ import { Flags } from "@oclif/core";
 import { BrowseCommand } from "../base.js";
 import { driverCommandFlags, runDriverCommandFromFlags, } from "../lib/driver/command-cli.js";
 export default class Snapshot extends BrowseCommand {
-    static description = "Print the active page accessibility snapshot and cache refs for element commands.";
+    static description = "Print the active page accessibility snapshot and cache refs for element commands. Pass --full to also include the ref maps (xpathMap, urlMap).";
     static examples = [
         "browse snapshot",
-        "browse snapshot --compact",
+        "browse snapshot --full",
         "browse snapshot --filter submit",
         "browse snapshot --max-depth 4",
     ];
     static flags = {
         ...driverCommandFlags,
+        full: Flags.boolean({
+            description: "Also include the ref maps (xpathMap, urlMap).",
+        }),
         compact: Flags.boolean({
-            description: "Print only the formatted tree, without ref maps.",
+            description: "Deprecated and has no effect; use --full to include the ref maps.",
         }),
         filter: Flags.string({
             description: "Filter output lines by text or /regex/ while preserving matching ancestors.",
@@ -25,8 +28,11 @@ export default class Snapshot extends BrowseCommand {
     };
     async run() {
         const { flags } = await this.parse(Snapshot);
+        if (flags.compact && process.stderr.isTTY) {
+            this.warn("`--compact` is deprecated and has no effect; use `--full` to include the ref maps.");
+        }
         await runDriverCommandFromFlags("snapshot", {
-            compact: flags.compact,
+            full: flags.full,
             filter: flags.filter,
             maxDepth: flags["max-depth"],
         }, flags);

package/dist/help.js

@@ -0,0 +1,19 @@
+import { Help } from "@oclif/core";
+// Custom root-help formatter so `browse --help` (and bare `browse`) lead with
+// a short block pointing agents at the bundled skill, ahead of oclif's
+// auto-generated VERSION/USAGE/DESCRIPTION/COMMANDS sections. Only the root
+// help view is customized -- individual `browse <command> --help` views are
+// unaffected.
+const AGENT_HEADER = `Start here (for AI agents):
+  browse skills show
+
+  The bundled skill ships with the CLI (always version-matched) and covers
+  workflows, session management, and common failure recovery. Prefer it over
+  guessing commands from flag docs alone.
+`;
+export default class BrowseHelp extends Help {
+    async showRootHelp() {
+        this.log(AGENT_HEADER);
+        await super.showRootHelp();
+    }
+}

package/dist/lib/driver/commands/snapshot.js

@@ -2,9 +2,9 @@ import { z } from "zod";
 import { formatSnapshotTree } from "./snapshot-format.js";
 export const snapshotHandlers = {
     async snapshot(manager, params) {
-        const { compact, filter, maxDepth } = z
+        const { full, filter, maxDepth } = z
             .object({
-            compact: z.boolean().optional(),
+            full: z.boolean().optional(),
             filter: z.string().optional(),
             maxDepth: z.number().int().nonnegative().optional(),
         })
@@ -16,17 +16,16 @@ export const snapshotHandlers = {
             xpathMap: snapshot.xpathMap ?? {},
         });
         const tree = formatSnapshotTree(snapshot.formattedTree, {
-            compact,
             filter,
             maxDepth,
         });
-        if (compact) {
-            return { tree };
+        if (full) {
+            return {
+                tree,
+                urlMap: snapshot.urlMap,
+                xpathMap: snapshot.xpathMap,
+            };
         }
-        return {
-            tree,
-            urlMap: snapshot.urlMap,
-            xpathMap: snapshot.xpathMap,
-        };
+        return { tree };
     },
 };

package/dist/lib/skills/install.js

@@ -167,7 +167,7 @@ function localSkillPath(skillId) {
     const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
     return join(configHome, "browserbase", "skills", skillId.domain, skillId.task);
 }
-function bundledCliSkillPath() {
+export function bundledCliSkillPath() {
     return join(packageRoot(), "skills", "browse");
 }
 function packageRoot() {

package/oclif.manifest.json

@@ -2093,10 +2093,10 @@
     "snapshot": {
       "aliases": [],
       "args": {},
-      "description": "Print the active page accessibility snapshot and cache refs for element commands.",
+      "description": "Print the active page accessibility snapshot and cache refs for element commands. Pass --full to also include the ref maps (xpathMap, urlMap).",
       "examples": [
         "browse snapshot",
-        "browse snapshot --compact",
+        "browse snapshot --full",
         "browse snapshot --filter submit",
         "browse snapshot --max-depth 4"
       ],
@@ -2190,8 +2190,14 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "full": {
+          "description": "Also include the ref maps (xpathMap, urlMap).",
+          "name": "full",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "compact": {
-          "description": "Print only the formatted tree, without ref maps.",
+          "description": "Deprecated and has no effect; use --full to include the ref maps.",
           "name": "compact",
           "allowNo": false,
           "type": "boolean"
@@ -4530,6 +4536,29 @@
         "list.js"
       ]
     },
+    "skills:show": {
+      "aliases": [],
+      "args": {},
+      "description": "Print the bundled browse skill (usage patterns, workflows, gotchas) to stdout. Run before using browse in an agent.",
+      "examples": [
+        "browse skills show"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "skills:show",
+      "pluginAlias": "browse",
+      "pluginName": "browse",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "skills",
+        "show.js"
+      ]
+    },
     "tab:close": {
       "aliases": [],
       "args": {
@@ -6392,5 +6421,5 @@
       ]
     }
   },
-  "version": "0.9.3"
+  "version": "0.9.5"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,
@@ -24,6 +24,7 @@
     "bin": "browse",
     "dirname": "browse",
     "commands": "./dist/commands",
+    "helpClass": "./dist/help.js",
     "hooks": {
       "init": "./dist/hooks/init.js",
       "prerun": "./dist/hooks/prerun.js",

package/skills/browse/SKILL.md

@@ -65,12 +65,16 @@ browse open https://example.com --cdp ws://127.0.0.1:9222/devtools/browser/<id>
 
 Use local mode for development, localhost, trusted sites, and fast iteration. Use `--auto-connect` only when the user explicitly wants to attach to an already-running debuggable Chrome session with existing cookies or login state; use `--local` when no debuggable Chrome is available. Use remote mode when Browserbase credentials are available and the site needs hosted browser infrastructure, Verified browser mode, CAPTCHA solving, proxies, or session persistence.
 
+`--local` requires Chrome or Chromium already installed on the machine. In containers, CI, and sandboxes with no browser installed, use `--remote` instead of `--local`. If `--local` fails with "No Chrome or Chromium found" and `BROWSERBASE_API_KEY` is set, switch to `--remote` — do not retry `--local`.
+
 For a Verified and/or proxied remote session, add `--verified` and/or `--proxies` to `--remote` — a single command that keeps the Browserbase session identity, so `browse status` and `browse doctor` report the session ID and live-view URL. `--verified` requires a Browserbase Scale plan. These flags only apply to `--remote` and are sticky for the session's lifetime, like `--headed`. Reach for `browse cloud sessions create` + `--cdp` only when you need session options `open` doesn't expose (region, keep-alive, contexts).
 
 Choose headed/headless and local/remote mode when starting a session. A running session keeps its mode: passing a conflicting flag such as `--headed` to an already-running headless session fails until you run `browse stop --session <name>` or target a different session.
 
 Use named sessions for any non-trivial work, especially when multiple agents or parallel tasks may run at once. Every browser command accepts `--session <name>` (or `-s <name>`); the `BROWSE_SESSION` env var sets the default, and commands without either share the `default` session.
 
+If `BROWSE_SESSION` is already set in the environment, every command already targets that session — do not pass `--session` or invent a new name. An explicit `--session <name>` always overrides `BROWSE_SESSION` for that command, so only pass it to deliberately target a different session.
+
 ```bash
 browse open https://example.com --session research --local
 browse snapshot --session research
@@ -132,8 +136,8 @@ browse wait selector "#result"
 Page state:
 
 ```bash
-browse snapshot
-browse snapshot --compact
+browse snapshot                            # formatted tree only
+browse snapshot --full                     # also include ref maps (xpathMap, urlMap)
 browse get url
 browse get title
 browse get text body