browserctl 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1626673b3046c133aa7e1d63ee7d1886ed3071970227c184ab412a8f3cf48a4f
-  data.tar.gz: 4773002a9052247ec8afe259abd0d4c38cc3aa308be81bbeca756626bb206d44
+  metadata.gz: ec75744264ce56f8c3f94ab95518a106c8225ec1dc11dd35a97f43186b590502
+  data.tar.gz: 973c3b270b5d1bba3dfa900623790e3c5cb9d5bd8ebe8faa50c28d09e48fbfff
 SHA512:
-  metadata.gz: 8e241d9fc064c419285b2e83b5e5154c6ccb639aeffb2179ace9b6ef3ec180069b76772cf5f6485af3cea4ef4616265a87dbbc43d7879cd0a71eec946e022ce8
-  data.tar.gz: b396184b74f6804e3b84105c4b75a89ef5a63751ad5577e2dc8008ed1c3111614f2d579ac9c3a12f7943968b3c4cab59fab69dfe392f4af51ba59fff0e8684ba
+  metadata.gz: 16cd84c58a070de0b9d340ed2bb4e3a951216526dd77a9f18e0f9ea7292311eb51eddf1989c93c11d488cf4bf29163a60a13510f5949599d6027142cf808c1a0
+  data.tar.gz: 615213ac9ba1e694c9fb4597a348abebab9d8f2ba04801dd7d59c1dc00829111f0cce9f49391a7883e7502422ed0b246e86d8c553c62b9be406e0f1e23946e8c

data/CHANGELOG.md

@@ -1,10 +1,57 @@
 # Changelog
 
+> **Do not edit this file manually.** It is generated automatically by
+> [release-please](https://github.com/googleapis/release-please) on every merge to `main`.
+> To include a change in the next release, write a
+> [Conventional Commit](https://www.conventionalcommits.org/) message (`feat:`, `fix:`, `chore:`, etc.).
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0](https://github.com/patrick204nqh/browserctl/compare/v0.4.0...v0.5.0) (2026-04-25)
+
+
+### Features
+
+* add cookie export/import commands and refine interaction guidance ([1dc8b2c](https://github.com/patrick204nqh/browserctl/commit/1dc8b2c4c744a5f0930c28d3bcf93fd017c368b1))
+* rename snapshot format 'ai' to 'elements' ([#22](https://github.com/patrick204nqh/browserctl/issues/22)) ([9fde6af](https://github.com/patrick204nqh/browserctl/commit/9fde6afb9e53b9556c84b4c24987777a5c266adf))
+* v0.5 architecture & protocol lock ([#20](https://github.com/patrick204nqh/browserctl/issues/20)) ([1224f2f](https://github.com/patrick204nqh/browserctl/commit/1224f2fe2fb05119053831e7901b286fe93ad4fc))
+
+
+### Bug Fixes
+
+* add rake as development dependency ([13902d8](https://github.com/patrick204nqh/browserctl/commit/13902d81fdb986c6ca754fcb16ce61ee850e27ce))
+* improve browser GIF quality and fix terminal font rendering ([17afdb2](https://github.com/patrick204nqh/browserctl/commit/17afdb210916d8ebdabd237130da1fc534cdbd3e))
+* open PR for demo assets instead of pushing directly to main ([f051316](https://github.com/patrick204nqh/browserctl/commit/f051316962d308419c08f60550cfb9910b148f14))
+* quote filtergraph and add -update 1 for palette in browser GIF pipeline ([053d074](https://github.com/patrick204nqh/browserctl/commit/053d074b5fdd3e0ea6fc51589593d72d5f7fcd74))
+* replace undefined REGISTRY constant with Browserctl.registry_snapshot ([d19a6bf](https://github.com/patrick204nqh/browserctl/commit/d19a6bf7ded8a5211f5b2a75511a9532f94e3845))
+* update README for improved clarity and add Quick Start section ([881d914](https://github.com/patrick204nqh/browserctl/commit/881d914c2bf46625ee4ff5c1ca8ef21b462c533d))
+* use app-slug output instead of gh api /app in assets workflow ([ae6a0f8](https://github.com/patrick204nqh/browserctl/commit/ae6a0f80ba2b66c76d681b1f258de5d72bc34c72))
+* use CSS selectors for browser GIF and add full login flow frames ([717b86b](https://github.com/patrick204nqh/browserctl/commit/717b86befa9af6bab1823f984668ebdc29f2d7f8))
+
+## [0.4.0](https://github.com/patrick204nqh/browserctl/compare/v0.3.1...v0.4.0) (2026-04-25)
+
+
+### Features
+
+* add Claude Code plugin support with installation instructions and plugin metadata ([b568ed2](https://github.com/patrick204nqh/browserctl/commit/b568ed29015d77bc521e4484aada1054b73362e6))
+* add PRODUCT and standardization plan documentation; update VISION, README, and command references ([5594b52](https://github.com/patrick204nqh/browserctl/commit/5594b520f65d19f6c0c022e7944f9a560044549f))
+* allow .browserctl/screenshots/ as project-scoped screenshot directory ([b6914f4](https://github.com/patrick204nqh/browserctl/commit/b6914f42ead76865b8c6e8e8c0e0f88516cb53e3))
+* browserctl v0.4 hardening (security, cookie I/O, store/fetch, params file) ([#15](https://github.com/patrick204nqh/browserctl/issues/15)) ([c702661](https://github.com/patrick204nqh/browserctl/commit/c702661196e0784179afdbd824e6064c1db047bc))
+* DX improvements, doc refresh, and hardening ([#16](https://github.com/patrick204nqh/browserctl/issues/16)) ([6e32e00](https://github.com/patrick204nqh/browserctl/commit/6e32e0038abfa28be9e92ec94f9a7642e29803c4))
+
+
+### Bug Fixes
+
+* add enabledPlugins section to settings.json for browserctl plugin activation ([924dbee](https://github.com/patrick204nqh/browserctl/commit/924dbeef9c86ea2c2486d4d93118045acc042833))
+* add marketplace.json and correct plugin metadata ([5cfc1d6](https://github.com/patrick204nqh/browserctl/commit/5cfc1d621bc162fb200150c71ad4f5b62b4bdcc7))
+* allow any path within daemon CWD for screenshots, not just .browserctl/screenshots ([817a492](https://github.com/patrick204nqh/browserctl/commit/817a49211e991493b6018b663fc198c4a0ff3742))
+* save login screenshot to ~/.browserctl/screenshots/ instead of docs/ path ([246688e](https://github.com/patrick204nqh/browserctl/commit/246688e5c586d2028b90c178994d0eb7f1e9c626))
+* update marketplace.json to set strict mode to true for browserctl plugin ([99db2ad](https://github.com/patrick204nqh/browserctl/commit/99db2ada2aae08f8bceb78658e15a267246df973))
+* use screenshot_path param in all examples; CI passes docs/screenshots/ explicitly ([64e073d](https://github.com/patrick204nqh/browserctl/commit/64e073d74979d869560d814b9a986c001b400238))
+
 ## [0.3.1](https://github.com/patrick204nqh/browserctl/compare/v0.3.0...v0.3.1) (2026-04-20)
 
 

data/README.md

@@ -2,287 +2,178 @@
   <img src=".github/logo.svg" width="96" height="96" alt="browserctl logo"/>
 </p>
 
-# browserctl
+<h1 align="center">browserctl</h1>
 
-[![CI](https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml/badge.svg)](https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/browserctl.svg)](https://badge.fury.io/rb/browserctl)
-[![Downloads](https://img.shields.io/gem/dt/browserctl)](https://rubygems.org/gems/browserctl)
+<p align="center">
+  A persistent browser daemon for AI agents and iterative dev workflows — the session stays alive between commands.
+</p>
 
-A persistent browser automation daemon and CLI, purpose-built for AI agents and developer workflows.
+<p align="center">
+  <a href="https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml"><img src="https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
+  <a href="https://badge.fury.io/rb/browserctl"><img src="https://badge.fury.io/rb/browserctl.svg" alt="Gem Version"/></a>
+  <a href="https://rubygems.org/gems/browserctl"><img src="https://img.shields.io/gem/dt/browserctl" alt="Downloads"/></a>
+</p>
 
-Unlike tools that restart the browser on every script run, **browserctl keeps a named browser session alive** — preserving cookies, localStorage, open tabs, and page state across discrete commands.
+---
+
+Every browser automation tool restarts the browser when your script ends. That means re-authenticating, re-navigating, re-loading state — on every run. browserctl doesn't restart. The session stays alive between commands, so you pick up exactly where you left off.
 
 ```bash
-browserd &                                           # start the daemon (headless)
+browserd &                                               # start the daemon (headless)
 browserctl open login --url https://example.com/login
-browserctl snap login                                # AI-friendly JSON snapshot with ref IDs
-browserctl fill login --ref e1 --value me@example.com   # interact by ref
+browserctl snap login                                    # AI-friendly JSON snapshot with ref IDs
+browserctl fill login --ref e1 --value me@example.com   # interact by ref, no selectors needed
 browserctl click login --ref e2
 browserctl shutdown
 ```
 
-![browserctl capturing a login flow](docs/screenshots/the_internet_login.png)
-<p align="center"><sub>Login flow captured with <code>browserctl shot</code></sub></p>
-
 ---
 
-## Why browserctl?
+## See it in action
 
-Most automation tools are stateless — every script spins up a fresh browser and tears it down. browserctl doesn't.
+<table align="center"><tr>
+<td align="center" width="50%">
 
-| | browserctl | Playwright / Selenium |
-|---|---|---|
-| Session persists across commands | ✓ | ✗ (per-script lifecycle) |
-| Named page handles | ✓ | ✗ |
-| AI-friendly DOM snapshot | ✓ | ✗ |
-| Lightweight CLI interface | ✓ | ✗ |
-| Full browser automation API | — | ✓ |
-| Parallel multi-browser testing | — | ✓ |
+**Terminal**<br/>
+<sub>CLI commands, live output, session persistence proof</sub>
 
-**Use browserctl when** you need a browser that stays alive and remembers state — for AI agents, iterative dev workflows, or lightweight smoke tests.
+<img src="docs/assets/terminal.webp" alt="browserctl terminal demo"/>
 
-**Use Playwright/Selenium when** you need parallel test suites, multi-browser support, or a full programmatic API.
+</td>
+<td align="center" width="50%">
 
----
+**Browser**<br/>
+<sub>What the browser sees as those commands run</sub>
+
+<img src="docs/assets/browser_demo.gif" alt="browserctl browser demo"/>
 
-## Requirements
+</td>
+</tr></table>
 
-- Ruby >= 3.2
-- Chrome or Chromium installed and on `PATH`
+> Demo assets are regenerated automatically on every push to `main` that touches `demo/` or the login example. To regenerate locally:
+>
+> ```bash
+> rake demo               # full pipeline: screenshots + browser GIF + terminal GIF
+> rake demo:screenshots   # smoke test screenshots only
+> rake demo:browser_gif   # browser animation only  (requires: ffmpeg)
+> rake demo:terminal      # terminal GIF only        (requires: vhs)
+> ```
 
 ---
 
-## Installation
+## Quick Start
 
 ```bash
+# 1. Install
 gem install browserctl
-```
-
-Or in your `Gemfile`:
-
-```ruby
-gem "browserctl"
-```
 
----
+# 2. Start the daemon
+browserd &
 
-## Quick Start
+# 3. Open a named page
+browserctl open main --url https://the-internet.herokuapp.com/login
 
-**1. Start the daemon**
+# 4. Snapshot the page — get AI-friendly JSON with ref IDs
+browserctl snap main
 
-```bash
-browserd           # headless (default)
-browserd --headed  # visible browser window
-```
+# 5. Interact using refs
+browserctl fill  main --ref e1 --value tomsmith
+browserctl fill  main --ref e2 --value SuperSecretPassword!
+browserctl click main --ref e3
 
-**2. Open a named page**
+# 6. Observe
+browserctl url  main
+browserctl snap main --diff   # only what changed
 
-```bash
-browserctl open login --url https://app.example.com/login
-```
-
-**3. Snapshot the page to discover refs**
-
-```bash
-browserctl snap login              # AI-friendly JSON with ref IDs (default)
-browserctl snap login --format html
+# 7. Done
+browserctl shutdown
 ```
 
-**4. Interact using refs or selectors**
+→ [Full Getting Started guide](docs/getting-started.md)
 
-```bash
-browserctl fill  login --ref e1 --value user@example.com
-browserctl fill  login --ref e2 --value s3cr3t
-browserctl click login --ref e3
+---
 
-# or using explicit CSS selectors
-browserctl fill  login "input[name=email]"    user@example.com
-browserctl click login "button[type=submit]"
-```
+## Use cases
 
-**5. Observe the result**
+**AI coding agent authenticating into a staging environment** — the agent logs in once, the session persists, subsequent commands run inside the authenticated context without re-authenticating between steps.
 
-```bash
-browserctl snap login --diff       # only changed elements since last snap
-browserctl shot login --out /tmp/after-login.png --full
-browserctl url  login
-```
+**Developer reproducing a multi-step bug report** — navigate to the failure point once, then iterate on the fix with the browser already in the right state; no restarting from the home page each run.
 
-**6. Manage pages and daemon**
-
-```bash
-browserctl pages
-browserctl close login
-browserctl ping
-browserctl shutdown
-```
+**Automated smoke test that needs human sign-off** — the test runs until it hits something ambiguous, calls `browserctl pause`, lets a human inspect and act, then `browserctl resume` hands control back to the script with all state intact.
 
 ---
 
-## All Commands
+## Why browserctl?
 
-### Browser commands _(require `browserd` running)_
+Most automation tools are stateless — every script spins up a fresh browser and tears it down. browserctl doesn't.
 
-| Command | Description |
-|---|---|
-| `open <page> [--url URL]` | Open or focus a named page |
-| `close <page>` | Close a named page |
-| `pages` | List open pages |
-| `goto <page> <url>` | Navigate a page to a URL |
-| `fill <page> <selector> <value>` | Fill an input field by CSS selector |
-| `fill <page> --ref <id> --value <v>` | Fill an input field by snapshot ref |
-| `click <page> <selector>` | Click an element by CSS selector |
-| `click <page> --ref <id>` | Click an element by snapshot ref |
-| `snap <page> [--format ai\|html] [--diff]` | Snapshot DOM; `--diff` returns only changed elements |
-| `watch <page> <selector> [--timeout N]` | Poll until selector appears (default timeout: 30s) |
-| `shot <page> [--out PATH] [--full]` | Take a screenshot |
-| `url <page>` | Print current URL |
-| `eval <page> <expression>` | Evaluate a JS expression |
-| `pause <page>` | Pause automation — browser stays live for manual interaction |
-| `resume <page>` | Resume automation after manual action |
-| `inspect <page>` | Open Chrome DevTools for a named page |
-| `cookies <page>` | List all cookies as JSON |
-| `set_cookie <page> <name> <value> <domain>` | Set a cookie (path defaults to `/`) |
-| `clear_cookies <page>` | Clear all cookies for a page |
-| `record start <name>` | Begin recording commands as a replayable workflow |
-| `record stop [--out path]` | End recording; saves to `.browserctl/workflows/` or custom path |
-| `record status` | Show whether a recording is active |
-
-### Daemon commands
-
-| Command | Description |
-|---|---|
-| `ping` | Check if `browserd` is alive |
-| `shutdown` | Stop `browserd` |
+| | browserctl | Playwright / Selenium |
+|---|---|---|
+| Session persists across commands | ✓ | ✗ (per-script lifecycle) |
+| Named page handles | ✓ | ✗ |
+| AI-friendly DOM snapshot | ✓ | ✗ |
+| Human-in-the-loop pause/resume | ✓ | ✗ |
+| Lightweight CLI interface | ✓ | ✗ |
+| Full browser automation API | — | ✓ |
+| Parallel multi-browser testing | — | ✓ |
 
-### Workflow commands
+**Use browserctl when** you need a browser that stays alive and remembers state — for AI agents, iterative dev workflows, or tasks that mix automation with human judgment.
 
-| Command | Description |
-|---|---|
-| `run <name\|file.rb> [--key value ...]` | Run a named workflow or workflow file |
-| `workflows` | List available workflows |
-| `describe <name>` | Show workflow params and steps |
+**Use Playwright/Selenium when** you need parallel test suites, multi-browser support, or a full programmatic API.
 
 ---
 
-## AI Snapshot Format
-
-`browserctl snap <page>` returns a compact JSON array of interactable elements — designed to be token-efficient for AI agents:
-
-```json
-[
-  {
-    "ref": "e1",
-    "tag": "input",
-    "text": "",
-    "selector": "form > input[name=email]",
-    "attrs": {
-      "type": "email",
-      "name": "email",
-      "placeholder": "Enter email"
-    }
-  },
-  {
-    "ref": "e2",
-    "tag": "button",
-    "text": "Sign in",
-    "selector": "form > button",
-    "attrs": {
-      "type": "submit"
-    }
-  }
-]
-```
-
-Use `ref` values directly with `--ref` for zero-fragility interactions, or use `selector` values with `fill` and `click`.
-
-### Ref-based interaction
+## Installation
 
-After a `snap`, use ref IDs instead of CSS selectors — no selector knowledge required:
+**Requirements:** Ruby >= 3.3 · Chrome or Chromium on your `PATH`
 
 ```bash
-browserctl fill  login --ref e1 --value user@example.com
-browserctl click login --ref e2
+gem install browserctl
 ```
 
-### Diff snapshots
-
-Track only what changed since the last snapshot — useful for AI agents monitoring async updates:
+Or in your `Gemfile`:
 
-```bash
-browserctl snap login --diff
+```ruby
+gem "browserctl"
 ```
 
 ---
 
-## Workflows
+## Claude Code Plugin
 
-Workflows are Ruby files using the `Browserctl.workflow` DSL. Place them in any of:
+browserctl ships as a Claude Code plugin. Install it once and Claude automatically knows how to use the daemon, ref-based interaction, HITL patterns, and workflow authoring.
 
-- `./.browserctl/workflows/`
-- `~/.browserctl/workflows/`
+**Interactive install**
 
-### Example
-
-```ruby
-# .browserctl/workflows/smoke_login.rb
-Browserctl.workflow "smoke_login" do
-  desc "Log in and confirm the dashboard loads"
-
-  param :email,    required: true
-  param :password, required: true, secret: true
-  param :base_url, default: "https://app.example.com"
-
-  step "open login page" do
-    page(:login).goto("#{base_url}/login")
-  end
-
-  step "submit credentials" do
-    page(:login).fill("input[name=email]",    email)
-    page(:login).fill("input[name=password]", password)
-    page(:login).click("button[type=submit]")
-  end
-
-  step "verify dashboard" do
-    page(:login).wait_for("[data-test=dashboard]", timeout: 10)
-    assert page(:login).url.include?("/dashboard")
-  end
-end
 ```
-
-```bash
-browserctl run smoke_login --email me@example.com --password s3cr3t
+/plugin marketplace add patrick204nqh/browserctl
+/plugin install browserctl@browserctl
 ```
 
-### Workflow DSL reference
-
-| Method | Description |
-|---|---|
-| `desc "text"` | Human-readable description |
-| `param :name, required:, secret:, default:` | Declare a parameter |
-| `step "label" { }` | Add a step (runs in order, halts on failure) |
-| `step "label", retry_count: N, timeout: S { }` | Step with retry and/or timeout |
-| `page(:name)` | Returns a `PageProxy` for the named page |
-| `invoke "other_workflow", **overrides` | Call another workflow |
-| `assert condition, "message"` | Raise `WorkflowError` if condition is false |
-
-### PageProxy methods
-
-`goto(url)` · `fill(selector, value)` · `click(selector)` · `snapshot(**opts)` · `screenshot(**opts)` · `wait_for(selector, timeout: 10)` · `url` · `evaluate(expression)` · `pause` · `resume` · `inspect_page` · `cookies` · `set_cookie(name, value, domain, path: "/")` · `clear_cookies`
-
----
-
-## Examples
+**Project settings** — commit `.claude/settings.json` to share with your team:
 
-Ready-to-run smoke tests against [the-internet.herokuapp.com](https://the-internet.herokuapp.com) are included in `examples/the_internet/`. See [docs/smoke-testing-the-internet.md](docs/smoke-testing-the-internet.md) for annotated output and auto-generated screenshots of each scenario.
+```json
+{
+  "extraKnownMarketplaces": {
+    "browserctl": {
+      "source": { "source": "github", "repo": "patrick204nqh/browserctl" }
+    }
+  },
+  "enabledPlugins": {
+    "browserctl@browserctl": true
+  }
+}
+```
 
-For a full guide on building your own workflows, see [docs/writing-workflows.md](docs/writing-workflows.md).
+Once installed, Claude Code loads the `browserctl` skill automatically — no `/invoke` needed.
 
 ---
 
 ## How it works
 
-`browserd` runs as a background process, listening on a Unix socket at `~/.browserctl/browserd.sock`. Start multiple named instances for agent isolation:
+`browserd` runs as a background process, listening on a Unix socket at `~/.browserctl/browserd.sock`. It manages a Ferrum (Chrome DevTools Protocol) browser instance with named page handles. `browserctl` sends JSON-RPC commands over the socket and prints the result.
+
+Start multiple named instances for agent isolation:
 
 ```bash
 browserd --name agent-a &
@@ -290,11 +181,22 @@ browserd --name agent-b &
 browserctl --daemon agent-a open main --url https://app.example.com
 ```
 
-It manages a Ferrum (Chrome DevTools Protocol) browser instance with named page handles.
+The daemon shuts itself down after 30 minutes of inactivity.
 
-`browserctl` sends JSON-RPC commands over the socket and prints the result. Workflows run in-process through the same client.
+---
 
-The daemon shuts itself down after 30 minutes of inactivity.
+## Documentation
+
+| | |
+|---|---|
+| [Getting Started](docs/getting-started.md) | Install, first session, first snapshot |
+| [Concepts](docs/concepts/) | Sessions, snapshots, human-in-the-loop |
+| [Guides](docs/guides/) | Writing workflows, handling challenges, smoke testing |
+| [Command Reference](docs/reference/commands.md) | Every command and flag |
+| [API Stability](docs/reference/api-stability.md) | Wire protocol contract and stability zones |
+| [Product](docs/product.md) | What browserctl is and who it's for |
+| [Vision & Roadmap](docs/vision.md) | Philosophy and release roadmap |
+| [vs. agent-browser](docs/vs-agent-browser.md) | How browserctl differs from Vercel's agent-browser |
 
 ---
 
@@ -303,10 +205,14 @@ The daemon shuts itself down after 30 minutes of inactivity.
 ```bash
 git clone https://github.com/patrick204nqh/browserctl
 cd browserctl
-bin/setup              # install deps + check for Chrome
+bin/setup              # brew bundle (macOS) + bundle install + Chrome check
 
 bundle exec rspec      # run tests
 bundle exec rubocop    # lint
+
+rake demo              # regenerate screenshots + terminal GIF
+rake demo:screenshots  # screenshots only (no VHS required)
+rake demo:terminal     # terminal GIF only
 ```
 
 ---

data/bin/browserctl

@@ -21,9 +21,13 @@ require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
 require "browserctl/commands/watch"
 require "browserctl/commands/record"
-require "browserctl/commands/pause_resume"
+require "browserctl/commands/pause"
+require "browserctl/commands/resume"
 require "browserctl/commands/init"
 require "browserctl/commands/inspect"
+require "browserctl/commands/export_cookies"
+require "browserctl/commands/import_cookies"
+require "browserctl/commands/status"
 
 def print_result(res)
   if res.is_a?(Hash) && res[:error]
@@ -59,8 +63,10 @@ def usage
       resume  <page>                               Resume automation after manual action
       inspect <page>                               Open Chrome DevTools for a named page
       cookies <page>                               List all cookies as JSON
-      set_cookie <page> <name> <value> <domain>    Set a cookie (path defaults to /)
-      clear_cookies <page>                         Clear all cookies for a page
+      set-cookie <page> <name> <value> <domain>    Set a cookie (path defaults to /)
+      clear-cookies <page>                         Clear all cookies for a page
+      export-cookies <page> <path>                 Export cookies to a JSON file
+      import-cookies <page> <path>                 Import cookies from a JSON file
 
     Recording commands:
       record start <name>            Start recording browser commands
@@ -68,12 +74,13 @@ def usage
       record status                  Show active recording name
 
     Workflow commands:
-      run      <name|file> [--key value ...]   Run a workflow
+      run      <name|file> [--params file] [--key value ...]   Run a workflow
       workflows                                List available workflows
       describe <name>                          Describe a workflow
 
     Daemon commands:
       ping                   Check if browserd is alive
+      status                 Show daemon status, PID, and open pages
       shutdown               Stop browserd
 
     Options:
@@ -101,15 +108,27 @@ case cmd
 when "run"
   name = args.shift or abort "usage: browserctl run <workflow_name|file.rb> [--key value ...]"
   if File.exist?(name)
-    before = Browserctl::REGISTRY.keys.dup
+    before = Browserctl.registry_snapshot.keys
     load File.expand_path(name)
-    name = (Browserctl::REGISTRY.keys - before).first || File.basename(name, ".rb")
+    name = (Browserctl.registry_snapshot.keys - before).first || File.basename(name, ".rb")
   end
-  params = {}
+  params_file_idx = args.index("--params")
+  file_params = {}
+  if params_file_idx
+    params_path = args.delete_at(params_file_idx + 1)
+    args.delete_at(params_file_idx)
+    begin
+      file_params = Browserctl::Runner.load_params_file(params_path)
+    rescue StandardError => e
+      abort "Error loading params file: #{e.message}"
+    end
+  end
+  cli_params = {}
   args.each_slice(2) do |flag, val|
     key = flag.sub(/\A--/, "").to_sym
-    params[key] = val
+    cli_params[key] = val
   end
+  params = file_params.merge(cli_params)
   success = runner.run_workflow(name, **params)
   exit(success ? 0 : 1)
 
@@ -139,13 +158,16 @@ else
   when "url"      then print_result(client.url(args[0]))
   when "eval"     then print_result(client.evaluate(args[0], args[1]))
   when "watch"    then Browserctl::Commands::Watch.run(client, args)
-  when "pause"    then Browserctl::Commands::PauseResume.pause(client, args)
-  when "resume"   then Browserctl::Commands::PauseResume.resume(client, args)
+  when "pause"    then Browserctl::Commands::Pause.run(client, args)
+  when "resume"   then Browserctl::Commands::Resume.run(client, args)
   when "inspect"       then Browserctl::Commands::Inspect.run(client, args)
-  when "cookies"       then print_result(client.cookies(args[0]))
-  when "set_cookie"    then print_result(client.set_cookie(args[0], args[1], args[2], args[3]))
-  when "clear_cookies" then print_result(client.clear_cookies(args[0]))
+  when "cookies"         then print_result(client.cookies(args[0]))
+  when "set-cookie"      then print_result(client.set_cookie(args[0], args[1], args[2], args[3]))
+  when "clear-cookies"   then print_result(client.clear_cookies(args[0]))
+  when "export-cookies" then Browserctl::Commands::ExportCookies.run(client, args)
+  when "import-cookies" then Browserctl::Commands::ImportCookies.run(client, args)
   when "ping"     then print_result(client.ping)
+  when "status"   then Browserctl::Commands::Status.run(client)
   when "shutdown" then print_result(client.shutdown)
   else
     abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."

data/bin/browserd

@@ -16,7 +16,13 @@ opts = Optimist.options do
   opt :name,      "Daemon instance name for multi-agent use", default: nil,    short: "-n", type: :string
 end
 
-Browserctl.logger = Browserctl.build_logger(opts[:log_level])
+if opts[:name] && opts[:name] !~ /\A[a-zA-Z0-9_-]{1,64}\z/
+  abort "Invalid daemon name #{opts[:name].inspect} — use only letters, digits, _ or -"
+end
+
+log_path = Browserctl.log_path(opts[:name])
+warn "browserd starting — log: #{log_path}"
+Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path)
 Browserctl::Server.new(
   headless: !opts[:headed],
   socket_path: Browserctl.socket_path(opts[:name]),

data/bin/setup

@@ -1,14 +1,18 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-echo "==> Installing dependencies..."
+if [[ "$(uname)" == "Darwin" ]] && command -v brew &>/dev/null; then
+  echo "==> Installing Homebrew dependencies (Brewfile)..."
+  brew bundle --no-upgrade
+fi
+
+echo "==> Installing gem dependencies..."
 bundle install
 
 echo "==> Checking for Chrome/Chromium..."
 if ! command -v google-chrome &>/dev/null && ! command -v chromium-browser &>/dev/null && ! command -v chromium &>/dev/null; then
   echo "WARNING: Chrome/Chromium not found on PATH."
-  echo "         Install it before running browserctl."
-  echo "         macOS:  brew install --cask google-chrome"
+  echo "         macOS:  brew bundle  (includes google-chrome)"
   echo "         Ubuntu: sudo apt-get install -y chromium-browser"
 fi
 

data/examples/cloudflare_hitl.rb

@@ -55,7 +55,7 @@ Browserctl.workflow "cloudflare_hitl" do
 
   step "wait for content and snapshot" do
     page(:main).wait_for(selector, timeout: 15)
-    result = page(:main).snapshot(format: "ai")
+    result = page(:main).snapshot(format: "elements")
     $stdout.puts "  Snapshot: #{result[:snapshot]&.length || 0} elements captured"
   end