browserctl 0.5.0 → 0.6.0

data/examples/test_automation_practices/key_press.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/key_press" do
+  desc "Key press page: dispatch keyboard events, 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/test_automation_practices_key_press.png")
+
+  step "open key press page" do
+    open_page(:main, url: "#{base_url}/#/key-press")
+  end
+
+  step "dispatch key events and verify last-key display" do
+    keys = %w[A B C D E]
+    keys.each do |key|
+      client.evaluate(
+        "main",
+        "document.dispatchEvent(new KeyboardEvent('keydown', { key: '#{key}', bubbles: true }))"
+      )
+      sleep 0.1
+    end
+
+    last = client.evaluate("main",
+                           "document.querySelector('[data-test=\"last-key-pressed\"]')?.innerText?.trim()")[:result]
+    assert last == keys.last, "expected last key '#{keys.last}', got: #{last.inspect}"
+    store(:keys, keys)
+  end
+
+  step "verify key history contains all dispatched keys" do
+    keys = fetch(:keys)
+    history = client.evaluate(
+      "main",
+      "Array.from(document.querySelectorAll('[data-test^=\"key-\"]')).map(el => el.innerText?.trim())"
+    )[:result]
+    # History shows most recent first; each entry typically contains the key label
+    keys.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/test_automation_practices/login.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/login" do
+  desc "Auth page: fill credentials, verify success message, logout"
+
+  param :username,        default: "admin"
+  param :password,        default: "admin", secret: true
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/test_automation_practices_login.png")
+
+  step "open auth page" do
+    open_page(:main, url: "#{base_url}/#/auth")
+  end
+
+  step "fill and submit credentials" do
+    page(:main).fill("[data-test='username-input']", username)
+    page(:main).fill("[data-test='password-input']", password)
+    page(:main).click("[data-test='login-button']")
+  end
+
+  step "verify successful login" do
+    page(:main).wait("[data-test='auth-success']", timeout: 10)
+    msg = client.evaluate("main", "document.querySelector('[data-test=\"auth-success\"]')?.innerText?.trim()")[:result]
+    assert msg&.length&.positive?, "expected a success message, got: #{msg.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "logout and verify form reappears" do
+    page(:main).click("[data-test='logout-button']")
+    page(:main).wait("[data-test='login-button']", timeout: 5)
+    visible = client.evaluate("main", "!!document.querySelector('[data-test=\"login-button\"]')")[:result]
+    assert visible, "expected login form to reappear after logout"
+  end
+end

data/examples/test_automation_practices/login_negative.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/login_negative" do
+  desc "Auth page: invalid credentials show an error message"
+
+  param :base_url, default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path,
+        default: File.expand_path(".browserctl/screenshots/test_automation_practices_login_negative.png")
+
+  step "open auth page" do
+    open_page(:main, url: "#{base_url}/#/auth")
+  end
+
+  step "submit wrong credentials" do
+    page(:main).fill("[data-test='username-input']", "wronguser")
+    page(:main).fill("[data-test='password-input']", "wrongpass")
+    page(:main).click("[data-test='login-button']")
+  end
+
+  step "verify error is shown and success is absent" do
+    page(:main).wait("[data-test='auth-error']", timeout: 10)
+    error = client.evaluate("main", "document.querySelector('[data-test=\"auth-error\"]')?.innerText?.trim()")[:result]
+    assert error&.length&.positive?, "expected an error message, got: #{error.inspect}"
+    no_success = client.evaluate("main", "!document.querySelector('[data-test=\"auth-success\"]')")[:result]
+    assert no_success, "expected no success element when credentials are invalid"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/notifications.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Individual notification items have data-test="notification-{id}".
+# The wrapper has data-test="notification-container" — excluded from counts below.
+NOTIFICATION_ITEMS_JS = <<~JS
+  document.querySelectorAll('[data-test^="notification-"]:not([data-test="notification-container"])').length
+JS
+
+Browserctl.workflow "test_automation_practices/notifications" do
+  desc "Notifications: trigger success, error, and info toasts — verify count increases on each trigger"
+
+  param :base_url, default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path,
+        default: File.expand_path(".browserctl/screenshots/test_automation_practices_notifications.png")
+
+  step "open notifications page and record baseline" do
+    open_page(:main, url: "#{base_url}/#/notifications")
+    page(:main).wait("[data-test='notification-container']", timeout: 5)
+    # Let any delayed on-load notifications finish appearing before we snapshot the baseline
+    sleep 1
+    store(:baseline, client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result])
+  end
+
+  step "trigger success notification and verify count increased by 1" do
+    base = fetch(:baseline)
+    page(:main).click("[data-test='add-success']")
+    page(:main).wait("[data-test^='notification-']:not([data-test='notification-container'])", timeout: 5)
+    count = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+    assert count == base + 1, "expected #{base + 1} notifications after success, got: #{count}"
+  end
+
+  step "dismiss one notification and verify count returns to baseline" do
+    base = fetch(:baseline)
+    client.evaluate("main", "document.querySelector('[data-test^=\"close-notification-\"]')?.click()")
+    deadline = Time.now + 5
+    remaining = nil
+    loop do
+      remaining = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+      break if remaining <= base || Time.now > deadline
+
+      sleep 0.2
+    end
+    assert remaining <= base, "expected count back to #{base} after dismiss, got: #{remaining}"
+    # Re-snapshot baseline in case on-load notifications auto-dismissed during this step
+    store(:baseline, remaining)
+  end
+
+  step "trigger error and info notifications and verify count increased by 2" do
+    base = fetch(:baseline)
+    page(:main).click("[data-test='add-error']")
+    page(:main).click("[data-test='add-info']")
+    page(:main).wait("[data-test^='notification-']:not([data-test='notification-container'])", timeout: 5)
+    count = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+    assert count == base + 2, "expected #{base + 2} notifications (error + info), got: #{count}"
+    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,35 @@ 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)
 
     # 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 +151,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 +181,88 @@ 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
+
+    # 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/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

data/lib/browserctl/commands/page.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "optimist"
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Page
+      extend CliOutput
+
+      USAGE = "Usage: browserctl page <open|close|list|focus> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "open"  then run_open(client, args)
+        when "close" then run_close(client, args)
+        when "list"  then run_list(client)
+        when "focus" then run_focus(client, args)
+        else abort "unknown page subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_open(client, args)
+        opts = Optimist.options(args) do
+          opt :url, "URL to navigate to", type: :string, short: "-u"
+        end
+        name = args.shift or abort "usage: browserctl page open <name> [--url URL]"
+        print_result(client.page_open(name, url: opts[:url]))
+      end
+
+      def self.run_close(client, args)
+        name = args.shift or abort "usage: browserctl page close <name>"
+        print_result(client.page_close(name))
+      end
+
+      def self.run_list(client)
+        print_result(client.page_list)
+      end
+
+      def self.run_focus(client, args)
+        name = args.shift or abort "usage: browserctl page focus <name>"
+        print_result(client.call("page_focus", name: name))
+      end
+    end
+  end
+end

data/lib/browserctl/commands/record.rb

@@ -43,7 +43,7 @@ module Browserctl
           FileUtils.mkdir_p(File.dirname(out))
           Recording.generate_workflow(name, output_path: out)
           puts "Workflow saved: #{out}"
-          puts "Run with: browserctl run #{name}"
+          puts "Run with: browserctl workflow run #{name}"
         end
 
         def run_status

data/lib/browserctl/commands/screenshot.rb

@@ -10,11 +10,11 @@ module Browserctl
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl shot <page> [--out PATH] [--full]"
+          banner "Usage: browserctl screenshot <page> [--out PATH] [--full]"
           opt :out,  "Output file path",   type: :string, short: "-o"
           opt :full, "Capture full page",  default: false, short: "-f"
         end
-        name = args.shift or abort "usage: browserctl shot <page> [--out PATH] [--full]"
+        name = args.shift or abort "usage: browserctl screenshot <page> [--out PATH] [--full]"
         print_result(client.screenshot(name, path: opts[:out], full: opts[:full]))
       end
     end