From 24e63eae81e3389226f017b83bc94663ee488d01 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 30 Jul 2026 12:30:18 -0700 Subject: [PATCH 01/11] chore(cli): copy V3 package onto V4 spike --- packages/cli/.gitignore | 37 + packages/cli/.prettierignore | 14 + packages/cli/.prettierrc | 1 + packages/cli/CHANGELOG.md | 271 +++ packages/cli/Dockerfile | 10 + packages/cli/LICENSE | 21 + packages/cli/README.md | 302 ++++ packages/cli/bin/run.js | 36 + packages/cli/eslint.config.mjs | 66 + .../CleanShot_2026-06-05_at_13.12.432x.png | Bin 0 -> 338900 bytes .../CleanShot_2026-06-05_at_13.15.542x.png | Bin 0 -> 263331 bytes .../CleanShot_2026-06-05_at_13.17.012x.png | Bin 0 -> 548335 bytes .../CleanShot_2026-06-05_at_13.27.052x.png | Bin 0 -> 1328441 bytes .../guides/anthropic-managed-agents/README.md | 77 + .../anthropic-managed-agents/image3.png | Bin 0 -> 341026 bytes packages/cli/media/browse.gif | Bin 0 -> 3872031 bytes packages/cli/package.json | 136 ++ packages/cli/skills/browse/SKILL.md | 372 ++++ packages/cli/src/base.ts | 29 + packages/cli/src/commands/back.ts | 32 + packages/cli/src/commands/cdp.ts | 40 + packages/cli/src/commands/click.ts | 38 + .../cli/src/commands/cloud/contexts/add.ts | 60 + .../cli/src/commands/cloud/contexts/create.ts | 77 + .../cli/src/commands/cloud/contexts/delete.ts | 51 + .../cli/src/commands/cloud/contexts/get.ts | 37 + .../cli/src/commands/cloud/contexts/list.ts | 74 + .../cli/src/commands/cloud/contexts/update.ts | 34 + .../src/commands/cloud/extensions/delete.ts | 27 + .../cli/src/commands/cloud/extensions/get.ts | 28 + .../src/commands/cloud/extensions/upload.ts | 36 + packages/cli/src/commands/cloud/fetch.ts | 120 ++ .../cli/src/commands/cloud/projects/get.ts | 28 + .../cli/src/commands/cloud/projects/list.ts | 89 + .../cli/src/commands/cloud/projects/usage.ts | 28 + packages/cli/src/commands/cloud/search.ts | 159 ++ .../cli/src/commands/cloud/sessions/create.ts | 234 +++ .../cli/src/commands/cloud/sessions/debug.ts | 29 + .../commands/cloud/sessions/downloads/get.ts | 43 + .../cli/src/commands/cloud/sessions/get.ts | 28 + .../cli/src/commands/cloud/sessions/list.ts | 203 +++ .../cli/src/commands/cloud/sessions/logs.ts | 58 + .../cli/src/commands/cloud/sessions/update.ts | 52 + .../commands/cloud/sessions/uploads/create.ts | 39 + packages/cli/src/commands/cursor.ts | 24 + packages/cli/src/commands/daemon.ts | 30 + packages/cli/src/commands/doctor.ts | 47 + packages/cli/src/commands/eval.ts | 38 + packages/cli/src/commands/fill.ts | 49 + packages/cli/src/commands/forward.ts | 32 + packages/cli/src/commands/functions/dev.ts | 57 + packages/cli/src/commands/functions/init.ts | 39 + packages/cli/src/commands/functions/invoke.ts | 57 + .../cli/src/commands/functions/publish.ts | 45 + packages/cli/src/commands/get.ts | 58 + packages/cli/src/commands/highlight.ts | 43 + packages/cli/src/commands/is.ts | 43 + packages/cli/src/commands/mouse/click.ts | 54 + packages/cli/src/commands/mouse/drag.ts | 76 + packages/cli/src/commands/mouse/hover.ts | 45 + packages/cli/src/commands/mouse/scroll.ts | 55 + packages/cli/src/commands/network/clear.ts | 24 + packages/cli/src/commands/network/off.ts | 24 + packages/cli/src/commands/network/on.ts | 24 + packages/cli/src/commands/network/path.ts | 24 + packages/cli/src/commands/open.ts | 47 + packages/cli/src/commands/press.ts | 34 + packages/cli/src/commands/reload.ts | 32 + packages/cli/src/commands/screenshot.ts | 147 ++ packages/cli/src/commands/select.ts | 48 + packages/cli/src/commands/skills/add.ts | 35 + packages/cli/src/commands/skills/find.ts | 74 + packages/cli/src/commands/skills/install.ts | 12 + packages/cli/src/commands/skills/list.ts | 51 + packages/cli/src/commands/skills/show.ts | 30 + packages/cli/src/commands/snapshot.ts | 57 + packages/cli/src/commands/status.ts | 27 + packages/cli/src/commands/stop.ts | 31 + packages/cli/src/commands/tab/close.ts | 36 + packages/cli/src/commands/tab/list.ts | 24 + packages/cli/src/commands/tab/new.ts | 33 + packages/cli/src/commands/tab/switch.ts | 36 + packages/cli/src/commands/templates/clone.ts | 70 + packages/cli/src/commands/templates/find.ts | 68 + packages/cli/src/commands/templates/list.ts | 54 + packages/cli/src/commands/type.ts | 46 + packages/cli/src/commands/upload.ts | 47 + packages/cli/src/commands/viewport.ts | 54 + packages/cli/src/commands/wait.ts | 57 + packages/cli/src/help.ts | 21 + packages/cli/src/hooks/command-not-found.ts | 55 + packages/cli/src/hooks/finally.ts | 13 + packages/cli/src/hooks/init.ts | 24 + packages/cli/src/hooks/prerun.ts | 13 + packages/cli/src/lib/agent.ts | 17 + packages/cli/src/lib/cloud/api.ts | 450 +++++ .../cli/src/lib/cloud/contexts-resolve.ts | 26 + packages/cli/src/lib/cloud/contexts-store.ts | 283 +++ packages/cli/src/lib/cloud/flags.ts | 27 + packages/cli/src/lib/cloud/reduce-logs.ts | 71 + packages/cli/src/lib/command-suggestions.ts | 138 ++ packages/cli/src/lib/driver/cdp-tail.ts | 242 +++ packages/cli/src/lib/driver/command-cli.ts | 175 ++ .../cli/src/lib/driver/commands/elements.ts | 83 + .../cli/src/lib/driver/commands/keyboard.ts | 25 + packages/cli/src/lib/driver/commands/mouse.ts | 87 + .../cli/src/lib/driver/commands/navigation.ts | 45 + .../cli/src/lib/driver/commands/network.ts | 20 + .../cli/src/lib/driver/commands/page-info.ts | 69 + .../cli/src/lib/driver/commands/registry.ts | 36 + .../cli/src/lib/driver/commands/runtime.ts | 106 ++ .../cli/src/lib/driver/commands/selectors.ts | 48 + .../lib/driver/commands/snapshot-format.ts | 92 + .../cli/src/lib/driver/commands/snapshot.ts | 36 + packages/cli/src/lib/driver/commands/tabs.ts | 121 ++ packages/cli/src/lib/driver/commands/types.ts | 49 + packages/cli/src/lib/driver/daemon/client.ts | 364 ++++ .../src/lib/driver/daemon/forwarded-env.ts | 65 + packages/cli/src/lib/driver/daemon/paths.ts | 87 + packages/cli/src/lib/driver/daemon/process.ts | 8 + .../cli/src/lib/driver/daemon/protocol.ts | 68 + packages/cli/src/lib/driver/daemon/server.ts | 234 +++ packages/cli/src/lib/driver/doctor.ts | 487 +++++ packages/cli/src/lib/driver/errors.ts | 19 + packages/cli/src/lib/driver/flags.ts | 74 + .../cli/src/lib/driver/local-cdp-discovery.ts | 231 +++ packages/cli/src/lib/driver/mode.ts | 225 +++ .../cli/src/lib/driver/network-capture.ts | 333 ++++ packages/cli/src/lib/driver/remote-binding.ts | 32 + packages/cli/src/lib/driver/remote-types.ts | 68 + .../cli/src/lib/driver/remote.disabled.ts | 61 + packages/cli/src/lib/driver/remote.ts | 146 ++ packages/cli/src/lib/driver/resolve-ws.ts | 57 + packages/cli/src/lib/driver/runtime.ts | 35 + .../cli/src/lib/driver/session-manager.ts | 472 +++++ packages/cli/src/lib/driver/types.ts | 54 + packages/cli/src/lib/errors.ts | 29 + packages/cli/src/lib/functions/dev.ts | 791 +++++++++ packages/cli/src/lib/functions/init.ts | 167 ++ packages/cli/src/lib/functions/invoke.ts | 81 + packages/cli/src/lib/functions/publish.ts | 279 +++ packages/cli/src/lib/functions/shared.ts | 166 ++ packages/cli/src/lib/identity.ts | 289 +++ packages/cli/src/lib/output.ts | 145 ++ packages/cli/src/lib/run-telemetry.ts | 25 + packages/cli/src/lib/skills/catalog.ts | 288 +++ packages/cli/src/lib/skills/install.ts | 654 +++++++ packages/cli/src/lib/skills/shared.ts | 32 + packages/cli/src/lib/telemetry.ts | 442 +++++ packages/cli/src/lib/templates/api.ts | 241 +++ packages/cli/src/lib/templates/output.ts | 106 ++ packages/cli/src/lib/templates/scaffold.ts | 326 ++++ packages/cli/src/lib/update.ts | 225 +++ packages/cli/src/update-check-worker.ts | 7 + packages/cli/tests/agent.test.ts | 82 + packages/cli/tests/cli-cloud-contract.test.ts | 1560 +++++++++++++++++ .../cli-command-not-found.integration.test.ts | 138 ++ .../cli/tests/cli-command-not-found.test.ts | 127 ++ .../cli/tests/cli-functions-contract.test.ts | 1128 ++++++++++++ packages/cli/tests/cli-surface.test.ts | 178 ++ packages/cli/tests/cli-telemetry.test.ts | 482 +++++ packages/cli/tests/cli-templates.test.ts | 470 +++++ packages/cli/tests/cli-update.test.ts | 154 ++ packages/cli/tests/contexts-named.test.ts | 284 +++ packages/cli/tests/contexts-store.test.ts | 274 +++ .../tests/daemon-forwarded-env-drift.test.ts | 126 ++ packages/cli/tests/doctor.test.ts | 435 +++++ packages/cli/tests/driver-commands.test.ts | 568 ++++++ packages/cli/tests/driver-errors.test.ts | 165 ++ packages/cli/tests/driver-foundation.test.ts | 1122 ++++++++++++ .../tests/helpers/fake-browserbase-server.ts | 120 ++ packages/cli/tests/helpers/platform.ts | 13 + packages/cli/tests/helpers/run-cli.ts | 51 + .../cli/tests/identity-attribution.test.ts | 448 +++++ packages/cli/tests/local-only-build.test.ts | 104 ++ packages/cli/tests/package-manifest.test.ts | 40 + packages/cli/tests/remote-disabled.test.ts | 48 + packages/cli/tests/remote-options.test.ts | 86 + packages/cli/tests/skills-install.test.ts | 247 +++ packages/cli/tests/skills-show.test.ts | 53 + packages/cli/tests/skills.test.ts | 738 ++++++++ packages/cli/tsconfig.json | 21 + packages/cli/tsconfig.local-only.json | 14 + packages/cli/vitest.config.ts | 12 + 184 files changed, 24127 insertions(+) create mode 100644 packages/cli/.gitignore create mode 100644 packages/cli/.prettierignore create mode 100644 packages/cli/.prettierrc create mode 100644 packages/cli/CHANGELOG.md create mode 100644 packages/cli/Dockerfile create mode 100644 packages/cli/LICENSE create mode 100644 packages/cli/README.md create mode 100755 packages/cli/bin/run.js create mode 100644 packages/cli/eslint.config.mjs create mode 100644 packages/cli/guides/anthropic-managed-agents/CleanShot_2026-06-05_at_13.12.432x.png create mode 100644 packages/cli/guides/anthropic-managed-agents/CleanShot_2026-06-05_at_13.15.542x.png create mode 100644 packages/cli/guides/anthropic-managed-agents/CleanShot_2026-06-05_at_13.17.012x.png create mode 100644 packages/cli/guides/anthropic-managed-agents/CleanShot_2026-06-05_at_13.27.052x.png create mode 100644 packages/cli/guides/anthropic-managed-agents/README.md create mode 100644 packages/cli/guides/anthropic-managed-agents/image3.png create mode 100644 packages/cli/media/browse.gif create mode 100644 packages/cli/package.json create mode 100644 packages/cli/skills/browse/SKILL.md create mode 100644 packages/cli/src/base.ts create mode 100644 packages/cli/src/commands/back.ts create mode 100644 packages/cli/src/commands/cdp.ts create mode 100644 packages/cli/src/commands/click.ts create mode 100644 packages/cli/src/commands/cloud/contexts/add.ts create mode 100644 packages/cli/src/commands/cloud/contexts/create.ts create mode 100644 packages/cli/src/commands/cloud/contexts/delete.ts create mode 100644 packages/cli/src/commands/cloud/contexts/get.ts create mode 100644 packages/cli/src/commands/cloud/contexts/list.ts create mode 100644 packages/cli/src/commands/cloud/contexts/update.ts create mode 100644 packages/cli/src/commands/cloud/extensions/delete.ts create mode 100644 packages/cli/src/commands/cloud/extensions/get.ts create mode 100644 packages/cli/src/commands/cloud/extensions/upload.ts create mode 100644 packages/cli/src/commands/cloud/fetch.ts create mode 100644 packages/cli/src/commands/cloud/projects/get.ts create mode 100644 packages/cli/src/commands/cloud/projects/list.ts create mode 100644 packages/cli/src/commands/cloud/projects/usage.ts create mode 100644 packages/cli/src/commands/cloud/search.ts create mode 100644 packages/cli/src/commands/cloud/sessions/create.ts create mode 100644 packages/cli/src/commands/cloud/sessions/debug.ts create mode 100644 packages/cli/src/commands/cloud/sessions/downloads/get.ts create mode 100644 packages/cli/src/commands/cloud/sessions/get.ts create mode 100644 packages/cli/src/commands/cloud/sessions/list.ts create mode 100644 packages/cli/src/commands/cloud/sessions/logs.ts create mode 100644 packages/cli/src/commands/cloud/sessions/update.ts create mode 100644 packages/cli/src/commands/cloud/sessions/uploads/create.ts create mode 100644 packages/cli/src/commands/cursor.ts create mode 100644 packages/cli/src/commands/daemon.ts create mode 100644 packages/cli/src/commands/doctor.ts create mode 100644 packages/cli/src/commands/eval.ts create mode 100644 packages/cli/src/commands/fill.ts create mode 100644 packages/cli/src/commands/forward.ts create mode 100644 packages/cli/src/commands/functions/dev.ts create mode 100644 packages/cli/src/commands/functions/init.ts create mode 100644 packages/cli/src/commands/functions/invoke.ts create mode 100644 packages/cli/src/commands/functions/publish.ts create mode 100644 packages/cli/src/commands/get.ts create mode 100644 packages/cli/src/commands/highlight.ts create mode 100644 packages/cli/src/commands/is.ts create mode 100644 packages/cli/src/commands/mouse/click.ts create mode 100644 packages/cli/src/commands/mouse/drag.ts create mode 100644 packages/cli/src/commands/mouse/hover.ts create mode 100644 packages/cli/src/commands/mouse/scroll.ts create mode 100644 packages/cli/src/commands/network/clear.ts create mode 100644 packages/cli/src/commands/network/off.ts create mode 100644 packages/cli/src/commands/network/on.ts create mode 100644 packages/cli/src/commands/network/path.ts create mode 100644 packages/cli/src/commands/open.ts create mode 100644 packages/cli/src/commands/press.ts create mode 100644 packages/cli/src/commands/reload.ts create mode 100644 packages/cli/src/commands/screenshot.ts create mode 100644 packages/cli/src/commands/select.ts create mode 100644 packages/cli/src/commands/skills/add.ts create mode 100644 packages/cli/src/commands/skills/find.ts create mode 100644 packages/cli/src/commands/skills/install.ts create mode 100644 packages/cli/src/commands/skills/list.ts create mode 100644 packages/cli/src/commands/skills/show.ts create mode 100644 packages/cli/src/commands/snapshot.ts create mode 100644 packages/cli/src/commands/status.ts create mode 100644 packages/cli/src/commands/stop.ts create mode 100644 packages/cli/src/commands/tab/close.ts create mode 100644 packages/cli/src/commands/tab/list.ts create mode 100644 packages/cli/src/commands/tab/new.ts create mode 100644 packages/cli/src/commands/tab/switch.ts create mode 100644 packages/cli/src/commands/templates/clone.ts create mode 100644 packages/cli/src/commands/templates/find.ts create mode 100644 packages/cli/src/commands/templates/list.ts create mode 100644 packages/cli/src/commands/type.ts create mode 100644 packages/cli/src/commands/upload.ts create mode 100644 packages/cli/src/commands/viewport.ts create mode 100644 packages/cli/src/commands/wait.ts create mode 100644 packages/cli/src/help.ts create mode 100644 packages/cli/src/hooks/command-not-found.ts create mode 100644 packages/cli/src/hooks/finally.ts create mode 100644 packages/cli/src/hooks/init.ts create mode 100644 packages/cli/src/hooks/prerun.ts create mode 100644 packages/cli/src/lib/agent.ts create mode 100644 packages/cli/src/lib/cloud/api.ts create mode 100644 packages/cli/src/lib/cloud/contexts-resolve.ts create mode 100644 packages/cli/src/lib/cloud/contexts-store.ts create mode 100644 packages/cli/src/lib/cloud/flags.ts create mode 100644 packages/cli/src/lib/cloud/reduce-logs.ts create mode 100644 packages/cli/src/lib/command-suggestions.ts create mode 100644 packages/cli/src/lib/driver/cdp-tail.ts create mode 100644 packages/cli/src/lib/driver/command-cli.ts create mode 100644 packages/cli/src/lib/driver/commands/elements.ts create mode 100644 packages/cli/src/lib/driver/commands/keyboard.ts create mode 100644 packages/cli/src/lib/driver/commands/mouse.ts create mode 100644 packages/cli/src/lib/driver/commands/navigation.ts create mode 100644 packages/cli/src/lib/driver/commands/network.ts create mode 100644 packages/cli/src/lib/driver/commands/page-info.ts create mode 100644 packages/cli/src/lib/driver/commands/registry.ts create mode 100644 packages/cli/src/lib/driver/commands/runtime.ts create mode 100644 packages/cli/src/lib/driver/commands/selectors.ts create mode 100644 packages/cli/src/lib/driver/commands/snapshot-format.ts create mode 100644 packages/cli/src/lib/driver/commands/snapshot.ts create mode 100644 packages/cli/src/lib/driver/commands/tabs.ts create mode 100644 packages/cli/src/lib/driver/commands/types.ts create mode 100644 packages/cli/src/lib/driver/daemon/client.ts create mode 100644 packages/cli/src/lib/driver/daemon/forwarded-env.ts create mode 100644 packages/cli/src/lib/driver/daemon/paths.ts create mode 100644 packages/cli/src/lib/driver/daemon/process.ts create mode 100644 packages/cli/src/lib/driver/daemon/protocol.ts create mode 100644 packages/cli/src/lib/driver/daemon/server.ts create mode 100644 packages/cli/src/lib/driver/doctor.ts create mode 100644 packages/cli/src/lib/driver/errors.ts create mode 100644 packages/cli/src/lib/driver/flags.ts create mode 100644 packages/cli/src/lib/driver/local-cdp-discovery.ts create mode 100644 packages/cli/src/lib/driver/mode.ts create mode 100644 packages/cli/src/lib/driver/network-capture.ts create mode 100644 packages/cli/src/lib/driver/remote-binding.ts create mode 100644 packages/cli/src/lib/driver/remote-types.ts create mode 100644 packages/cli/src/lib/driver/remote.disabled.ts create mode 100644 packages/cli/src/lib/driver/remote.ts create mode 100644 packages/cli/src/lib/driver/resolve-ws.ts create mode 100644 packages/cli/src/lib/driver/runtime.ts create mode 100644 packages/cli/src/lib/driver/session-manager.ts create mode 100644 packages/cli/src/lib/driver/types.ts create mode 100644 packages/cli/src/lib/errors.ts create mode 100644 packages/cli/src/lib/functions/dev.ts create mode 100644 packages/cli/src/lib/functions/init.ts create mode 100644 packages/cli/src/lib/functions/invoke.ts create mode 100644 packages/cli/src/lib/functions/publish.ts create mode 100644 packages/cli/src/lib/functions/shared.ts create mode 100644 packages/cli/src/lib/identity.ts create mode 100644 packages/cli/src/lib/output.ts create mode 100644 packages/cli/src/lib/run-telemetry.ts create mode 100644 packages/cli/src/lib/skills/catalog.ts create mode 100644 packages/cli/src/lib/skills/install.ts create mode 100644 packages/cli/src/lib/skills/shared.ts create mode 100644 packages/cli/src/lib/telemetry.ts create mode 100644 packages/cli/src/lib/templates/api.ts create mode 100644 packages/cli/src/lib/templates/output.ts create mode 100644 packages/cli/src/lib/templates/scaffold.ts create mode 100644 packages/cli/src/lib/update.ts create mode 100644 packages/cli/src/update-check-worker.ts create mode 100644 packages/cli/tests/agent.test.ts create mode 100644 packages/cli/tests/cli-cloud-contract.test.ts create mode 100644 packages/cli/tests/cli-command-not-found.integration.test.ts create mode 100644 packages/cli/tests/cli-command-not-found.test.ts create mode 100644 packages/cli/tests/cli-functions-contract.test.ts create mode 100644 packages/cli/tests/cli-surface.test.ts create mode 100644 packages/cli/tests/cli-telemetry.test.ts create mode 100644 packages/cli/tests/cli-templates.test.ts create mode 100644 packages/cli/tests/cli-update.test.ts create mode 100644 packages/cli/tests/contexts-named.test.ts create mode 100644 packages/cli/tests/contexts-store.test.ts create mode 100644 packages/cli/tests/daemon-forwarded-env-drift.test.ts create mode 100644 packages/cli/tests/doctor.test.ts create mode 100644 packages/cli/tests/driver-commands.test.ts create mode 100644 packages/cli/tests/driver-errors.test.ts create mode 100644 packages/cli/tests/driver-foundation.test.ts create mode 100644 packages/cli/tests/helpers/fake-browserbase-server.ts create mode 100644 packages/cli/tests/helpers/platform.ts create mode 100644 packages/cli/tests/helpers/run-cli.ts create mode 100644 packages/cli/tests/identity-attribution.test.ts create mode 100644 packages/cli/tests/local-only-build.test.ts create mode 100644 packages/cli/tests/package-manifest.test.ts create mode 100644 packages/cli/tests/remote-disabled.test.ts create mode 100644 packages/cli/tests/remote-options.test.ts create mode 100644 packages/cli/tests/skills-install.test.ts create mode 100644 packages/cli/tests/skills-show.test.ts create mode 100644 packages/cli/tests/skills.test.ts create mode 100644 packages/cli/tsconfig.json create mode 100644 packages/cli/tsconfig.local-only.json create mode 100644 packages/cli/vitest.config.ts diff --git a/packages/cli/.gitignore b/packages/cli/.gitignore new file mode 100644 index 0000000000..3a1e128b49 --- /dev/null +++ b/packages/cli/.gitignore @@ -0,0 +1,37 @@ +# dependencies (pnpm install) +node_modules + +# output +out +dist +*.tgz + +# code coverage +coverage +*.lcov + +# logs +logs +*.log +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# dotenv environment variable files +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# caches +.eslintcache +.cache +*.tsbuildinfo + +# IntelliJ based IDEs +.idea + +# Finder (MacOS) folder config +.DS_Store + +# oclif manifest (generated at build) +oclif.manifest.json diff --git a/packages/cli/.prettierignore b/packages/cli/.prettierignore new file mode 100644 index 0000000000..15e84bc8e0 --- /dev/null +++ b/packages/cli/.prettierignore @@ -0,0 +1,14 @@ +pnpm-lock.yaml +README.md +**/*.json +.github/ +dist/ +node_modules/ +coverage/ +out/ +.cache/ +*.tgz +.browserbase/ +.browserbase/** +**/.browserbase/ +**/.browserbase/** diff --git a/packages/cli/.prettierrc b/packages/cli/.prettierrc new file mode 100644 index 0000000000..0967ef424b --- /dev/null +++ b/packages/cli/.prettierrc @@ -0,0 +1 @@ +{} diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md new file mode 100644 index 0000000000..22cb5a648f --- /dev/null +++ b/packages/cli/CHANGELOG.md @@ -0,0 +1,271 @@ +# browse + +## 0.9.5 + +### Patch Changes + +- [#2335](https://github.com/browserbase/stagehand/pull/2335) [`19f9f5a`](https://github.com/browserbase/stagehand/commit/19f9f5a2631573b9952e4df7fbd2c8765c5fac5b) Thanks [@shrey150](https://github.com/shrey150)! - Add `browse skills show` to print the bundled skill and point agents to it from `--help`. + +## 0.9.4 + +### Patch Changes + +- [#2296](https://github.com/browserbase/stagehand/pull/2296) [`2f5e085`](https://github.com/browserbase/stagehand/commit/2f5e085a38aa6d8d52eb33017c64385a75e192cf) Thanks [@shrey150](https://github.com/shrey150)! - `browse snapshot` now prints the accessibility tree only by default, omitting the `xpathMap`/`urlMap` ref maps. Pass `--full` to include them. Ref-based element commands are unaffected. + +## 0.9.3 + +### Patch Changes + +- [#2310](https://github.com/browserbase/stagehand/pull/2310) [`77a8e92`](https://github.com/browserbase/stagehand/commit/77a8e926ac525264e41a3686808270efd3b4fd9f) Thanks [@shrey150](https://github.com/shrey150)! - browse is now also distributed as a Docker image: `ghcr.io/browserbase/browse` (multi-arch `linux/amd64,linux/arm64`, pinned to each release). Lets code sandboxes consume the CLI by image reference without a Dockerfile. + +## 0.9.2 + +### Patch Changes + +- [#2284](https://github.com/browserbase/stagehand/pull/2284) [`70b72d3`](https://github.com/browserbase/stagehand/commit/70b72d36907254fb3719ea5f520d37d362a11319) Thanks [@shrey150](https://github.com/shrey150)! - Add named contexts to the CLI so you can reuse a Browserbase context by a memorable name instead of its ID. `browse cloud contexts create --name ` saves a local name→ID alias (stored at `(XDG_CONFIG_HOME||~/.config)/browserbase/contexts.json`, honoring `BROWSERBASE_CONFIG_DIR`), `browse cloud contexts add ` names a context you already have, `browse cloud contexts list` shows your saved names, and any place that accepts a context ID — `contexts get|update|delete` and `sessions create --context-id` — now also accepts a saved name. Deleting a context prunes its local alias, and a typo'd name fails with a "did you mean?" hint instead of a cryptic API error. The map is purely client-side: it stores the same IDs the API already returns, and a missing or corrupt file degrades to "no saved contexts" rather than erroring. + +- [#2282](https://github.com/browserbase/stagehand/pull/2282) [`b8132f6`](https://github.com/browserbase/stagehand/commit/b8132f6a3350ba5682f6ead07d72f86d34286b16) Thanks [@shrey150](https://github.com/shrey150)! - Add `--verified` and `--proxies` to remote driver sessions so `browse open --remote --verified --proxies` opens a Verified and/or proxied Browserbase session in one command — no more create-then-attach with `--cdp`. + + - The flags are valid only with `--remote` (they are never implied, since that would silently switch to billed cloud sessions) and are sticky for the session's lifetime like `--headed`/`--headless`: a re-open requesting different settings fails with the usual stop-and-reopen error. + - Because the session is created through the normal remote path (not a raw `--cdp` attach), it keeps its Browserbase identity and the `browse_cli` attribution tag. `browse status` and `browse doctor` now surface the Browserbase session ID, the dashboard URL, the live-view (debug) URL, and the verified/proxies state. + - `--verified` requires a Browserbase Scale plan. + +- [#2280](https://github.com/browserbase/stagehand/pull/2280) [`39d7638`](https://github.com/browserbase/stagehand/commit/39d7638022b742f9d24776b6dc5d70a992aaeabf) Thanks [@shrey150](https://github.com/shrey150)! - Honor `BROWSERBASE_API_KEY` passed to an already-running driver daemon. Previously, if the first remote command started the daemon without a key, a later `BROWSERBASE_API_KEY=… browse open --remote` (or an exported key in a new shell) kept failing with "Missing BROWSERBASE_API_KEY" because the detached daemon captured `process.env` once at spawn time and never saw the new key. The client now forwards the caller's key over the (localhost, owner-only) driver socket with every command, and the daemon threads it straight into the Stagehand constructor when it creates the session — so an inline or exported key works without a manual `browse stop` and restart. The forwarded key is never written back into the daemon's `process.env`; its only home is the live session. Already-initialized warm sessions are untouched; the forwarded key only takes effect at session init. The local-only (CDP-only) build forwards nothing and remains free of any API-key code path. + +- [#2297](https://github.com/browserbase/stagehand/pull/2297) [`c18ab34`](https://github.com/browserbase/stagehand/commit/c18ab345e00451237ebd2bcf3567a76bbf1e52a3) Thanks [@shrey150](https://github.com/shrey150)! - Remove the `browse refs` command. It only re-printed the `xpathMap`/`urlMap` cached from the last `browse snapshot` — which `browse snapshot` already returns — so it was redundant, and it returned stale maps if the page had changed since that snapshot. + +## 0.9.1 + +### Patch Changes + +- [#2277](https://github.com/browserbase/stagehand/pull/2277) [`263e4d4`](https://github.com/browserbase/stagehand/commit/263e4d437dbdb722b9801488dd8cb40b8d78106e) Thanks [@shrey150](https://github.com/shrey150)! - Attribute CLI-driven Browserbase usage to an anonymous install. Remote browser sessions now stamp `install_id` and `cli_version` (alongside `browse_cli`) onto `userMetadata`, and cloud Search/Fetch requests send `x-bb-client` and `x-bb-install-id` headers. The install id reuses the existing anonymous telemetry marker; resolution is best-effort and never blocks or fails a command. + +## 0.9.0 + +### Minor Changes + +- [#2246](https://github.com/browserbase/stagehand/pull/2246) [`303ab2c`](https://github.com/browserbase/stagehand/commit/303ab2c03c68e239c5e27c6fe9f0fa02b12c4749) Thanks [@shrey150](https://github.com/shrey150)! - `browse screenshot` now writes a file by default instead of printing base64 to stdout. Bare invocations save to `screenshot-.` in the current directory (with a collision counter instead of overwriting) and print `{ "saved": "" }`. A new `--base64` flag preserves the legacy behavior of printing `{ "base64": "..." }` to stdout; it is mutually exclusive with `--path`. `--path` behavior is unchanged. + + Note for scripts that parsed the bare-invocation base64 output: pass `--base64` to keep the old stdout contract. + +### Patch Changes + +- [#2250](https://github.com/browserbase/stagehand/pull/2250) [`8b83bb7`](https://github.com/browserbase/stagehand/commit/8b83bb7bb51c81b05014fac4a77bc653a90ca98b) Thanks [@shrey150](https://github.com/shrey150)! - Fix `browse skills add` on Windows and bound the unbounded installer stages. + + - Quote the `npx` command and arguments when spawning through cmd.exe (`shell: true` for `.cmd`/`.bat` shims), so the default `C:\Program Files\nodejs\npx.cmd` path and install paths with spaces (e.g. `C:\Users\First Last\...`) no longer split at the space and fail with "'C:\Program' is not recognized". + - Kill the `npx skills add` child after a 180s deadline (SIGTERM, then SIGKILL) and fail with a clear message and a distinct `skill_install_timeout` telemetry result code instead of hanging forever. + - Bound the catalog and skill-file fetches with a 10s abort timeout, preserving the existing catalog-unavailable fallback semantics when a fetch hangs. + +## 0.8.5 + +### Patch Changes + +- [#2258](https://github.com/browserbase/stagehand/pull/2258) [`2441cd4`](https://github.com/browserbase/stagehand/commit/2441cd4197da67896dca1e4a856673032fd66c74) Thanks [@shrey150](https://github.com/shrey150)! - Stop headed local sessions from stealing OS focus on every command. + + In headed managed-local mode the browse daemon re-resolved the active page on every subcommand and called `setActivePage()` unconditionally, which ends in a CDP `Target.activateTarget`. On macOS that raises the whole Chrome app to the OS foreground, stealing keyboard focus from the editor/terminal on each `browse navigate/snapshot/get/…` — making the CLI nearly unusable alongside a coding agent and impossible to parallelize. The active tab is now re-activated only when it actually changes; explicit `tab new` / `tab select` still foreground intentionally. + +- [#2249](https://github.com/browserbase/stagehand/pull/2249) [`4ee8d99`](https://github.com/browserbase/stagehand/commit/4ee8d9948c143e114b33b8b63b90c75daec1545d) Thanks [@shrey150](https://github.com/shrey150)! - Add did-you-mean suggestions and telemetry for unknown commands. + + - Unknown commands (e.g. `browse sessions`, `browse search`, `browse auth status` — old Commander-era syntax — plus plain typos like `browse opne`) now print an actionable suggestion on stderr: an explicit alias table maps old syntax to the current command tree, with a Levenshtein nearest-match fallback for typos. The clause is omitted when there is no decent match. + - A new `cli.command_not_found` telemetry event makes this failure class measurable. Privacy: only the sanitized attempted command id and the computed suggestion are sent — never raw argv, which can contain URLs, selectors, or secrets. + - oclif's standard "command not found" error and exit code 2 are preserved; no new runtime dependency (deliberately avoids `@oclif/plugin-not-found`, which prompts interactively and is agent-hostile). + +- [#2248](https://github.com/browserbase/stagehand/pull/2248) [`cffcc91`](https://github.com/browserbase/stagehand/commit/cffcc91add8edc1f9b9f0846b36ecb8ea51605d0) Thanks [@shrey150](https://github.com/shrey150)! - Make driver (browser session) failures actionable, classified, and self-correcting. + + - An invalid `BROWSERBASE_API_KEY` no longer surfaces a bare `401 Unauthorized`: remote init failures are classified (401 invalid key, 403 permissions/plan, other) into actionable messages that point at the key settings page, `--local`, and `browse doctor`. + - A missing local Chrome now explains how to install Chrome, attach with `--cdp`, or switch to remote, instead of leaking chrome-launcher internals. + - Cached init failures back off exponentially (5s doubling, capped at 5 minutes) and append a "failing repeatedly" hint after 3 consecutive failures, so retry-looping agents get a clear self-correction signal instead of instant identical errors forever. + - The daemon protocol now carries optional `code`/`httpStatus` on error responses (backward compatible), and the client records them as telemetry result codes — `open` failures stop being 94% `unexpected`. New codes include `remote_auth_401`, `remote_auth_403`, `remote_session_create_failed`, `no_chrome_found`, `stale_ref`, `no_active_page`, `daemon_lock_timeout`, `daemon_unresponsive`, `daemon_socket_timeout`, and `daemon_spawn_failed`. + +- [#2201](https://github.com/browserbase/stagehand/pull/2201) [`9971a7b`](https://github.com/browserbase/stagehand/commit/9971a7b3d8ecca255b4548cfb9128657c053cca7) Thanks [@shrey150](https://github.com/shrey150)! - Add Chrome launch arg flags for managed local browser sessions: `--chrome-arg ` (repeatable) appends launch args on top of Chrome's defaults, `--ignore-default-chrome-arg ` (repeatable) drops specific default args, and `--no-default-chrome-args` launches without any of Chrome's defaults. + +- [#2251](https://github.com/browserbase/stagehand/pull/2251) [`3ecf09e`](https://github.com/browserbase/stagehand/commit/3ecf09eabb7f3cd107bf64378664416597e912c8) Thanks [@shrey150](https://github.com/shrey150)! - Emit a `skill_id` property on `cli.command_completed` telemetry. + + The validated, catalog-public skill id (e.g. `yelp.com/extract-reviews`, or `bundled/browse` for `skills install`) is attached to the completion event for `browse skills add`/`install`, covering both successful installs and every downstream failure path (`skill_not_found`, `skill_install_failed`, ...). Only the parsed, regex-validated id is ever attached — never the raw argument. + +## 0.8.4 + +### Patch Changes + +- [#2213](https://github.com/browserbase/stagehand/pull/2213) [`7449046`](https://github.com/browserbase/stagehand/commit/7449046647c30800404c333dd604bacccba0aa7c) Thanks [@shrey150](https://github.com/shrey150)! - fix(cli): request the full template catalog via scope=all so `browse templates list` returns all templates, not just playground-runnable ones + +- [#2210](https://github.com/browserbase/stagehand/pull/2210) [`a9552fd`](https://github.com/browserbase/stagehand/commit/a9552fde629a2b13bc32dedc002e401af90b866c) Thanks [@shrey150](https://github.com/shrey150)! - Make `browse skills add` failures diagnosable and fail cleanly on unknown skills. + + - Unknown (non-generated) skill ids now fail fast with an actionable "not found in the catalog" message pointing at `browse skills find`/`browse skills list`, instead of silently git-cloning the entire browse.sh repo and exiting with an opaque error. + - The `npx skills add` child's output is now buffered (tail) while still streaming live to the terminal, so a nonzero exit surfaces the real reason instead of a bare exit code. + - Failures now record distinct telemetry result codes (`skill_not_found`, `invalid_skill_id`, `npx_missing`, `skill_install_failed`) so the failure modes are measurable. + - `browse skills add` with no argument now prints actionable guidance (the `/` form plus `browse skills find`) instead of oclif's bare "Missing 1 required arg". + +## 0.8.3 + +### Patch Changes + +- [#2192](https://github.com/browserbase/stagehand/pull/2192) [`e7d3b55`](https://github.com/browserbase/stagehand/commit/e7d3b55f69f2a1fd75e92dea8f831f96fa6180d3) Thanks [@shrey150](https://github.com/shrey150)! - Lead-with-local onboarding: the missing-API-key error on cloud commands now tells users that local browser automation needs no key and points them to `browse open --local`. The remote-mode driver error is clearer about when a key is required versus when local mode works without one. + +## 0.8.2 + +### Patch Changes + +- e29aeac: Update README demo GIF link + +## 0.8.1 + +### Patch Changes + +- 67d0ce8: Restore CLI telemetry agent attribution. +- c9a4236: Restore CLI completion telemetry result and HTTP metadata. + +## 0.8.0 + +### Minor Changes + +- 013f345: Add Browserbase Fetch API output formats to `browse cloud fetch`, defaulting to markdown with support for raw and schema-based JSON output. + +## 0.7.3 + +### Patch Changes + +- 87c0535: Publish the updated npm README. + +## 0.7.2 + +### Patch Changes + +- c0ed7ff: Allow `browse skills list` and `browse skills find` to display any skill method value returned by the Browse.sh catalog. + +## 0.7.1 + +### Patch Changes + +- 4d4f7f4: Make skills and templates list-style output human-readable in terminals while preserving JSON output for scripts. + +## 0.7.0 + +### Minor Changes + +- 147540b: Add `browse skills list` and `browse skills find` for Browse.sh catalog discovery. + +### Patch Changes + +- f156c32: Add human-readable table output for cloud session, project, and search lists while preserving JSON for scripts. + +## 0.6.1 + +### Patch Changes + +- cc5f649: Make browse driver sessions recover when no active page is selected and reuse matching daemon targets for broad local or remote mode flags. + +## 0.6.0 + +### Minor Changes + +- b3425a3: Add Browserbase cloud API commands under the new `browse cloud` oclif taxonomy. +- b3425a3: Port the browse driver command surface onto native oclif commands. +- b3425a3: Add the initial native browse driver daemon foundation with top-level open, status, and stop commands. +- b3425a3: Add native `browse functions` commands for initializing, developing, publishing, and invoking Browserbase Functions. +- b3425a3: Add `browse skills add` for site-specific skill installation. +- b3425a3: Add `browse skills install` for installing the bundled Browse CLI skill. +- b3425a3: Add Browserbase template listing, search, and clone commands. +- b3425a3: Add best-effort PostHog telemetry for oclif command lifecycle events. +- b3425a3: Introduce the minimal oclif-based `browse` CLI scaffold. +- b3425a3: Add a lightweight npm registry update notice for the browse CLI. + +### Patch Changes + +- b3425a3: Add alpha release automation for publishing browse canaries from the oclif and main trunks. +- b3425a3: Add a read-only `browse doctor` command for browser driver session diagnostics. +- b3425a3: Create a fresh browser page when `browse open` finds an initialized session with no pages. +- b3425a3: Generate and package the oclif manifest to reduce browse CLI startup latency. +- b3425a3: Harden local Functions dev CORS and owner-only driver runtime artifacts. +- b3425a3: Use --verified for Browserbase Verified sessions while accepting --advanced-stealth as a hidden compatibility alias. + +## 0.5.7 + +### Patch Changes + +- e0c7b2b: Improve CLI telemetry classification for browse wrapper failures and generic API HTTP errors. + +## 0.5.6 + +### Patch Changes + +- 038517f: Capture structured telemetry result codes and HTTP status details for CLI fetch and search failures. + +## 0.5.5 + +### Patch Changes + +- 644d4ce: Tag telemetry events with the detected agent harness (Claude Code, Codex, Cursor, etc.) so we can understand how the CLI is invoked across environments. + +## 0.5.4 + +### Patch Changes + +- 4b9e2aa: Add a Browserbase settings hint to missing API key errors so users know where to find their API key. +- 35cc5b0: Clarify browse and skills installation flows with explicit `--install` flags while keeping `--yes` as a compatibility alias. +- 440f753: Add CLI auto-update checks with npm registry lookup, a shared global `--yes` prompt context, and update/install prompt handling improvements for `browse` and `skills`. + +## 0.5.3 + +### Patch Changes + +- 5012468: Add privacy-safe lifecycle telemetry for command invocation and completion events. + +## 0.5.2 + +### Patch Changes + +- 22df06e: Fix `bb templates clone` to scaffold full `create-browser-app` boilerplate instead of cloning only the raw template files. + +## 0.5.1 + +### Patch Changes + +- 2f0ac7a: Add `bb templates` command for listing and cloning starter templates + +## 0.5.0 + +### Minor Changes + +- e63ad9f: Add first-class flags to `bb sessions create` for commonly used session parameters (--proxies, --advanced-stealth, --solve-captchas, --region, --keep-alive, --timeout, --block-ads, --context-id, --persist, --record-session, --log-session, --viewport, --extension-id). Flags merge with --body JSON when both are provided, with flags taking precedence. + +## 0.4.0 + +### Minor Changes + +- 69a88fe: Make CLI more agent-friendly: add `--yes`/`-y` flag to `browse` and `skills` to skip interactive prompts, add usage examples to `--help` for every subcommand, add `--stdin` flag for piped JSON input on `sessions create/update` and `contexts create`, and fix readline hanging in non-interactive environments. + +## 0.3.2 + +### Patch Changes + +- e8822fe: Improve README with comprehensive command reference, usage examples, and configuration docs + +## 0.3.1 + +### Patch Changes + +- 82ec911: Add ASCII art banner and hidden `bb b` easter egg command + +## 0.3.0 + +### Minor Changes + +- 497145b: Add `bb search` command for the Browserbase Search API + +## 0.2.1 + +### Patch Changes + +- 1728c46: Read CLI version from package.json instead of hardcoding it, so `bb -V` stays in sync with changesets + +## 0.2.0 + +### Minor Changes + +- 09f4bf6: Add `bb skills` command to install Browserbase agent skills via `npx skills add browserbase/skills`. + +### Patch Changes + +- cd489c9: Improve CLI subcommand descriptions for clarity. +- 5953230: Add release automation for publishing `@browserbasehq/cli` to npm. diff --git a/packages/cli/Dockerfile b/packages/cli/Dockerfile new file mode 100644 index 0000000000..56d9073458 --- /dev/null +++ b/packages/cli/Dockerfile @@ -0,0 +1,10 @@ +# No browser is bundled: browse drives a remote Browserbase cloud browser over +# CDP, so the image stays a thin client. +FROM node:20-slim + +ARG BROWSE_VERSION +RUN test -n "$BROWSE_VERSION" \ + && npm install -g "browse@${BROWSE_VERSION}" \ + && npm cache clean --force + +CMD ["browse", "--help"] diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE new file mode 100644 index 0000000000..683c709c95 --- /dev/null +++ b/packages/cli/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 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. diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 0000000000..416dc1b3a9 --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,302 @@ +
+ +# >_ browse + +### The single CLI your AI agents need to access the internet reliably. + +[![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/badge/license-MIT-000000?style=flat-square)](https://github.com/browserbase/stagehand/blob/main/packages/cli/LICENSE) + +```bash +npm install -g browse +``` + +browse CLI demo + +
+ +--- + +`browse` gives any agent — or any terminal — a reliable way to drive a real browser, learn how to use specific websites, and tap into Browserbase's cloud. One command to navigate the open web, capture telemetry while you do it, and reuse skills the community has already built. + +## Why browse + +- **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). + +## Quick start + +```bash +npm install -g browse + +browse open https://example.com +browse snapshot +browse click @0-12 +browse fill @0-8 "hello" +browse get title +browse screenshot --path page.png +browse stop +``` + +## How it works + +`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 ` (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 ` | Attach directly to a CDP endpoint (port, `http(s)://`, or `ws(s)://`) | +| `--target-id ` | Select a specific CDP target when attaching to an existing browser | +| `--chrome-arg ` | Append a Chrome launch arg on top of the defaults (repeatable, managed-local only) | +| `--ignore-default-chrome-arg ` | Drop a specific Chrome default launch arg (repeatable, managed-local only) | +| `--no-default-chrome-args` | Launch without any of Chrome's default args (managed-local only) | + +```bash +browse open https://example.com # default target +browse open https://example.com --local --headed +browse open https://example.com --local --headed --chrome-arg=--no-focus-on-navigate +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/ --target-id +``` + +Run `browse doctor` to diagnose session and browser-connection prerequisites for any target. + +## Commands + +### Navigation + +```bash +browse open # Open a URL (--wait load|domcontentloaded|networkidle, --timeout ) +browse reload # Reload the active page +browse back # Navigate backward +browse forward # Navigate forward +``` + +### Snapshot + +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 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 +``` + +### 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