Skip to content
Back to search

gsd-browser

SkillWorks with Claude CodeGitHub

Native Rust browser automation CLI for AI agents. Use when the user needs to interact with websites — navigating pages, filling forms, clicking buttons, taking screenshots, sharing a live browser view, narrating browser actions, extracting structured data, running assertions, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "show me the browser", "share the screen", "pause the browser", "step through this", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", "visual regression test", "check for prompt injection", or any task requiring programmatic web interaction.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gsd-build--gsd-browser/badge.svg)](/listings/gsd-build--gsd-browser)

HTML

<a href="/listings/gsd-build--gsd-browser"><img src="/api/listings/gsd-build--gsd-browser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Recommended: installer (macOS / Linux)

curl -fsSL https://install.gsd.build/browser | bash

The installer downloads the correct `gsd-browser` binary for your platform. If Chrome or Chromium is already installed, it uses that. Otherwise it downloads Chromium automatically when Chrome for Testing is available for your platform. Run `gsd-browser update` to install the current release.

Pre-built binaries

Download from [GitHub Releases](https://github.com/gsd-build/gsd-browser/releases):

| Platform | Asset | |----------|-------| | macOS (Apple Silicon) | `gsd-browser-darwin-arm64` | | macOS (Intel) | `gsd-browser-darwin-x64` | | Linux (ARM64) | `gsd-browser-linux-arm64` | | Linux (x64) | `gsd-browser-linux-x64` |

Build from source

git clone https://github.com/gsd-build/gsd-browser.git
cd gsd-browser
cargo install --path cli

Package registries

The public npm package (`@gsd-build/gsd-browser`) and crates.io package (`gsd-browser`) are not published yet. Use the installer, GitHub release assets, or a source build.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 783 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: gsd-browser
  3. description: >
  4. Native Rust browser automation CLI for AI agents. Use when the user needs to
  5. interact with websites — navigating pages, filling forms, clicking buttons,
  6. taking screenshots, sharing a live browser view, narrating browser actions,
  7. extracting structured data, running assertions, testing web apps, or
  8. automating any browser task. Triggers include requests to "open a website",
  9. "fill out a form", "click a button", "take a screenshot", "show me the
  10. browser", "share the screen", "pause the browser", "step through this",
  11. "scrape data from a page", "test this web app", "login to a site",
  12. "automate browser actions", "visual regression test", "check for prompt
  13. injection", or any task requiring programmatic web interaction.
  14. allowed-tools: Bash(gsd-browser:*), Bash(gsd-browser *)
  15. ---
  16. # Browser Automation with gsd-browser
  17. ## Critical Rules
  18. 1. **The daemon auto-starts on browser commands.** `daemon health` only reports state; it does not start a session. Use `daemon start` only when you want to pre-warm or verify daemon lifecycle explicitly.
  19. 2. **Always re-snapshot after page changes.** Refs are versioned (`@v1:e1`). After navigation, form submission, or dynamic content loading, old refs are stale. Run `gsd-browser snapshot` to get fresh refs.
  20. 3. **Use `--json` when parsing output.** Use text mode when reading output yourself. Use `--json` when you need to extract values programmatically (e.g., checking assertion results, parsing snapshot refs).
  21. 4. **Positional args have no flag prefix.** Commands like `click`, `type`, `hover` take positional args — do NOT add `--selector`. See exact syntax in command reference below.
  22. 5. **Use `batch` for atomic multi-step flows.** Batch reduces round trips and keeps pass/fail checks in one call. Use separate commands when you need intermediate output (e.g., snapshot to discover refs).
  23. 6. **Use `view` when the user wants to watch or direct the browser.** The live viewer is an authenticated local workbench with Control, Annotate, Record, and Sensitive modes. Keep CLI commands on the same named session.
  24. ## Core Workflow
  25. Every browser automation follows this pattern:
  26. 1. **Navigate**: `gsd-browser navigate <url>`
  27. 2. **Snapshot**: `gsd-browser snapshot` (get versioned refs like `@v1:e1`, `@v1:e2`)
  28. 3. **Interact**: Use refs to click, fill, hover
  29. 4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
  30. ```bash
  31. gsd-browser navigate https://example.com/form
  32. gsd-browser snapshot
  33. # Output: @v1:e1 [input type="email"], @v1:e2 [input type="password"], @v1:e3 [button] "Submit"
  34. gsd-browser fill-ref @v1:e1 "user@example.com"
  35. gsd-browser fill-ref @v1:e2 "password123"
  36. gsd-browser click-ref @v1:e3
  37. gsd-browser wait-for --condition network_idle
  38. gsd-browser snapshot # REQUIRED — old refs are now stale
  39. ```
  40. ## Command Chaining
  41. Commands can be chained with `&&` in a single shell invocation. Browser state also persists across separate invocations through the background daemon when you stay on the same session.
  42. ```bash
  43. # Chain navigate + wait + snapshot
  44. gsd-browser navigate https://example.com && gsd-browser wait-for --condition network_idle && gsd-browser snapshot
  45. # Chain multiple interactions
  46. gsd-browser fill-ref @v1:e1 "user@example.com" && gsd-browser fill-ref @v1:e2 "password123" && gsd-browser click-ref @v1:e3
  47. ```
  48. **When to chain:** Use `&&` when you don't need intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact).
  49. ---
  50. ## Command Reference
  51. Argument syntax: `<arg>` = required positional, `[arg]` = optional positional, `--flag` = named option. Do NOT add `--` prefix to positional args.
  52. ### Navigation
  53. ```bash
  54. gsd-browser navigate <url> # Navigate to a URL
  55. gsd-browser back # Go back in browser history
  56. gsd-browser forward # Go forward in browser history
  57. gsd-browser reload # Reload the current page
  58. ```
  59. ### Interaction
  60. All selectors are **positional** — do NOT use `--selector`.
  61. ```bash
  62. # Click
  63. gsd-browser click <selector> # Click by CSS selector
  64. gsd-browser click --x 100 --y 200 # Click by coordinates (no selector)
  65. # Type — positional: <selector> <text>
  66. gsd-browser type <selector> <text> # Atomic fill (replaces content)
  67. gsd-browser type <selector> <text> --slowly # Character-by-character
  68. gsd-browser type <selector> <text> --clear-first # Clear field before typing
  69. gsd-browser type <selector> <text> --submit # Press Enter after typing
  70. # Other interaction — all positional selectors
  71. gsd-browser press <key> # Press key: Enter, Escape, Tab, Meta+A
  72. gsd-browser hover <selector> # Hover over element
  73. gsd-browser scroll --direction down # Scroll down 300px (default)
  74. gsd-browser scroll --direction up --amount 500 # Scroll up 500px
  75. gsd-browser select-option <selector> <option> # Select dropdown by label or value
  76. gsd-browser set-checked <selector> --checked # Check checkbox/radio (omit --checked to uncheck)
  77. gsd-browser drag <source-selector> <target-selector> # Drag-and-drop
  78. gsd-browser upload-file <selector> <file>... # Set files on <input type="file">
  79. gsd-browser set-viewport --preset mobile # Preset: mobile, tablet, desktop, wide
  80. gsd-browser set-viewport --width 1920 --height 1080 # Custom dimensions
  81. ```
  82. ### Snapshot & Refs
  83. Refs are versioned (`@v1:e1`, `@v2:e3`). The version increments each snapshot. **Old refs become stale after page changes — always re-snapshot.**
  84. ```bash
  85. # Take snapshot
  86. gsd-browser snapshot # Snapshot interactive elements, assign refs
  87. gsd-browser snapshot --selector "form" # Scope to a CSS selector
  88. gsd-browser snapshot --mode <mode> # Semantic mode (see below)
  89. gsd-browser snapshot --limit 80 # Increase element limit (default: 40)
  90. # Use refs — all positional
  91. gsd-browser get-ref <ref> # Get metadata for a ref
  92. gsd-browser click-ref <ref> # Click element by ref
  93. gsd-browser hover-ref <ref> # Hover element by ref
  94. gsd-browser fill-ref <ref> <text> # Type into element by ref
  95. ```
  96. **Snapshot modes** (`--mode`):
  97. | Mode | What it captures |
  98. |------|-----------------|
  99. | `interactive` | Buttons, inputs, links, selects (default) |
  100. | `form` | Form fields with labels and current values |
  101. | `dialog` | Elements inside open dialogs/modals |
  102. | `navigation` | Links and nav elements |
  103. | `errors` | Error messages, validation warnings |
  104. | `headings` | Heading elements (h1-h6) for page structure |
  105. | `visible_only` | All visible elements regardless of interactivity |
  106. ### Inspection
  107. ```bash
  108. gsd-browser accessibility-tree # Full accessibility tree (roles, names, states)
  109. gsd-browser find --text "Sign In" # Find elements by text (case-insensitive)
  110. gsd-browser find --role button # Find by ARIA role
  111. gsd-browser find --selector ".my-class" # Find by CSS selector
  112. gsd-browser find --role link --limit 50 # Increase limit (default: 20)
  113. gsd-browser page-source # Get raw HTML of page
  114. gsd-browser page-source --selector "main" # Scoped HTML source
  115. gsd-browser eval '<js-expression>' # Evaluate JavaScript in page context
  116. ```
  117. ### Assertions
  118. Run explicit pass/fail checks against the current page state. Prefer this over inferring success from output.
  119. ```bash
  120. gsd-browser assert --checks '[
  121. {"kind": "url_contains", "text": "/dashboard"},
  122. {"kind": "text_visible", "text": "Welcome"},
  123. {"kind": "selector_visible", "selector": "#user-menu"},
  124. {"kind": "value_equals", "selector": "input[name=email]", "value": "user@test.com"},
  125. {"kind": "no_console_errors"},
  126. {"kind": "no_failed_requests"}
  127. ]'
  128. ```
  129. **Assertion kinds (17):** `url_contains`, `text_visible`, `text_hidden`, `selector_visible`, `selector_hidden`, `value_equals`, `checked`, `no_console_errors`, `no_failed_requests`, `request_url_seen`, `response_status`, `console_message_matches`, `network_count`, `console_count`, `element_count`, `no_console_errors_since`, `no_failed_requests_since`.
  130. ### Batch Execution
  131. Execute multiple steps in one call to reduce round trips. Stops on first failure by default.
  132. ```bash
  133. gsd-browser batch --steps '[
  134. {"action": "navigate", "url": "https://example.com"},
  135. {"action": "wait_for", "condition": "network_idle"},
  136. {"action": "click", "selector": "#login-btn"},
  137. {"action": "type", "selector": "input[name=email]", "text": "user@test.com"},
  138. {"action": "type", "selector": "input[name=password]", "text": "secret", "submit": true},
  139. {"action": "assert", "checks": [{"kind": "url_contains", "text": "/dashboard"}]}
  140. ]'
  141. # With --summary-only to reduce output
  142. gsd-browser batch --steps '[...]' --summary-only
  143. ```
  144. **Batch actions:** `navigate`, `click`, `type`, `key_press`, `wait_for`, `assert`, `click_ref`, `fill_ref`.
  145. ### Wait Conditions
  146. ```bash
  147. gsd-browser wait-for --condition selector_visible --value "#content"
  148. gsd-browser wait-for --condition selector_hidden --value ".spinner"
  149. gsd-browser wait-for --condition url_contains --value "/dashboard"
  150. gsd-browser wait-for --condition network_idle
  151. gsd-browser wait-for --condition delay --value 2000
  152. gsd-browser wait-for --condition text_visible --value "Success"
  153. gsd-browser wait-for --condition text_hidden --value "Loading"
  154. gsd-browser wait-for --condition request_completed --value "/api/data"
  155. gsd-browser wait-for --condition console_message --value "ready"
  156. gsd-browser wait-for --condition element_count --value ".item" --threshold ">=5"
  157. gsd-browser wait-for --condition region_stable --value "#content"
  158. # Custom timeout (default: 10000ms)
  159. gsd-browser wait-for --condition selector_visible --value "#slow" --timeout 30000
  160. ```
  161. ### Forms (Smart Fill)
  162. Analyze forms and fill them by field label, name, placeholder, or aria-label — no selectors needed.
  163. ```bash
  164. # Analyze form structure
  165. gsd-browser analyze-form
  166. gsd-browser analyze-form --selector "#signup-form"
  167. # Fill by field identifiers (resolved: label -> name -> placeholder -> aria-label)
  168. gsd-browser fill-form --values '{"Email": "a@b.com", "Password": "secret", "Country": "US"}'
  169. gsd-browser fill-form --values '{"Email": "a@b.com"}' --submit # Fill and click submit
  170. gsd-browser fill-form --values '{"Email": "a@b.com"}' --selector "#login-form"
  171. ```
  172. ### Intent-Based Interaction
  173. Find and act on elements by semantic intent — no selectors or refs needed. Intents are predefined categories, not free-form text.
  174. ```bash
  175. # Find top candidates for an intent (returns scored matches with selectors)
  176. gsd-browser find-best --intent submit_form
  177. gsd-browser find-best --intent accept_cookies
  178. gsd-browser find-best --intent primary_cta --scope "#modal"
  179. # Act: find best match and click/focus it in one call
  180. gsd-browser act --intent submit_form
  181. gsd-browser act --intent accept_cookies
  182. gsd-browser act --intent fill_email
  183. ```
  184. **Intents (15):**
  185. | Intent | Action | Description |
  186. |--------|--------|-------------|
  187. | `submit_form` | click | Submit buttons, form actions |
  188. | `close_dialog` | click | Modal/dialog close buttons |
  189. | `primary_cta` | click | Primary call-to-action elements |
  190. | `search_field` | focus | Search inputs and searchboxes |
  191. | `next_step` | click | Next/continue/proceed buttons |
  192. | `dismiss` | click | Dismiss overlays, banners, toasts |
  193. | `auth_action` | click | Login/signup/register buttons |
  194. | `back_navigation` | click | Back/previous navigation links |
  195. | `fill_email` | focus | Email input fields |
  196. | `fill_password` | focus | Password input fields |
  197. | `fill_username` | focus | Username/login input fields |
  198. | `accept_cookies` | click | Cookie consent accept buttons |
  199. | `main_content` | click | Main content area (`<main>`, `<article>`, semantic markup required) |
  200. | `pagination_next` | click | Next page in pagination |
  201. | `pagination_prev` | click | Previous page in pagination |
  202. ### Pages & Frames
  203. Page and frame IDs are **positional** — do NOT use `--id`.
  204. ```bash
  205. gsd-browser list-pages # List all open tabs
  206. gsd-browser switch-page <id> # Switch to tab by ID (positional)
  207. gsd-browser close-page <id> # Close a tab by ID (positional)
  208. gsd-browser list-frames # List all frames (main + iframes)
  209. gsd-browser select-frame --name "iframe-name" # Select frame by name
  210. gsd-browser select-frame --url-pattern "embed" # Select frame by URL substring
  211. gsd-browser select-frame --index 0 # Select by index
  212. gsd-browser select-frame --name main # Return to main frame
  213. ```
  214. ### Diagnostics
  215. ```bash
  216. gsd-browser console # Get console log entries (clears buffer)
  217. gsd-browser console --no-clear # Read without clearing
  218. gsd-browser network # Get network log entries
  219. gsd-browser dialog # Get dialog events (alert, confirm, prompt)
  220. gsd-browser timeline # Query the action timeline
  221. gsd-browser session-summary # Diagnostic summary of current session
  222. gsd-browser debug-bundle # Full debug bundle: screenshot + logs + timeline + a11y tree
  223. ```
  224. ### Live Viewer & Workbench
  225. The live viewer is a localhost screen-sharing and control surface for the active browser session. It prints or opens a tokenized URL bound to the session, viewer id, local origin, expiry, and capabilities. The viewer displays live frames, narrated action history, ref overlays, target rings, click ripples, failure markers, and page-following across navigation or tab changes.
  226. ```bash
  227. gsd-browser view # Open the live viewer
  228. gsd-browser view --print-only # Print tokenized URL only
  229. gsd-browser view --interactive # Interactive local workbench
  230. gsd-browser view --history # Open history-focused viewer
  231. gsd-browser view --history --print-only # Print history URL only
  232. gsd-browser goal "Find the checkout button" # Set viewer goal banner
  233. gsd-browser goal --clear # Clear goal banner
  234. gsd-browser control-state # Show shared owner/mode/version
  235. gsd-browser takeover # Give page input to the viewer
  236. gsd-browser release-control # Return page input to the agent
  237. gsd-browser pause # Pause before next narrated action
  238. gsd-browser resume # Resume actions
  239. gsd-browser step # Allow one action, then pause
  240. gsd-browser abort # Abort next gated action
  241. gsd-browser sensitive-on # Local human control with redaction
  242. gsd-browser sensitive-off # Leave sensitive mode
  243. ```
  244. Use one named session for the whole shared-screen flow:
  245. ```bash
  246. gsd-browser --session demo navigate https://example.com
  247. gsd-browser --session demo view --print-only
  248. gsd-browser --session demo click "h1"
  249. ```
  250. Viewer controls:
  251. | Control | Effect |
  252. |---------|--------|
  253. | Control | Forwards pointer, wheel, keyboard, text, and paste input to Chrome |
  254. | Annotate | Creates point annotations without forwarding page input |
  255. | Record | Starts or stops a local recording bundle |
  256. | Sensitive | Keeps local viewer control active and applies redaction policy |
  257. | Pause | Blocks agent page input |
  258. | Resume | Allows actions to continue |
  259. | Step | Allows one action, then returns to paused mode |
  260. | Abort | Aborts the next gated action |
  261. | Refs overlay | Shows or hides target boxes/labels |
  262. Keyboard shortcuts: Space pauses/resumes, Right Arrow steps, Escape aborts, `R` toggles refs.
  263. Risky visible targets such as destructive labels, payment actions, OAuth grants, credential entry, file transfer, production/admin surfaces, and cross-origin navigation produce an approval banner. Approval dispatches the exact pending command stored by the daemon.
  264. Annotations:
  265. ```bash
  266. gsd-browser annotations
  267. gsd-browser annotation-get <id>
  268. gsd-browser annotation-clear <id>
  269. gsd-browser annotation-clear --all
  270. gsd-browser annotation-resolve <id>
  271. gsd-browser annotation-export --output annotations.json
  272. gsd-browser annotation-request "Select the button to restyle"
  273. ```
  274. Recording bundles:
  275. ```bash
  276. gsd-browser record-start --name checkout-bug
  277. gsd-browser record-stop
  278. gsd-browser record-pause
  279. gsd-browser record-resume
  280. gsd-browser recordings
  281. gsd-browser recording-get <id>
  282. gsd-browser recording-export <id> --output <path>
  283. gsd-browser recording-discard <id>
  284. gsd-browser recording-validate <id-or-path> --json
  285. ```
  286. Viewer annotations and recording bundles are local daemon artifacts. Recording manifests use `BrowserArtifactBundleV1`, ordered JSONL events, redaction metadata, and local artifact directories under the browser state path.
  287. Use `--no-narration-delay` for fast agent-only runs that keep narration events/history without lead-time sleeps:
  288. ```bash
  289. gsd-browser --session demo --no-narration-delay click "h1"
  290. ```
  291. ### Visual
  292. ```bash
  293. gsd-browser screenshot # Screenshot to stdout (JPEG base64)
  294. gsd-browser screenshot --output page.png # Write to file
  295. gsd-browser screenshot --format png # Force PNG format
  296. gsd-browser screenshot --full-page # Full scrollable page
  297. gsd-browser screenshot --selector "#hero" # Crop to element (always PNG)
  298. gsd-browser screenshot --quality 50 # JPEG quality 1-100 (default: 80)
  299. gsd-browser zoom-region --x 100 --y 200 --width 400 --height 300 # Capture region
  300. gsd-browser zoom-region --x 0 --y 0 --width 200 --height 200 --scale 3 # Upscale
  301. gsd-browser save-pdf # Save page as PDF (A4 default)
  302. gsd-browser save-pdf --output report.pdf # Custom output path
  303. gsd-browser save-pdf --format Letter # Page format: A4, Letter, Legal, Tabloid
  304. ```
  305. ### Visual Regression
  306. ```bash
  307. # First run: saves baseline screenshot
  308. gsd-browser visual-diff --name "homepage"
  309. # Subsequent runs: compare against baseline, report mismatch
  310. gsd-browser visual-diff --name "homepage"
  311. gsd-browser visual-diff --name "homepage" --threshold 0.05 # Stricter tolerance (0-1)
  312. gsd-browser visual-diff --selector "#hero" --name "hero" # Scope to element
  313. gsd-browser visual-diff --name "homepage" --update-baseline # Reset baseline
  314. ```
  315. ### Structured Data Extraction
  316. ```bash
  317. # Single item
  318. gsd-browser extract --schema '{
  319. "type": "object",
  320. "properties": {
  321. "title": {"_selector": "h1", "_attribute": "textContent"},
  322. "price": {"_selector": ".price", "_attribute": "textContent"},
  323. "image": {"_selector": "img.product", "_attribute": "src"}
  324. }
  325. }'
  326. # Array of items
  327. gsd-browser extract --selector ".product-card" --multiple --schema '{
  328. "type": "object",
  329. "properties": {
  330. "name": {"_selector": "h3", "_attribute": "textContent"},
  331. "price": {"_selector": ".price", "_attribute": "textContent"}
  332. }
  333. }'
  334. ```
  335. ### Network Mocking
  336. ```bash
  337. gsd-browser mock-route --url "**/api/users*" --body '[{"name":"Alice"}]' --status 200
  338. gsd-browser mock-route --url "**/api/data" --body '{"ok":true}' --delay 3000 # Slow response
  339. gsd-browser block-urls "**/analytics*" "**/ads*" # Block URL patterns (positional)
  340. gsd-browser clear-routes # Remove all mocks and blocks
  341. ```
  342. ### Device Emulation
  343. ```bash
  344. gsd-browser emulate-device <device-name> # Full device emulation (positional)
  345. gsd-browser emulate-device "iPhone 15"
  346. gsd-browser emulate-device "Pixel 7"
  347. gsd-browser emulate-device "iPad Pro 11"
  348. gsd-browser emulate-device list # Show all available presets
  349. ```
  350. **Warning:** Device emulation recreates the browser context — current page state and cookies are lost.
  351. ### State & Auth
  352. ```bash
  353. # Save/restore browser state (cookies, localStorage, sessionStorage)
  354. gsd-browser save-state --name "logged-in"
  355. gsd-browser restore-state --name "logged-in"
  356. # Auth vault (encrypted credentials)
  357. gsd-browser vault-save --profile github --url https://github.com/login \
  358. --username user --password "secret"
  359. gsd-browser vault-login --profile github
  360. gsd-browser vault-list # List profiles (no secrets shown)
  361. ```
  362. Vault encryption requires `GSD_BROWSER_VAULT_KEY` env var set **before the daemon starts**. If the daemon is already running, stop it first, set the var, then run your vault command.
  363. ### Tracing & Recording
  364. ```bash
  365. gsd-browser trace-start # Start CDP performance trace
  366. gsd-browser trace-start --name "checkout-flow" # Named trace
  367. gsd-browser trace-stop # Stop and write trace to disk
  368. gsd-browser trace-stop --name "checkout.json" # Custom output filename
  369. gsd-browser har-export # Export network as HAR 1.2 JSON
  370. gsd-browser har-export --filename "session.har" # Custom output path
  371. gsd-browser generate-test # Generate Playwright test from timeline
  372. gsd-browser generate-test --name "login-flow" --output tests/login.spec.ts
  373. ```
  374. ### Security
  375. ```bash
  376. gsd-browser check-injection # Scan for prompt injection in page content
  377. gsd-browser check-injection --include-hidden # Include hidden/invisible text (default: true)
  378. ```
  379. ### Action Cache
  380. Reduce repeated element lookups by caching intent-to-selector mappings.
  381. ```bash
  382. gsd-browser action-cache --action stats # Show cache metrics
  383. gsd-browser action-cache --action get --intent submit_form # Look up cached selector
  384. gsd-browser action-cache --action put --intent submit_form --selector "#submit-btn" --score 0.95
  385. gsd-browser action-cache --action clear # Flush cache
  386. ```
  387. ### Daemon Management
  388. The daemon auto-starts on browser commands. These are for explicit lifecycle control.
  389. ```bash
  390. gsd-browser daemon stop # Stop daemon (idempotent — safe on dead processes)
  391. gsd-browser daemon health # Health check (read-only, does not auto-start)
  392. gsd-browser daemon start # Explicit start (pre-warm browser before commands)
  393. gsd-browser update # Install the current release
  394. ```
  395. ---
  396. ## Global Options
  397. Available on all commands:
  398. | Flag | Description |
  399. |------|-------------|
  400. | `--json` | Output as JSON (use when parsing output programmatically) |
  401. | `--browser-path <path>` | Path to Chrome/Chromium binary |
  402. | `--cdp-url <url>` | Attach to an already-running Chrome (e.g. `http://localhost:9222`) |
  403. | `--session <name>` | Named session for parallel browser instances |
  404. | `--no-narration-delay` | Skip narration lead-time sleeps while keeping history/events |
  405. ---
  406. ## Error Recovery
  407. ### Stale refs
  408. ```
  409. Error: resolve_ref: JS evaluation failed: ref @v1:e3 not found
  410. ```
  411. Refs become stale after page changes. Fix: re-snapshot and use the new version.
  412. ```bash
  413. gsd-browser snapshot # Get fresh refs (@v2:eN)
  414. gsd-browser click-ref @v2:e1
  415. ```
  416. ### Click/type timeouts
  417. ```
  418. Error: click timed out after 10s for: #submit-btn
  419. ```
  420. The element may not be visible, may be behind an overlay, or may not exist. Try:
  421. ```bash
  422. gsd-browser find --selector "#submit-btn" # Verify element exists
  423. gsd-browser scroll --direction down # Scroll it into view
  424. gsd-browser wait-for --condition selector_visible --value "#submit-btn" # Wait for it
  425. gsd-browser click "#submit-btn" # Retry
  426. ```
  427. ### Empty console/network logs
  428. Console and network buffers start fresh each navigation. If you need logs from a specific action, check them **before** navigating away:
  429. ```bash
  430. gsd-browser navigate https://example.com
  431. gsd-browser eval "fetch('/api/data')"
  432. gsd-browser network # Check network BEFORE navigating away
  433. ```
  434. ### Cookie banners / overlays blocking interaction
  435. Many sites show consent banners that block clicks. Dismiss them first:
  436. ```bash
  437. gsd-browser act --intent accept_cookies # Auto-find and click accept button
  438. gsd-browser act --intent dismiss # Or dismiss generic overlays
  439. ```
  440. ### Session is stopped, unhealthy, or opens a fresh blank page
  441. If `daemon health` reports `stopped` or `unhealthy`, or a named session no longer has the page you expected, that session does not currently map to a live daemon/browser pair.
  442. ```bash
  443. gsd-browser --session site1 daemon health
  444. gsd-browser --session site1 daemon stop
  445. gsd-browser --session site1 navigate https://example.com
  446. ```
  447. Use the same `--session` value on every follow-up command. `batch` is still useful for atomic flows, but separate invocations are supported when the session is healthy.
  448. ### Daemon won't start
  449. ```
  450. Error: daemon did not start within 10s
  451. ```
  452. Usually the session is unhealthy, startup exited early, or browser launch state is stale. Fix:
  453. ```bash
  454. gsd-browser daemon health # Inspect current state
  455. gsd-browser daemon stop # Clear the current session state
  456. gsd-browser daemon start # Retry explicit startup
  457. ```
  458. ---
  459. ## Common Patterns
  460. ### Form Submission
  461. ```bash
  462. gsd-browser navigate https://example.com/signup
  463. gsd-browser analyze-form # Discover field labels and types
  464. gsd-browser fill-form --values '{"Full Name": "Jane Doe", "Email": "jane@example.com", "State": "California"}' --submit
  465. gsd-browser wait-for --condition network_idle
  466. gsd-browser assert --checks '[{"kind": "text_visible", "text": "Welcome"}]'
  467. ```
  468. ### Login Flow (Refs)
  469. ```bash
  470. gsd-browser navigate https://app.example.com/login
  471. gsd-browser act --intent accept_cookies # Dismiss cookie banner if present
  472. gsd-browser snapshot
  473. # Read snapshot output to find email, password, and submit refs
  474. gsd-browser fill-ref @v1:e1 "$USERNAME"
  475. gsd-browser fill-ref @v1:e2 "$PASSWORD"
  476. gsd-browser click-ref @v1:e3
  477. gsd-browser wait-for --condition url_contains --value "/dashboard"
  478. gsd-browser save-state --name "myapp-auth" # Save for reuse
  479. ```
  480. ### Login Flow (Vault)
  481. ```bash
  482. # Save credentials once (encrypted at rest)
  483. gsd-browser vault-save --profile myapp \
  484. --url https://app.example.com/login \
  485. --username user@example.com \
  486. --password "$PASSWORD"
  487. # Login in any future session
  488. gsd-browser vault-login --profile myapp
  489. gsd-browser wait-for --condition url_contains --value "/dashboard"
  490. ```
  491. ### Reuse Saved Auth
  492. ```bash
  493. gsd-browser restore-state --name "myapp-auth"
  494. gsd-browser navigate https://app.example.com/dashboard # Already logged in
  495. ```
  496. ### Data Scraping
  497. ```bash
  498. gsd-browser navigate https://example.com/products
  499. gsd-browser extract --selector ".product" --multiple --schema '{
  500. "type": "object",
  501. "properties": {
  502. "name": {"_selector": ".title", "_attribute": "textContent"},
  503. "price": {"_selector": ".price", "_attribute": "textContent"},
  504. "link": {"_selector": "a", "_attribute": "href"}
  505. }
  506. }'
  507. ```
  508. ### Visual Regression Testing
  509. ```bash
  510. # Establish baseline (first run)
  511. gsd-browser navigate https://example.com
  512. gsd-browser visual-diff --name "home-page"
  513. # Later: compare current state
  514. gsd-browser navigate https://example.com
  515. gsd-browser visual-diff --name "home-page"
  516. # Output: similarity %, diff pixel count, diff image path
  517. ```
  518. ### Network Mocking for Testing
  519. ```bash
  520. gsd-browser mock-route --url "**/api/users" --body '{"error":"server error"}' --status 500
  521. gsd-browser navigate https://app.example.com
  522. gsd-browser assert --checks '[{"kind": "text_visible", "text": "Something went wrong"}]'
  523. gsd-browser clear-routes # Clean up mocks
  524. ```
  525. ### Parallel Sessions
  526. ```bash
  527. gsd-browser --session site1 navigate https://site-a.com
  528. gsd-browser --session site2 navigate https://site-b.com
  529. gsd-browser --session site1 snapshot
  530. gsd-browser --session site2 snapshot
  531. # Clean up both
  532. gsd-browser --session site1 daemon stop
  533. gsd-browser --session site2 daemon stop
  534. ```
  535. ### Performance Audit
  536. ```bash
  537. gsd-browser navigate https://example.com
  538. gsd-browser trace-start --name "perf-audit"
  539. # ... interact with the page ...
  540. gsd-browser trace-stop --name "perf-audit.json"
  541. gsd-browser har-export --filename "network.har"
  542. ```
  543. ### Prompt Injection Scanning
  544. ```bash
  545. gsd-browser navigate https://untrusted-page.com
  546. gsd-browser check-injection
  547. # Returns severity-rated findings for visible and hidden injection patterns
  548. ```
  549. ---
  550. ## Configuration
  551. ### Config Files (TOML)
  552. gsd-browser loads config with 5-layer merge precedence:
  553. 1. Compiled defaults
  554. 2. User config: `~/.gsd-browser/config.toml`
  555. 3. Project config: `./gsd-browser.toml`
  556. 4. Environment variables: `GSD_BROWSER_*`
  557. 5. CLI flags (highest priority)
  558. Example `gsd-browser.toml`:
  559. ```toml
  560. [browser]
  561. path = "/usr/bin/chromium"
  562. [daemon]
  563. port = 9222
  564. host = "127.0.0.1"
  565. [screenshot]
  566. quality = 90
  567. format = "png"
  568. full_page = false
  569. [settle]
  570. timeout_ms = 500
  571. poll_ms = 40
  572. quiet_window_ms = 100
  573. [logs]
  574. max_buffer_size = 1000
  575. [artifacts]
  576. dir = "./browser-artifacts"
  577. [timeline]
  578. max_entries = 500
  579. ```
  580. ### Environment Variables
  581. Supported config overrides use `GSD_BROWSER_<SECTION>_<FIELD>` naming:
  582. ```bash
  583. GSD_BROWSER_BROWSER_PATH=/usr/bin/chromium
  584. GSD_BROWSER_DAEMON_PORT=9223
  585. GSD_BROWSER_SCREENSHOT_QUALITY=90
  586. GSD_BROWSER_SETTLE_TIMEOUT_MS=1000
  587. GSD_BROWSER_VAULT_KEY=your-encryption-key
  588. ```
  589. ---
  590. ## Session Cleanup
  591. Always stop the daemon when done to avoid leaked Chrome processes:
  592. ```bash
  593. gsd-browser daemon stop
  594. ```
  595. For parallel sessions:
  596. ```bash
  597. gsd-browser --session agent1 daemon stop
  598. gsd-browser --session agent2 daemon stop
  599. ```
README.md · README · 219 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # gsd-browser
  2. Native Rust browser automation CLI for Chrome/Chromium via CDP. `gsd-browser` keeps a persistent background daemon, auto-starts on first use, and exposes 92 top-level commands for navigation, interaction, authenticated live viewing, annotations, recording bundles, snapshots with versioned refs, assertions, structured extraction, network control, visual diffing, tracing, and stateful auth flows.
  3. Built for AI agents, CI pipelines, and developers who want deterministic browser control without adopting a full browser test framework.
  4. ## Install
  5. ### Recommended: installer (macOS / Linux)
  6. ```bash
  7. curl -fsSL https://install.gsd.build/browser | bash
  8. ```
  9. The installer downloads the correct `gsd-browser` binary for your platform. If Chrome or Chromium is already installed, it uses that. Otherwise it downloads Chromium automatically when Chrome for Testing is available for your platform.
  10. Run `gsd-browser update` to install the current release.
  11. ### Pre-built binaries
  12. Download from [GitHub Releases](https://github.com/gsd-build/gsd-browser/releases):
  13. | Platform | Asset |
  14. |----------|-------|
  15. | macOS (Apple Silicon) | `gsd-browser-darwin-arm64` |
  16. | macOS (Intel) | `gsd-browser-darwin-x64` |
  17. | Linux (ARM64) | `gsd-browser-linux-arm64` |
  18. | Linux (x64) | `gsd-browser-linux-x64` |
  19. ### Build from source
  20. ```bash
  21. git clone https://github.com/gsd-build/gsd-browser.git
  22. cd gsd-browser
  23. cargo install --path cli
  24. ```
  25. ### Package registries
  26. The public npm package (`@gsd-build/gsd-browser`) and crates.io package (`gsd-browser`) are not published yet. Use the installer, GitHub release assets, or a source build.
  27. ## Quick Start
  28. The daemon starts automatically on first use.
  29. ```bash
  30. # Navigate to a page
  31. gsd-browser navigate https://example.com
  32. # Snapshot interactive elements and assign refs like @v1:e1
  33. gsd-browser snapshot
  34. # On example.com the only interactive element is the "More information..." link
  35. gsd-browser click-ref @v1:e1
  36. # Wait for navigation and assert the result
  37. gsd-browser wait-for --condition network_idle
  38. gsd-browser assert --checks '[{"kind":"url_contains","text":"iana.org"}]'
  39. # Capture a PNG
  40. gsd-browser screenshot --output page.png --format png
  41. ```
  42. ## Interactive Workbench
  43. `gsd-browser view` starts an authenticated localhost workbench for the active session. The URL is bound to the session, viewer id, loopback origin, expiry, and viewer capabilities. Use `view --print-only` when another tool needs the URL.
  44. ```bash
  45. gsd-browser view
  46. gsd-browser view --print-only
  47. gsd-browser control-state
  48. gsd-browser takeover
  49. gsd-browser release-control
  50. gsd-browser sensitive-on
  51. gsd-browser sensitive-off
  52. ```
  53. The viewer streams the real Chrome page, forwards pointer, wheel, keyboard, text, and paste input while in Control mode, creates annotations in Annotate mode, and starts/stops local recording bundles in Record mode. Sensitive mode keeps local human control available while cloud frame capture and evidence surfaces use redaction policy.
  54. Annotations and recordings stay local to the daemon state directory:
  55. ```bash
  56. gsd-browser annotations
  57. gsd-browser annotation-get <id>
  58. gsd-browser annotation-clear <id>
  59. gsd-browser annotation-resolve <id>
  60. gsd-browser annotation-export --output annotations.json
  61. gsd-browser record-start --name checkout-bug
  62. gsd-browser record-stop
  63. gsd-browser recordings
  64. gsd-browser recording-get <id>
  65. gsd-browser recording-export <id> --output <path>
  66. gsd-browser recording-discard <id>
  67. gsd-browser recording-validate <id-or-path> --json
  68. ```
  69. ## Command Surface
  70. `gsd-browser` currently exposes 92 top-level commands:
  71. | Area | Commands |
  72. |------|----------|
  73. | Navigation | `navigate`, `back`, `forward`, `reload` |
  74. | Logs & JavaScript | `console`, `network`, `dialog`, `eval` |
  75. | Interaction | `click`, `type`, `press`, `hover`, `scroll`, `select-option`, `set-checked`, `drag`, `set-viewport`, `upload-file` |
  76. | Inspection | `accessibility-tree`, `find`, `page-source` |
  77. | Waits | `wait-for` |
  78. | Snapshots & refs | `snapshot`, `get-ref`, `click-ref`, `hover-ref`, `fill-ref` |
  79. | Assertions & batching | `assert`, `diff`, `batch` |
  80. | Pages & frames | `list-pages`, `switch-page`, `close-page`, `list-frames`, `select-frame` |
  81. | Forms & semantic actions | `analyze-form`, `fill-form`, `find-best`, `act` |
  82. | Live workbench | `goal`, `view`, `control-state`, `takeover`, `release-control`, `pause`, `resume`, `step`, `abort`, `sensitive-on`, `sensitive-off` |
  83. | Annotations | `annotations`, `annotation-get`, `annotation-clear`, `annotation-resolve`, `annotation-export`, `annotation-request` |
  84. | Recording bundles | `record-start`, `record-stop`, `record-pause`, `record-resume`, `recordings`, `recording-get`, `recording-export`, `recording-discard`, `recording-validate` |
  85. | Diagnostics | `timeline`, `session-summary`, `debug-bundle` |
  86. | Screenshots & document output | `screenshot`, `zoom-region`, `save-pdf` |
  87. | Visual regression | `visual-diff` |
  88. | Structured extraction | `extract` |
  89. | Network control | `mock-route`, `block-urls`, `clear-routes` |
  90. | Device & browser state | `emulate-device`, `save-state`, `restore-state` |
  91. | Auth vault | `vault-save`, `vault-login`, `vault-list` |
  92. | Recording & traces | `generate-test`, `har-export`, `trace-start`, `trace-stop` |
  93. | Safety, caching & daemon management | `action-cache`, `check-injection`, `daemon` |
  94. ## Highlights
  95. - Persistent daemon with automatic startup for fast repeated commands
  96. - Durable named sessions with explicit health reporting and no silent session replacement
  97. - Versioned refs from `snapshot` for deterministic interaction (`@v1:e1`, `@v2:e3`)
  98. - Explicit assertions with `assert` and multi-step automation with `batch`
  99. - Shared inspection semantics across `snapshot`, `find`, `wait-for`, `assert`, and ref-driven actions
  100. - Semantic `find-best` and `act` flows covering 15 built-in intents
  101. - Named sessions via `--session` for isolated parallel browser workers
  102. - Authenticated local viewer with human takeover, pause/step/abort, annotations, sensitive mode, and bounded recording bundles
  103. - Structured JSON output on every command via `--json`
  104. - Visual diffing, HAR export, PDF generation, and CDP tracing in the same tool
  105. - Saved browser state plus encrypted credential replay through the auth vault
  106. - Prompt injection scanning for agent-facing browsing workflows
  107. ## Configuration
  108. `gsd-browser` merges configuration in this order:
  109. 1. Built-in defaults
  110. 2. User config: `~/.gsd-browser/config.toml`
  111. 3. Project config: `./gsd-browser.toml`
  112. 4. Environment variables: `GSD_BROWSER_*`
  113. 5. CLI flags
  114. Example `gsd-browser.toml`:
  115. ```toml
  116. [browser]
  117. path = "/usr/bin/chromium"
  118. cdp_url = "http://localhost:9222" # attach to existing Chrome instead of launching
  119. headless = true
  120. [daemon]
  121. port = 9222
  122. host = "127.0.0.1"
  123. [screenshot]
  124. quality = 90
  125. format = "png"
  126. full_page = false
  127. [settle]
  128. timeout_ms = 500
  129. poll_ms = 40
  130. quiet_window_ms = 100
  131. [logs]
  132. max_buffer_size = 1000
  133. [artifacts]
  134. dir = "./browser-artifacts"
  135. [timeline]
  136. enabled = true
  137. max_entries = 500
  138. ```
  139. Supported environment variable overrides use `GSD_BROWSER_<SECTION>_<FIELD>` naming:
  140. ```bash
  141. export GSD_BROWSER_BROWSER_PATH=/usr/bin/chromium
  142. export GSD_BROWSER_BROWSER_CDP_URL=http://localhost:9222
  143. export GSD_BROWSER_BROWSER_HEADLESS=true
  144. export GSD_BROWSER_DAEMON_PORT=9333
  145. export GSD_BROWSER_SCREENSHOT_QUALITY=90
  146. export GSD_BROWSER_SETTLE_TIMEOUT_MS=1000
  147. export GSD_BROWSER_ARTIFACTS_DIR=./browser-artifacts
  148. export GSD_BROWSER_VAULT_KEY=your-encryption-key
  149. ```
  150. ## How It Works
  151. - The CLI parses commands and sends them to a local daemon over a loopback HTTP channel.
  152. - The daemon maintains the browser lifecycle, page/frame routing, network hooks, action timeline, and session manifest state.
  153. - `--session <name>` creates isolated daemon and browser instances for parallel workflows.
  154. ## For AI Agents
  155. - The daemon auto-starts. You almost never need `gsd-browser daemon start`.
  156. - `gsd-browser daemon health` reports the current session state and does not auto-start the daemon.
  157. - Use `--json` when you need structured output.
  158. - Prefer `snapshot` then `click-ref` or `fill-ref` for stable interaction, and re-snapshot after page changes.
  159. - Use `assert` and `batch` when you need deterministic pass/fail automation.
  160. - `find-best` and `act` cover 15 built-in semantic intents for common navigation, form, dialog, auth, and pagination actions.
  161. - Read [SKILL.md](./SKILL.md) for the full command reference and workflow patterns.
  162. ## License
  163. Licensed under either of:
  164. - [MIT License](LICENSE-MIT)
  165. - [Apache License, Version 2.0](LICENSE-APACHE)
  166. at your option.
install.sh · Bundled script · 578 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. set -euo pipefail
  3. # gsd-browser installer
  4. # Usage: curl -fsSL https://install.gsd.build/browser | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 5 on GitHub
  5. #
  6. # Environment variables (advanced):
  7. # GSD_BROWSER_VERSION - install a specific version (default: latest)
  8. # GSD_BROWSER_DIR - override install directory (default: $HOME/.gsd-browser)
  9. # GSD_BROWSER_INSTALL_MODE - install or update (default: install)
  10. # GSD_BROWSER_SKIP_CHROMIUM - skip Chrome/Chromium setup when set to 1
  11. # GSD_BROWSER_SKIP_SKILL - skip AI agent skill installation when set to 1
  12. VERSION="${GSD_BROWSER_VERSION:-latest}"
  13. REPO="gsd-build/gsd-browser"
  14. INSTALL_DIR="${GSD_BROWSER_DIR:-$HOME/.gsd-browser}"
  15. BIN_DIR="$INSTALL_DIR/bin"
  16. CHROMIUM_DIR="$INSTALL_DIR/chromium"
  17. INSTALL_MODE="${GSD_BROWSER_INSTALL_MODE:-install}"
  18. SKIP_CHROMIUM="${GSD_BROWSER_SKIP_CHROMIUM:-0}"
  19. SKIP_SKILL="${GSD_BROWSER_SKIP_SKILL:-0}"
  20. # Colors
  21. cyan="\033[36m"
  22. green="\033[32m"
  23. yellow="\033[33m"
  24. red="\033[31m"
  25. dim="\033[2m"
  26. bold="\033[1m"
  27. reset="\033[0m"
  28. banner() {
  29. echo ""
  30. printf "${cyan}${bold}"
  31. echo " ██████╗ ███████╗██████╗ ██████╗ ██████╗ ██████╗ ██╗ ██╗███████╗███████╗██████╗ "
  32. echo " ██╔════╝ ██╔════╝██╔══██╗ ██╔══██╗██╔══██╗██╔═══██╗██║ ██║██╔════╝██╔════╝██╔══██╗"
  33. echo " ██║ ███╗███████╗██║ ██║█████╗██████╔╝██████╔╝██║ ██║██║ █╗ ██║███████╗█████╗ ██████╔╝"
  34. echo " ██║ ██║╚════██║██║ ██║╚════╝██╔══██╗██╔══██╗██║ ██║██║███╗██║╚════██║██╔══╝ ██╔══██╗"
  35. echo " ╚██████╔╝███████║██████╔╝ ██████╔╝██║ ██║╚██████╔╝╚███╔███╔╝███████║███████╗██║ ██║"
  36. echo " ╚═════╝ ╚══════╝╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══╝╚══╝ ╚══════╝╚══════╝╚═╝ ╚═╝"
  37. printf "${reset}\n"
  38. printf " ${dim}Browser automation for AI agents${reset}\n\n"
  39. }
  40. info() { printf " ${cyan}>${reset} %s\n" "$1"; }
  41. ok() { printf " ${green}✓${reset} %s\n" "$1"; }
  42. warn() { printf " ${yellow}!${reset} %s\n" "$1"; }
  43. fail() { printf " ${red}✗${reset} %s\n" "$1"; exit 1; }
  44. parse_args() {
  45. for arg in "$@"; do
  46. case "$arg" in
  47. --update)
  48. INSTALL_MODE="update"
  49. SKIP_CHROMIUM=1
  50. SKIP_SKILL=1
  51. ;;
  52. --skip-chromium)
  53. SKIP_CHROMIUM=1
  54. ;;
  55. --skip-skill)
  56. SKIP_SKILL=1
  57. ;;
  58. *)
  59. fail "Unknown option: $arg"
  60. ;;
  61. esac
  62. done
  63. case "$INSTALL_MODE" in
  64. install|update) ;;
  65. *) fail "Invalid GSD_BROWSER_INSTALL_MODE: $INSTALL_MODE" ;;
  66. esac
  67. }
  68. detect_platform() {
  69. local os arch
  70. os="$(uname -s)"
  71. arch="$(uname -m)"
  72. case "$os" in
  73. Darwin) os="darwin" ;;
  74. Linux) os="linux" ;;
  75. *) fail "Unsupported OS: $os (Windows users: use WSL)" ;;
  76. esac
  77. case "$arch" in
  78. x86_64|amd64) arch="x64" ;;
  79. arm64|aarch64) arch="arm64" ;;
  80. *) fail "Unsupported architecture: $arch" ;;
  81. esac
  82. PLATFORM="${os}-${arch}"
  83. # Chrome for Testing platform names (different from ours)
  84. case "$PLATFORM" in
  85. darwin-arm64) CHROME_PLATFORM="mac-arm64" ;;
  86. darwin-x64) CHROME_PLATFORM="mac-x64" ;;
  87. linux-x64) CHROME_PLATFORM="linux64" ;;
  88. linux-arm64) CHROME_PLATFORM="" ;; # Not available
  89. *) CHROME_PLATFORM="" ;;
  90. esac
  91. }
  92. resolve_version() {
  93. if [ "$VERSION" = "latest" ]; then
  94. info "Fetching latest release..."
  95. VERSION=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" | grep '"tag_name"' | sed -E 's/.*"v?([^"]+)".*/\1/')
  96. if [ -z "$VERSION" ]; then
  97. fail "Could not determine latest version. Set GSD_BROWSER_VERSION manually."
  98. fi
  99. fi
  100. ok "Version: $VERSION"
  101. }
  102. download_binary() {
  103. local url filename
  104. filename="gsd-browser-${PLATFORM}"
  105. url="https://github.com/$REPO/releases/download/v${VERSION}/${filename}"
  106. info "Downloading gsd-browser for $PLATFORM..."
  107. mkdir -p "$BIN_DIR"
  108. local target="$BIN_DIR/gsd-browser"
  109. local tmp
  110. tmp="$(mktemp "$BIN_DIR/.gsd-browser.XXXXXX")"
  111. trap 'rm -f "$tmp"' EXIT
  112. if ! curl -fsSL -o "$tmp" "$url"; then
  113. rm -f "$tmp"
  114. fail "Download failed: $url"
  115. fi
  116. chmod +x "$tmp"
  117. mv -f "$tmp" "$target"
  118. chmod +x "$target"
  119. # On macOS, strip quarantine/provenance attributes added by curl, then verify
  120. # the Developer ID signature. Fall back to ad-hoc signing only if the binary
  121. # has no valid signature (manual builds, stripped signatures).
  122. if [ "$(uname -s)" = "Darwin" ]; then
  123. xattr -d com.apple.quarantine "$target" 2>/dev/null || true
  124. xattr -d com.apple.provenance "$target" 2>/dev/null || true
  125. if command -v codesign >/dev/null 2>&1; then
  126. if codesign --verify --strict "$target" 2>/dev/null; then
  127. if "$target" --version >/dev/null 2>&1; then
  128. ok "Binary signature verified (Developer ID)"
  129. else
  130. warn "Developer ID signature verifies but macOS refused to launch the binary"
  131. codesign --sign - --force "$target" 2>/dev/null && "$target" --version >/dev/null 2>&1 && {
  132. ok "Ad-hoc signed for macOS Gatekeeper"
  133. } || {
  134. warn "Ad-hoc signing failed — binary may be blocked by Gatekeeper"
  135. warn "Fix manually: codesign --sign - --force $target"
  136. }
  137. fi
  138. else
  139. codesign --sign - --force "$target" 2>/dev/null && {
  140. ok "Ad-hoc signed for macOS Gatekeeper"
  141. } || {
  142. warn "Ad-hoc signing failed — binary may be blocked by Gatekeeper"
  143. warn "Fix manually: codesign --sign - --force $target"
  144. }
  145. fi
  146. fi
  147. fi
  148. trap - EXIT
  149. ok "Binary installed: $target"
  150. }
  151. detect_existing_chrome() {
  152. # Check standard Chrome/Chromium locations — mirrors find_chrome() in common/src/chrome.rs
  153. local candidates=()
  154. case "$(uname -s)" in
  155. Darwin)
  156. candidates=(
  157. "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  158. )
  159. ;;
  160. Linux)
  161. candidates=(
  162. "/usr/bin/google-chrome"
  163. "/usr/bin/google-chrome-stable"
  164. "/usr/bin/chromium-browser"
  165. "/usr/bin/chromium"
  166. "/snap/bin/chromium"
  167. )
  168. ;;
  169. esac
  170. for path in "${candidates[@]}"; do
  171. if [ -x "$path" ]; then
  172. echo "$path"
  173. return 0
  174. fi
  175. done
  176. # Check PATH
  177. for name in google-chrome google-chrome-stable chromium-browser chromium; do
  178. if command -v "$name" >/dev/null 2>&1; then
  179. command -v "$name"
  180. return 0
  181. fi
  182. done
  183. return 1
  184. }
  185. download_chromium() {
  186. if [ "$SKIP_CHROMIUM" = "1" ]; then
  187. info "Skipping Chrome/Chromium setup"
  188. return
  189. fi
  190. if [ -z "$CHROME_PLATFORM" ]; then
  191. warn "Chromium not available for $PLATFORM via Chrome for Testing"
  192. warn "Install Chrome/Chromium manually and set GSD_BROWSER_BROWSER_PATH"
  193. return
  194. fi
  195. # Check if a system Chrome/Chromium is already available
  196. local system_chrome
  197. if system_chrome=$(detect_existing_chrome); then
  198. ok "Found Chrome at: $system_chrome (skipping download)"
  199. SKIP_CHROMIUM_CONFIG=1
  200. return
  201. fi
  202. # Check if we previously downloaded Chrome for Testing
  203. if [ -f "$CHROMIUM_DIR/version" ]; then
  204. local existing
  205. existing=$(cat "$CHROMIUM_DIR/version")
  206. info "Chromium $existing already installed"
  207. read -rp " Reinstall? [y/N] " yn < /dev/tty || yn="n"
  208. case "$yn" in
  209. [Yy]*) ;;
  210. *) ok "Keeping existing Chromium"; return ;;
  211. esac
  212. fi
  213. info "Fetching Chrome for Testing metadata..."
  214. local json chrome_url chrome_version
  215. json=$(curl -fsSL "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json")
  216. chrome_version=$(echo "$json" | grep -o '"Stable"[^}]*"version":"[^"]*"' | head -1 | grep -o '"version":"[^"]*"' | cut -d'"' -f4)
  217. chrome_url=$(echo "$json" | python3 -c "
  218. import sys, json
  219. data = json.load(sys.stdin)
  220. for entry in data['channels']['Stable']['downloads']['chrome']:
  221. if entry['platform'] == '$CHROME_PLATFORM':
  222. print(entry['url'])
  223. break
  224. " 2>/dev/null || echo "")
  225. if [ -z "$chrome_url" ]; then
  226. warn "Could not find Chromium download for $CHROME_PLATFORM"
  227. return
  228. fi
  229. info "Downloading Chromium $chrome_version for $CHROME_PLATFORM..."
  230. mkdir -p "$CHROMIUM_DIR"
  231. local tmpzip="$CHROMIUM_DIR/chrome.zip"
  232. if ! curl -fsSL -o "$tmpzip" "$chrome_url"; then
  233. warn "Chromium download failed — you can install Chrome manually"
  234. rm -f "$tmpzip"
  235. return
  236. fi
  237. info "Extracting Chromium..."
  238. unzip -qo "$tmpzip" -d "$CHROMIUM_DIR"
  239. rm -f "$tmpzip"
  240. # Find the chrome binary inside the extracted directory
  241. local chrome_bin=""
  242. case "$CHROME_PLATFORM" in
  243. mac-arm64|mac-x64)
  244. chrome_bin=$(find "$CHROMIUM_DIR" -name "Google Chrome for Testing" -type f 2>/dev/null | head -1)
  245. if [ -z "$chrome_bin" ]; then
  246. chrome_bin=$(find "$CHROMIUM_DIR" -name "Chromium" -type f 2>/dev/null | head -1)
  247. fi
  248. ;;
  249. linux64)
  250. chrome_bin=$(find "$CHROMIUM_DIR" -name "chrome" -type f 2>/dev/null | head -1)
  251. ;;
  252. esac
  253. if [ -n "$chrome_bin" ]; then
  254. echo "$chrome_version" > "$CHROMIUM_DIR/version"
  255. echo "$chrome_bin" > "$CHROMIUM_DIR/binary_path"
  256. ok "Chromium $chrome_version installed"
  257. else
  258. warn "Chromium extracted but binary not found — check $CHROMIUM_DIR"
  259. fi
  260. }
  261. setup_path() {
  262. local target="/usr/local/bin/gsd-browser"
  263. local source="$BIN_DIR/gsd-browser"
  264. # Try symlink to /usr/local/bin
  265. if [ -w "/usr/local/bin" ] || [ -w "$(dirname /usr/local/bin)" ]; then
  266. ln -sf "$source" "$target" 2>/dev/null && {
  267. ok "Linked to $target"
  268. return
  269. }
  270. fi
  271. # Try with sudo
  272. if command -v sudo >/dev/null 2>&1; then
  273. info "Linking to /usr/local/bin (may need password)..."
  274. sudo ln -sf "$source" "$target" 2>/dev/null && {
  275. ok "Linked to $target"
  276. return
  277. }
  278. fi
  279. # Fallback: tell user to add to PATH
  280. warn "Could not link to /usr/local/bin"
  281. echo ""
  282. printf " Add this to your shell profile:\n"
  283. printf " ${bold}export PATH=\"$BIN_DIR:\$PATH\"${reset}\n"
  284. echo ""
  285. }
  286. write_config() {
  287. # If system Chrome was detected, no config needed — find_chrome() will discover it
  288. if [ "${SKIP_CHROMIUM_CONFIG:-}" = "1" ]; then
  289. return
  290. fi
  291. # If we downloaded Chromium, write a config pointing to it
  292. if [ -f "$CHROMIUM_DIR/binary_path" ]; then
  293. local chrome_path
  294. chrome_path=$(cat "$CHROMIUM_DIR/binary_path")
  295. local config_dir="$HOME/.gsd-browser"
  296. mkdir -p "$config_dir"
  297. cat > "$config_dir/config.toml" << TOML
  298. [browser]
  299. path = "$chrome_path"
  300. TOML
  301. ok "Config written: $config_dir/config.toml"
  302. fi
  303. }
  304. verify() {
  305. info "Verifying installation..."
  306. local bin=""
  307. if ! command -v gsd-browser >/dev/null 2>&1; then
  308. # Try the direct path
  309. if [ -x "$BIN_DIR/gsd-browser" ]; then
  310. bin="$BIN_DIR/gsd-browser"
  311. else
  312. warn "gsd-browser not in PATH yet — restart your shell or run: export PATH=\"$BIN_DIR:\$PATH\""
  313. return
  314. fi
  315. else
  316. bin="gsd-browser"
  317. fi
  318. "$bin" daemon stop >/dev/null 2>&1 || true
  319. if "$bin" daemon start >/dev/null 2>&1; then
  320. local health_output
  321. health_output=$("$bin" daemon health 2>&1 || true)
  322. if printf '%s\n' "$health_output" | grep -q '^Daemon: healthy$'; then
  323. if [ "$bin" = "$BIN_DIR/gsd-browser" ]; then
  324. ok "Daemon healthy (using direct path)"
  325. else
  326. ok "Daemon healthy"
  327. fi
  328. "$bin" daemon stop >/dev/null 2>&1 || true
  329. return
  330. fi
  331. fi
  332. "$bin" daemon stop >/dev/null 2>&1 || true
  333. warn "Daemon test failed — this is normal if Chrome is not in the default path"
  334. warn "Set browser.path in ~/.gsd-browser/config.toml"
  335. }
  336. SKILL_REPO_BASE="https://raw.githubusercontent.com/$REPO/main/gsd-browser-skill"
  337. SKILL_FILES=(
  338. "SKILL.md"
  339. "references/command-reference.md"
  340. "references/snapshot-and-refs.md"
  341. "references/semantic-intents.md"
  342. "references/configuration.md"
  343. "references/error-recovery.md"
  344. "workflows/scrape-and-extract.md"
  345. "workflows/setup-and-configure.md"
  346. "workflows/live-viewer-and-narration.md"
  347. "workflows/navigate-and-interact.md"
  348. "workflows/test-and-assert.md"
  349. "workflows/debug-and-diagnose.md"
  350. )
  351. install_skill_to() {
  352. local dest="$1"
  353. mkdir -p "$dest" "$dest/references" "$dest/workflows"
  354. local failed=0
  355. for file in "${SKILL_FILES[@]}"; do
  356. if ! curl -fsSL -o "$dest/$file" "$SKILL_REPO_BASE/$file" 2>/dev/null; then
  357. failed=1
  358. break
  359. fi
  360. done
  361. if [ "$failed" -eq 1 ]; then
  362. warn "Failed to download skill files — check network or repo access"
  363. rm -rf "$dest"
  364. return 1
  365. fi
  366. ok "Skill installed: $dest"
  367. return 0
  368. }
  369. install_skill() {
  370. if [ "$SKIP_SKILL" = "1" ]; then
  371. info "Skipping skill installation"
  372. return
  373. fi
  374. echo ""
  375. printf " ${cyan}${bold}AI Agent Skill Installation${reset}\n"
  376. printf " ${dim}Install the gsd-browser skill so your AI coding agent knows how to use it${reset}\n"
  377. echo ""
  378. # Detect available AI CLIs
  379. local available=()
  380. local labels=()
  381. if command -v claude >/dev/null 2>&1; then
  382. available+=("claude")
  383. labels+=("Claude Code")
  384. fi
  385. if command -v codex >/dev/null 2>&1; then
  386. available+=("codex")
  387. labels+=("OpenAI Codex CLI")
  388. fi
  389. if command -v gemini >/dev/null 2>&1; then
  390. available+=("gemini")
  391. labels+=("Google Gemini CLI")
  392. fi
  393. if [ ${#available[@]} -eq 0 ]; then
  394. info "No AI coding agents detected (claude, codex, gemini)"
  395. info "Install one, then re-run: gsd-browser skill install"
  396. return
  397. fi
  398. printf " Detected AI agents:\n"
  399. local idx=1
  400. for label in "${labels[@]}"; do
  401. printf " ${bold}%d)${reset} %s\n" "$idx" "$label"
  402. idx=$((idx + 1))
  403. done
  404. printf " ${bold}a)${reset} All detected agents\n"
  405. printf " ${bold}s)${reset} Skip\n"
  406. echo ""
  407. local choice
  408. read -rp " Install skill for which agent(s)? [a]: " choice < /dev/tty || choice="a"
  409. choice="${choice:-a}"
  410. if [ "$choice" = "s" ] || [ "$choice" = "S" ]; then
  411. info "Skipping skill installation"
  412. return
  413. fi
  414. # Build list of selected tools
  415. local selected=()
  416. if [ "$choice" = "a" ] || [ "$choice" = "A" ]; then
  417. selected=("${available[@]}")
  418. else
  419. # Parse comma-separated or single number
  420. IFS=',' read -ra nums <<< "$choice"
  421. for num in "${nums[@]}"; do
  422. num=$(echo "$num" | tr -d ' ')
  423. if [[ "$num" =~ ^[0-9]+$ ]] && [ "$num" -ge 1 ] && [ "$num" -le ${#available[@]} ]; then
  424. selected+=("${available[$((num - 1))]}")
  425. fi
  426. done
  427. fi
  428. if [ ${#selected[@]} -eq 0 ]; then
  429. warn "No valid selection — skipping skill installation"
  430. return
  431. fi
  432. # Ask scope
  433. echo ""
  434. printf " Install scope:\n"
  435. printf " ${bold}g)${reset} Global (available in all projects)\n"
  436. printf " ${bold}l)${reset} Local (current directory only)\n"
  437. echo ""
  438. local scope
  439. read -rp " Scope? [g]: " scope < /dev/tty || scope="g"
  440. scope="${scope:-g}"
  441. for tool in "${selected[@]}"; do
  442. local dest=""
  443. case "$tool" in
  444. claude)
  445. if [ "$scope" = "l" ] || [ "$scope" = "L" ]; then
  446. dest=".claude/skills/gsd-browser"
  447. else
  448. dest="$HOME/.claude/skills/gsd-browser"
  449. fi
  450. ;;
  451. codex)
  452. if [ "$scope" = "l" ] || [ "$scope" = "L" ]; then
  453. dest=".codex/skills/gsd-browser"
  454. else
  455. dest="$HOME/.codex/skills/gsd-browser"
  456. fi
  457. ;;
  458. gemini)
  459. if [ "$scope" = "l" ] || [ "$scope" = "L" ]; then
  460. dest=".gemini/skills/gsd-browser"
  461. else
  462. dest="$HOME/.gemini/skills/gsd-browser"
  463. fi
  464. ;;
  465. esac
  466. if [ -n "$dest" ]; then
  467. info "Installing skill for $tool → $dest"
  468. install_skill_to "$dest"
  469. fi
  470. done
  471. }
  472. main() {
  473. parse_args "$@"
  474. if [ "$INSTALL_MODE" = "update" ]; then
  475. echo ""
  476. printf " ${cyan}${bold}Updating gsd-browser${reset}\n\n"
  477. else
  478. banner
  479. fi
  480. detect_platform
  481. ok "Platform: $PLATFORM"
  482. resolve_version
  483. download_binary
  484. if [ "$INSTALL_MODE" = "update" ]; then
  485. verify
  486. echo ""
  487. printf " ${green}${bold}Update complete!${reset}\n"
  488. echo ""
  489. return
  490. fi
  491. download_chromium
  492. setup_path
  493. write_config
  494. verify
  495. install_skill
  496. echo ""
  497. printf " ${green}${bold}Installation complete!${reset}\n"
  498. echo ""
  499. printf " ${dim}Quick start:${reset}\n"
  500. printf " gsd-browser navigate https://example.com\n"
  501. printf " gsd-browser screenshot --output page.png\n"
  502. printf " gsd-browser snapshot\n"
  503. echo ""
  504. }
  505. main "$@"
npm/scripts/postinstall.js · Bundled script · 126 lines · 1 finding marked
  1. #!/usr/bin/env node
  2. "use strict";
  3. const fs = require("fs");
  4. const path = require("path");
  5. const https = require("https");
  6. const { execSync } = require("child_process");
  7. const REPO = "gsd-build/gsd-browser";
  8. const PLATFORM_MAP = {
  9. "darwin-arm64": "gsd-browser-darwin-arm64",
  10. "darwin-x64": "gsd-browser-darwin-x64",
  11. "linux-arm64": "gsd-browser-linux-arm64",
  12. "linux-x64": "gsd-browser-linux-x64",
  13. };
  14. function fetchJSON(url) {
  15. return new Promise((resolve, reject) => {
  16. https.get(url, { headers: { "User-Agent": "gsd-browser-npm" } }, (res) => {
  17. if (res.statusCode === 302 || res.statusCode === 301) {
  18. return fetchJSON(res.headers.location).then(resolve, reject);
  19. }
  20. if (res.statusCode !== 200) {
  21. return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
  22. }
  23. let data = "";
  24. res.on("data", (chunk) => (data += chunk));
  25. res.on("end", () => {
  26. try { resolve(JSON.parse(data)); }
  27. catch (e) { reject(e); }
  28. });
  29. }).on("error", reject);
  30. });
  31. }
  32. function downloadFile(url, dest) {
  33. return new Promise((resolve, reject) => {
  34. https.get(url, { headers: { "User-Agent": "gsd-browser-npm" } }, (res) => {
  35. if (res.statusCode === 302 || res.statusCode === 301) {
  36. return downloadFile(res.headers.location, dest).then(resolve, reject);
  37. }
  38. if (res.statusCode !== 200) {
  39. return reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
  40. }
  41. const file = fs.createWriteStream(dest);
  42. res.pipe(file);
  43. file.on("finish", () => { file.close(); resolve(); });
  44. }).on("error", reject);
  45. });
  46. }
  47. async function main() {
  48. const platform = process.platform;
  49. const arch = process.arch;
  50. const key = `${platform}-${arch}`;
  51. const binaryName = PLATFORM_MAP[key];
  52. if (!binaryName) {
  53. console.error(
  54. `gsd-browser: unsupported platform ${key}.\n` +
  55. `Supported: ${Object.keys(PLATFORM_MAP).join(", ")}`
  56. );
  57. process.exit(1);
  58. }
  59. const binDir = path.join(__dirname, "..", "bin");
  60. fs.mkdirSync(binDir, { recursive: true });
  61. const isWindows = platform === "win32";
  62. const targetName = isWindows ? "gsd-browser.exe" : "gsd-browser";
  63. const targetPath = path.join(binDir, targetName);
  64. // Check if binary already exists (e.g., bundled in package)
  65. if (fs.existsSync(targetPath)) {
  66. console.log(`gsd-browser: binary already present at ${targetPath}`);
  67. return;
  68. }
  69. // Determine version from package.json
  70. const pkg = require("../package.json");
  71. let version = pkg.version;
  72. // Download from GitHub releases
  73. let url = `https://github.com/${REPO}/releases/download/v${version}/${binaryName}`;
  74. // If version is 0.1.0 or similar pre-release, try latest
  75. try {
  76. console.log(`gsd-browser: downloading ${binaryName} v${version}...`);
  77. await downloadFile(url, targetPath);
  78. } catch (e) {
  79. // Fall back to latest release
  80. console.log(`gsd-browser: v${version} not found, trying latest release...`);
  81. try {
  82. const release = await fetchJSON(`https://api.github.com/repos/${REPO}/releases/latest`);
  83. const asset = release.assets.find((a) => a.name === binaryName);
  84. if (!asset) {
  85. throw new Error(`No asset ${binaryName} in latest release`);
  86. }
  87. await downloadFile(asset.browser_download_url, targetPath);
  88. version = release.tag_name;
  89. } catch (e2) {
  90. console.error(
  91. `gsd-browser: failed to download binary.\n` +
  92. ` ${e2.message}\n` +
  93. ` You can build from a repo checkout:\n` +
  94. ` git clone https://github.com/${REPO}.git\n` +
  95. ` cd gsd-browser\n` +
  96. ` cargo install --path cli\n` +
  97. ` Or use the installer: curl -fsSL https://install.gsd.build/browser | bash`
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 110 on GitHub
  98. );
  99. process.exit(1);
  100. }
  101. }
  102. if (!isWindows) {
  103. fs.chmodSync(targetPath, 0o755);
  104. }
  105. console.log(`gsd-browser: installed ${binaryName} (${version}) to ${targetPath}`);
  106. }
  107. main().catch((e) => {
  108. console.error(`gsd-browser: postinstall failed: ${e.message}`);
  109. process.exit(1);
  110. });

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.