browserctl 0.5.0 → 0.7.0

data/examples/test_automation_practices/interactions/drag_drop.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/interactions/drag_drop" do
+  desc "Drag-drop page: reorder items via keyboard (Space to pick up, Arrow to move, Space to drop)"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_interactions_drag_drop.png")
+
+  step "open drag-drop page and read initial order" do
+    open_page(:main, url: "#{base_url}/#/drag-drop")
+    page(:main).wait("[data-test='drag-drop-list']", timeout: 10)
+    items = page(:main).evaluate(
+      "Array.from(document.querySelectorAll('[data-test=\"drag-drop-list\"] li')).map(el => el.textContent?.trim())"
+    )
+    store(:initial_order, items)
+    assert items.length == 5, "expected 5 items in drag-drop list, got: #{items.length}"
+  end
+
+  step "focus first item and move it down one position via keyboard" do
+    page(:main).evaluate(
+      "document.querySelectorAll('[data-test=\"drag-drop-list\"] li')[0].focus()"
+    )
+    sleep 0.1
+    page(:main).press("Space")
+    sleep 0.1
+    page(:main).press("ArrowDown")
+    sleep 0.1
+    page(:main).press("Space")
+    sleep 0.2
+  end
+
+  step "verify first item moved to second position" do
+    initial = fetch(:initial_order)
+    current = page(:main).evaluate(
+      "Array.from(document.querySelectorAll('[data-test=\"drag-drop-list\"] li')).map(el => el.textContent?.trim())"
+    )
+    assert current[1] == initial[0],
+           "expected '#{initial[0]}' at index 1 after move down, got order: #{current.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/interactions/exit_intent.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/interactions/exit_intent" do
+  desc "Exit intent page: trigger modal by dispatching mouseleave at viewport top, test all dismiss paths"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_interactions_exit_intent.png")
+
+  step "open exit intent page" do
+    open_page(:main, url: "#{base_url}/#/exit-intent")
+    sleep 0.5
+  end
+
+  step "trigger exit intent — modal appears" do
+    page(:main).evaluate(<<~JS)
+      document.dispatchEvent(
+        new MouseEvent('mouseleave', { bubbles: true, cancelable: true, clientY: -1 })
+      )
+    JS
+    page(:main).wait("[data-test='exit-modal']", timeout: 5)
+    visible = page(:main).evaluate("!!document.querySelector('[data-test=\"exit-modal\"]')")
+    assert visible, "expected exit-modal to appear after mouseleave event"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "dismiss via X close button — modal disappears" do
+    page(:main).click("[data-test='close-modal']")
+    sleep 0.2
+    gone = page(:main).evaluate("!document.querySelector('[data-test=\"exit-modal\"]')")
+    assert gone, "expected exit-modal to close after clicking X"
+  end
+
+  step "re-trigger and dismiss via No thanks" do
+    page(:main).navigate("#{base_url}/#/exit-intent")
+    sleep 0.5
+    page(:main).evaluate(<<~JS)
+      document.dispatchEvent(
+        new MouseEvent('mouseleave', { bubbles: true, cancelable: true, clientY: -1 })
+      )
+    JS
+    page(:main).wait("[data-test='exit-modal']", timeout: 5)
+    page(:main).click("[data-test='modal-no']")
+    sleep 0.2
+    gone = page(:main).evaluate("!document.querySelector('[data-test=\"exit-modal\"]')")
+    assert gone, "expected exit-modal to close after clicking No thanks"
+  end
+end

data/examples/test_automation_practices/interactions/hover.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/interactions/hover" do
+  desc "Hover states page: move mouse over each figure, verify overlay content appears on each"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_interactions_hover.png")
+
+  step "open hover states page" do
+    open_page(:main, url: "#{base_url}/#/hover")
+    page(:main).wait("[data-test='hover-example']", timeout: 10)
+  end
+
+  step "hover over each figure and verify caption appears" do
+    [1, 2, 3].each do |i|
+      page(:main).hover("[data-test='hover-figure-#{i}']")
+      sleep 0.2
+      caption = page(:main).evaluate(
+        "!!document.querySelector('[data-test=\"hover-caption-#{i}\"]')"
+      )
+      assert caption, "expected caption to appear on figure #{i} after hover"
+    end
+  end
+
+  step "screenshot the hovered state" do
+    page(:main).hover("[data-test='hover-figure-2']")
+    sleep 0.2
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/interactions/key_press.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/interactions/key_press" do
+  desc "Key press page: fire real keyboard events via press, verify last-key display and history list update"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_interactions_key_press.png")
+
+  step "open key press page" do
+    open_page(:main, url: "#{base_url}/#/key-press")
+  end
+
+  step "fire key events and verify last-key display" do
+    keys = %w[A B C D E]
+    keys.each do |key|
+      page(:main).press(key)
+      sleep 0.1
+    end
+
+    last = page(:main).evaluate(
+      "document.querySelector('[data-test=\"last-key-pressed\"]')?.innerText?.trim()"
+    )
+    assert last == keys.last, "expected last key '#{keys.last}', got: #{last.inspect}"
+    store(:keys, keys)
+  end
+
+  step "verify key history contains the most recent keys" do
+    keys = fetch(:keys)
+    history = page(:main).evaluate(
+      "Array.from(document.querySelectorAll('[data-test^=\"key-\"]')).map(el => el.innerText?.trim())"
+    )
+    # The site retains only the last 4 keys in the history list; assert those
+    keys.last(4).each do |key|
+      assert history.any? { |entry| entry&.include?(key) }, "expected '#{key}' in history, got: #{history.inspect}"
+    end
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/the_internet/add_remove_elements.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/add_remove_elements" do
   param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_add_remove_elements.png")
 
   step "open add/remove elements page" do
-    client.open_page("main", url: "#{base_url}/add_remove_elements/")
+    open_page(:main, url: "#{base_url}/add_remove_elements/")
   end
 
   step "add three elements" do

data/examples/the_internet/checkboxes.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/checkboxes" do
   param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_checkboxes.png")
 
   step "open checkboxes page" do
-    client.open_page("main", url: "#{base_url}/checkboxes")
+    open_page(:main, url: "#{base_url}/checkboxes")
   end
 
   step "read initial state" do

data/examples/the_internet/dropdown.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/dropdown" do
   param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_dropdown.png")
 
   step "open dropdown page" do
-    client.open_page("main", url: "#{base_url}/dropdown")
+    open_page(:main, url: "#{base_url}/dropdown")
   end
 
   step "assert default is unselected" do

data/examples/the_internet/dynamic_loading.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/dynamic_loading" do
   param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_dynamic_loading.png")
 
   step "open dynamic loading page" do
-    client.open_page("main", url: "#{base_url}/dynamic_loading/1")
+    open_page(:main, url: "#{base_url}/dynamic_loading/1")
   end
 
   step "assert finish text is hidden before start" do
@@ -17,7 +17,7 @@ Browserctl.workflow "the_internet/dynamic_loading" do
 
   step "click Start and wait for content" do
     page(:main).click("#start button")
-    page(:main).wait_for("#finish h4", timeout: 10)
+    page(:main).wait("#finish h4", timeout: 10)
   end
 
   step "assert finish text is correct" do

data/examples/the_internet/login.rb

@@ -9,7 +9,7 @@ Browserctl.workflow "the_internet/login" do
   param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_login.png")
 
   step "open login page" do
-    client.open_page("main", url: "#{base_url}/login")
+    open_page(:main, url: "#{base_url}/login")
   end
 
   step "fill and submit credentials" do

data/lib/browserctl/client.rb

@@ -9,8 +9,8 @@ require_relative "recording"
 module Browserctl
   # Thin IPC client that wraps each browserd command as a Ruby method call.
   class Client
-    def initialize(socket_path = Browserctl.socket_path)
-      @socket_path = socket_path
+    def initialize(socket_path = nil)
+      @socket_path = socket_path || auto_discover_socket
     end
 
     def call(cmd, **params)
@@ -25,22 +25,22 @@ module Browserctl
     # @param name [String] logical page name
     # @param url [String, nil] optional URL to navigate to after opening
     # @return [Hash] `{ ok: true, name: }` or `{ error: }`
-    def open_page(name, url: nil)  = call("open_page",  name: name, url: url)
+    def page_open(name, url: nil)  = call("page_open",  name: name, url: url)
 
     # Closes a named page and removes it from the session.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def close_page(name)           = call("close_page", name: name)
+    def page_close(name)           = call("page_close", name: name)
 
     # Lists all open page names.
     # @return [Hash] `{ pages: [String] }`
-    def list_pages                 = call("list_pages")
+    def page_list                  = call("page_list")
 
     # Navigates a page to a URL. Returns `challenge: true` when Cloudflare is detected.
     # @param name [String] logical page name
     # @param url [String] destination URL
     # @return [Hash] `{ ok: true, url:, challenge: }` or `{ error: }`
-    def goto(name, url)            = call("goto", name: name, url: url)
+    def navigate(name, url)        = call("navigate", name: name, url: url)
 
     # Clicks an element identified by CSS selector or snapshot ref.
     # @param name [String] logical page name
@@ -81,32 +81,23 @@ module Browserctl
       call("snapshot", name: name, format: format, diff: diff)
     end
 
-    # Waits for a CSS selector to appear (short timeout).
+    # Waits for a CSS selector to appear within the given timeout.
     # @param name [String] logical page name
     # @param selector [String] CSS selector to wait for
-    # @param timeout [Numeric] seconds before giving up (default: 10)
-    # @return [Hash] `{ ok: true }` or `{ error: }`
-    def wait_for(name, selector, timeout: 10) = call("wait_for", name: name, selector: selector, timeout: timeout)
-
-    # Polls for a CSS selector with a longer timeout (suitable for async operations).
-    # @param name [String] logical page name
-    # @param selector [String] CSS selector to poll for
     # @param timeout [Numeric] seconds before giving up (default: 30)
     # @return [Hash] `{ ok: true, selector: }` or `{ error: }`
-    def watch(name, selector, timeout: 30)
-      call("watch", name: name, selector: selector, timeout: timeout)
-    end
+    def wait(name, selector, timeout: 30) = call("wait", name: name, selector: selector, timeout: timeout)
 
     # Returns the current URL of a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, url: }` or `{ error: }`
-    def url(name)                  = call("url",         name: name)
+    def url(name)                  = call("url",      name: name)
 
     # Evaluates a JavaScript expression and returns the result.
     # @param name [String] logical page name
     # @param expression [String] JavaScript expression
     # @return [Hash] `{ ok: true, result: }` or `{ error: }`
-    def evaluate(name, expression) = call("evaluate",    name: name, expression: expression)
+    def evaluate(name, expression) = call("evaluate", name: name, expression: expression)
 
     # Checks if browserd is alive.
     # @return [Hash] `{ ok: true, pid: }` or raises if daemon is not running
@@ -118,34 +109,40 @@ module Browserctl
 
     # Pauses automation on a page so a human can interact directly.
     # @param name [String] logical page name
-    # @return [Hash] `{ ok: true, paused: true }` or `{ error: }`
-    def pause(name)                = call("pause",   name: name)
+    # @param message [String, nil] optional message displayed to the human
+    # @return [Hash] `{ ok: true, paused: true, message: }` or `{ error: }`
+    def pause(name, message: nil)  = call("pause",  name: name, message: message)
 
     # Resumes automation on a paused page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, paused: false }` or `{ error: }`
-    def resume(name)               = call("resume",  name: name)
+    def resume(name)               = call("resume", name: name)
 
     # Returns the Chrome DevTools URL for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, devtools_url: }` or `{ error: }`
-    def inspect_page(name)         = call("inspect", name: name)
+    def devtools(name)             = call("devtools", name: name)
+
+    # Brings the named page's tab to front. Only works when browserd was started with --headed.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def page_focus(name) = call("page_focus", name: name)
 
     # Stores a value in the daemon-scoped key-value store.
     # @param key [String] storage key
     # @param value [Object] value to store (must be JSON-serialisable)
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def store(key, value) = call("store", key: key, value: value)
+    def store(key, value)          = call("store", key: key, value: value)
 
     # Retrieves a value from the daemon-scoped key-value store.
     # @param key [String] storage key
     # @return [Hash] `{ ok: true, value: }` or `{ error:, code: "key_not_found" }`
-    def fetch(key) = call("fetch", key: key)
+    def fetch(key)                 = call("fetch", key: key)
 
     # Returns all cookies for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, cookies: [Hash] }` or `{ error: }`
-    def cookies(name) = call("cookies", name: name)
+    def cookies(name)              = call("cookies", name: name)
 
     # Sets a cookie on a named page.
     # @param name [String] logical page name
@@ -159,12 +156,13 @@ module Browserctl
                          value: value, domain: domain, path: path)
     end
 
-    # Clears all cookies for a named page.
+    # Deletes all cookies for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def clear_cookies(name) = call("clear_cookies", name: name)
+    def delete_cookies(name) = call("delete_cookies", name: name)
 
     # Exports all cookies for a named page to a JSON file.
+    # File I/O is client-side; daemon provides the cookie data.
     # @param name [String] logical page name
     # @param path [String] file path to write cookies to
     # @return [Hash] `{ ok: true, path:, count: }` or `{ error: }`
@@ -188,8 +186,125 @@ module Browserctl
       call("import_cookies", name: name, cookies: cookies)
     end
 
+    # Returns the value of a localStorage or sessionStorage key.
+    # @param name [String] logical page name
+    # @param key [String] storage key
+    # @param store [String] "local" or "session" (default: "local")
+    # @return [Hash] `{ ok: true, value: }` or `{ error: }`
+    def storage_get(name, key, store: "local")
+      call("storage_get", name: name, key: key, store: store)
+    end
+
+    # Sets a localStorage or sessionStorage key.
+    # @param name [String] logical page name
+    # @param key [String] storage key
+    # @param value [String] storage value
+    # @param store [String] "local" or "session" (default: "local")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def storage_set(name, key, value, store: "local")
+      call("storage_set", name: name, key: key, value: value, store: store)
+    end
+
+    # Exports localStorage and/or sessionStorage to a JSON file.
+    # @param name [String] logical page name
+    # @param path [String] destination file path
+    # @param stores [String] "local", "session", or "all" (default: "all")
+    # @return [Hash] `{ ok: true, path:, key_count: }` or `{ error: }`
+    def storage_export(name, path, stores: "all")
+      call("storage_export", name: name, path: path, stores: stores)
+    end
+
+    # Imports storage keys from a JSON file into the page's localStorage.
+    # @param name [String] logical page name
+    # @param path [String] source file path
+    # @return [Hash] `{ ok: true, origins: N, key_count: M }` or `{ error: }`
+    def storage_import(name, path)
+      call("storage_import", name: name, path: path)
+    end
+
+    # Clears localStorage and/or sessionStorage for the page.
+    # @param name [String] logical page name
+    # @param stores [String] "local", "session", or "all" (default: "all")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def storage_delete(name, stores: "all")
+      call("storage_delete", name: name, stores: stores)
+    end
+
+    # Fires a keydown + keyup event for the given key name on a page.
+    # @param name [String] logical page name
+    # @param key [String] key name e.g. "Enter", "Tab", "Escape", "ArrowDown"
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def press(name, key)          = call("press",  name: name, key: key)
+
+    # Moves the mouse to the centre of the element matched by selector.
+    # @param name [String] logical page name
+    # @param selector [String] CSS selector
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def hover(name, selector)     = call("hover",  name: name, selector: selector)
+
+    # Sets a file-input element to the given file path.
+    # @param name [String] logical page name
+    # @param selector [String] CSS selector for the file input
+    # @param path [String] absolute or relative file path
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def upload(name, selector, path) = call("upload", name: name, selector: selector, path: path)
+
+    # Sets a <select> element's value and fires a change event.
+    # @param name [String] logical page name
+    # @param selector [String] CSS selector for the select element
+    # @param value [String] option value to select
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def select(name, selector, value) = call("select", name: name, selector: selector, value: value)
+
+    # Pre-registers a one-shot handler to accept the next JS dialog on a page.
+    # @param name [String] logical page name
+    # @param text [String, nil] prompt text for window.prompt dialogs (ignored for alert/confirm)
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def dialog_accept(name, text: nil) = call("dialog_accept", name: name, text: text)
+
+    # Pre-registers a one-shot handler to dismiss the next JS dialog on a page.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def dialog_dismiss(name)           = call("dialog_dismiss", name: name)
+
+    # Saves the current browser state (cookies, localStorage, open pages) to a named session.
+    # @param session_name [String] name for the saved session
+    # @return [Hash] `{ ok: true, path:, pages: N, cookies: N }` or `{ error: }`
+    def session_save(session_name)
+      call("session_save", session_name: session_name)
+    end
+
+    # Restores a previously saved session into the running daemon.
+    # @param session_name [String] name of the session to load
+    # @return [Hash] `{ ok: true, cookies: N, pages: N, local_storage_keys: N }` or `{ error: }`
+    def session_load(session_name)
+      call("session_load", session_name: session_name)
+    end
+
+    # Lists all saved sessions.
+    # @return [Hash] `{ ok: true, sessions: [Hash] }` or `{ error: }`
+    def session_list
+      call("session_list")
+    end
+
+    # Permanently deletes a named session.
+    # @param session_name [String] name of the session to delete
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def session_delete(session_name)
+      call("session_delete", session_name: session_name)
+    end
+
     private
 
+    def auto_discover_socket
+      default = Browserctl.socket_path
+      return default if File.exist?(default)
+
+      # Fall back to the first available auto-indexed daemon, or the default path
+      # (which will raise "browserd is not running" at connection time if absent).
+      Browserctl.all_daemon_sockets.first || default
+    end
+
     def communicate(payload)
       UNIXSocket.open(@socket_path) do |sock|
         sock.puts(payload)

data/lib/browserctl/commands/ask.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Ask
+      extend CliOutput
+
+      def self.run(args)
+        abort "usage: browserctl ask <prompt>" if args.empty?
+
+        prompt = args.join(" ")
+        $stderr.print("[browserctl] #{prompt} ")
+        value = $stdin.gets.chomp
+        print_result({ ok: true, value: value })
+      end
+    end
+  end
+end

data/lib/browserctl/commands/cookie.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Cookie
+      extend CliOutput
+
+      USAGE = "Usage: browserctl cookie <list|set|delete|export|import> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "list"   then run_list(client, args)
+        when "set"    then run_set(client, args)
+        when "delete" then run_delete(client, args)
+        when "export" then run_export(client, args)
+        when "import" then run_import(client, args)
+        else abort "unknown cookie subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_list(client, args)
+        page = args.shift or abort "usage: browserctl cookie list <page>"
+        print_result(client.cookies(page))
+      end
+
+      def self.run_set(client, args)
+        page   = args.shift or abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN [--path /]"
+        name   = args.shift or abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN [--path /]"
+        value  = args.shift or abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN [--path /]"
+        domain_idx = args.index("--domain")
+        domain = domain_idx ? args.delete_at(domain_idx + 1).tap { args.delete_at(domain_idx) } : nil
+        abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN" unless domain
+        path_idx = args.index("--path")
+        path = path_idx ? args.delete_at(path_idx + 1).tap { args.delete_at(path_idx) } : "/"
+        print_result(client.set_cookie(page, name, value, domain, path: path))
+      end
+
+      def self.run_delete(client, args)
+        page = args.shift or abort "usage: browserctl cookie delete <page>"
+        print_result(client.delete_cookies(page))
+      end
+
+      def self.run_export(client, args)
+        page = args.shift or abort "usage: browserctl cookie export <page> <path>"
+        path = args.shift or abort "usage: browserctl cookie export <page> <path>"
+        print_result(client.export_cookies(page, path))
+      end
+
+      def self.run_import(client, args)
+        page = args.shift or abort "usage: browserctl cookie import <page> <path>"
+        path = args.shift or abort "usage: browserctl cookie import <page> <path>"
+        print_result(client.import_cookies(page, path))
+      end
+    end
+  end
+end

data/lib/browserctl/commands/daemon.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+require "optimist"
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Daemon
+      extend CliOutput
+
+      USAGE = "Usage: browserctl daemon <ping|status|start|stop|list> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "ping"   then print_result(client.ping)
+        when "status" then run_status(client)
+        when "start"  then run_start(args)
+        when "stop"   then print_result(client.shutdown)
+        when "list"   then run_list
+        else abort "unknown daemon subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_status(client)
+        ping = client.ping
+        pages = client.page_list[:pages] || []
+        page_info = pages.map do |name|
+          url_res = client.url(name)
+          { name: name, url: url_res[:url] || url_res[:error] }
+        end
+        puts JSON.pretty_generate(
+          daemon: "online",
+          pid: ping[:pid],
+          protocol_version: ping[:protocol_version],
+          pages: page_info
+        )
+      rescue RuntimeError => e
+        raise unless e.message.include?("browserd is not running")
+
+        puts JSON.pretty_generate(daemon: "offline", error: e.message)
+        exit 1
+      end
+
+      def self.run_start(args)
+        opts = Optimist.options(args) do
+          opt :headed, "Run with visible browser", default: false
+          opt :name,   "Daemon name", type: :string
+        end
+        flags = []
+        flags << "--headed" if opts[:headed]
+        flags += ["--name", opts[:name]] if opts[:name]
+        pid = Process.spawn("browserd", *flags, out: File::NULL, err: File::NULL)
+        Process.detach(pid)
+        puts "browserd started (pid #{pid})"
+      end
+
+      def self.run_list
+        sockets = Dir[File.join(Browserctl::BROWSERCTL_DIR, "*.sock")]
+        rows = sockets.map do |sock_path|
+          daemon_name = File.basename(sock_path, ".sock")
+          display_name = daemon_name == "browserd" ? "default" : daemon_name
+          socket_name = daemon_name == "browserd" ? nil : daemon_name
+          client = Browserctl::Client.new(Browserctl.socket_path(socket_name))
+          status = client.ping
+          next unless status&.dig(:ok)
+
+          { name: display_name, pid: status[:pid], pages: (client.page_list[:pages] || []).length }
+        rescue RuntimeError
+          nil
+        end.compact
+        puts({ daemons: rows }.to_json)
+      end
+    end
+  end
+end