browserctl 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b5b21accfeb82afa82dc2c12d51ef7da31ed8ab9db073d2b576df0385e5adb6
-  data.tar.gz: d9cd601ce2d63b5c3f2c8d539d14dc684dcf3753a7f95002b9c165791ff2f584
+  metadata.gz: ac5d5a587f5d9862ef7bd7839f7e7e817acd742ed0a1c6d6e33913eac1be1444
+  data.tar.gz: f28af579b05237429959a444c0369550bcc848c04644bf172b95a4927657b40c
 SHA512:
-  metadata.gz: 5bc9c337336ac4fb23da1966a9b51e3dffcef8b23ea00a2990310a0aae5978ccf423416118ebe61b83c92ca84f38846ca16ca909a376e2e3e8f13eb97e82b045
-  data.tar.gz: 13b8b5fcbc17e328210488ce8e50ead2ea8576419dc5d493c06285d8e191a4be7599a04a58b651f501febb351704609be6dc06c0c8c00c827a7c796667072943
+  metadata.gz: eca2babe456ed7a818ab908bbb9d0ec5fecb0a0474cdfe5335dbc5112667b8bf2e031a5a278dd8369b2009b284def98839ea26f712d88d94c2b89c061b5718f7
+  data.tar.gz: da2d6b4eff687f5257e178a00a96b3ec9b93256fc191b386848328874bd5070cb2631a594b039550a8e3ec6ff9f00fbbfbd088d9ee594cc1d04166c6074f0c60

data/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.3.0](https://github.com/patrick204nqh/browserctl/compare/v0.2.2...v0.3.0) (2026-04-20)
+
+
+### Features
+
+* add cookies, set_cookie, clear_cookies commands for CF clearance replay ([dd38f2d](https://github.com/patrick204nqh/browserctl/commit/dd38f2d587d12f789072326310a1f490e7f993b7))
+* add cookies, set_cookie, clear_cookies commands for CF clearance replay ([c773fe2](https://github.com/patrick204nqh/browserctl/commit/c773fe25e73660cbe5c7e0e3d698fbf7709df51d))
+* browserctl v0.3 — HITL, Cloudflare detection, init, compose, plugins, inspect, RBS, YARD ([ec24c85](https://github.com/patrick204nqh/browserctl/commit/ec24c85a7772b508c477ef4413b0b4a64be8dfa2))
+
+
+### Bug Fixes
+
+* rubocop offenses — bump ClassLength max to 240, fix hash alignment ([52669fd](https://github.com/patrick204nqh/browserctl/commit/52669fd21051e1fef581d1c6acd3189d7d805dfb))
+* rubocop offenses — move CLOUDFLARE_SIGNALS above private, autocorrect style ([0ad3d38](https://github.com/patrick204nqh/browserctl/commit/0ad3d38127671284c935809e189478c7160294f6))
+
+## [0.2.2](https://github.com/patrick204nqh/browserctl/compare/v0.2.1...v0.2.2) (2026-04-20)
+
+
+### Bug Fixes
+
+* never record plaintext fill values in session recordings ([a0ea9a1](https://github.com/patrick204nqh/browserctl/commit/a0ea9a15f4dbdc29a0a6aaa8186fa313e601c691))
+* rescue Timeout::Error in quietly; remove duplicate [@last](https://github.com/last)_used update ([d0b1430](https://github.com/patrick204nqh/browserctl/commit/d0b143051a4a6adcdc80620388390bd649ee0bce))
+* restrict screenshot path to ~/.browserctl/screenshots ([0a1303f](https://github.com/patrick204nqh/browserctl/commit/0a1303f95b1df3135a81c98e531ac31c99e2e275))
+* rubocop offenses — constant scope and hash alignment ([cc11bc5](https://github.com/patrick204nqh/browserctl/commit/cc11bc546746c7f341573ffff43b02fdc94578d8))
+* security patches and PageSession architecture refactor (review fixes) ([a01d0f7](https://github.com/patrick204nqh/browserctl/commit/a01d0f7bd3f58b51d21fc534a67dda25c15b029b))
+* trigger release on tag push; revert release-please to default token ([011d4dc](https://github.com/patrick204nqh/browserctl/commit/011d4dcddd872f0ed88548ee9c2e8b19d64ad5c2))
+* update CI workflows to use actions/checkout@v4 and set timeout for jobs ([15ab5d4](https://github.com/patrick204nqh/browserctl/commit/15ab5d471952ff9759eff7ff77ce2df30eea5e1f))
+* validate workflow name to prevent path traversal ([1d0f221](https://github.com/patrick204nqh/browserctl/commit/1d0f221b35a855c1991bee5177b7e742ecb16e86))
+
+## [0.2.1](https://github.com/patrick204nqh/browserctl/compare/v0.2.0...v0.2.1) (2026-04-20)
+
+
+### Bug Fixes
+
+* align CLI with standard conventions ([215c2af](https://github.com/patrick204nqh/browserctl/commit/215c2af3a4c4d27397476932147f3fda39e4039c))
+* remove flag_extractor spec after deleting the module ([cd80045](https://github.com/patrick204nqh/browserctl/commit/cd8004515fcbae68248d7133e10d5c0223be10e1))
+* use GH_PAT for release-please to trigger release workflow ([da83358](https://github.com/patrick204nqh/browserctl/commit/da83358e8ff19e8a30c23b9f5d744cb11ffbc7c6))
+* use PAT for release-please to trigger release workflow ([4a9ea99](https://github.com/patrick204nqh/browserctl/commit/4a9ea99f418cbf719a16e2a971672175e0292221))
+
 ## [0.2.0](https://github.com/patrick204nqh/browserctl/compare/v0.1.1...v0.2.0) (2026-04-20)
 
 

data/README.md

@@ -138,6 +138,12 @@ browserctl shutdown
 | `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 |
@@ -262,7 +268,7 @@ browserctl run smoke_login --email me@example.com --password s3cr3t
 
 ### PageProxy methods
 
-`goto(url)` · `fill(selector, value)` · `click(selector)` · `snapshot(**opts)` · `screenshot(**opts)` · `wait_for(selector, timeout: 10)` · `url` · `evaluate(expression)`
+`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`
 
 ---
 

data/bin/browserctl

@@ -3,8 +3,17 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
+require "browserctl/version"
+
+if ARGV.intersect?(%w[--version -v])
+  puts "browserctl #{Browserctl::VERSION}"
+  exit 0
+end
+
 require "json"
+require "optimist"
 require "browserctl"
+require "browserctl/commands/cli_output"
 require "browserctl/commands/open_page"
 require "browserctl/commands/fill"
 require "browserctl/commands/click"
@@ -12,43 +21,68 @@ require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
 require "browserctl/commands/watch"
 require "browserctl/commands/record"
+require "browserctl/commands/pause_resume"
+require "browserctl/commands/init"
+require "browserctl/commands/inspect"
+
+def print_result(res)
+  if res.is_a?(Hash) && res[:error]
+    warn "Error: #{res[:error]}"
+    exit 1
+  end
+  puts res.to_json
+end
 
+# rubocop:disable Metrics/MethodLength
 def usage
   puts <<~USAGE
     Usage: browserctl <command> [args]
 
+    Setup:
+      init                                         Scaffold .browserctl/ in this project
+
     Browser commands (require browserd running):
-      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
-      fill   <page> <selector> <value>     Fill an input
-      click  <page> <selector>             Click an element
-      shot   <page> [--out PATH] [--full]  Take a screenshot
-      snap   <page> [--format ai|html]     Snapshot DOM (default: ai)
-      url    <page>                        Print current URL
-      eval   <page> <expression>           Evaluate JS expression
-      watch  <page> <selector> [--timeout N]  Wait for a selector to appear
+      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
+      fill   <page> <selector> <value>             Fill an input
+             <page> --ref <ref> --value <value>    Fill via snapshot ref
+      click  <page> <selector>                     Click an element
+             <page> --ref <ref>                    Click via snapshot ref
+      shot   <page> [--out PATH] [--full]          Take a screenshot
+      snap   <page> [--format ai|html] [--diff]    Snapshot DOM (default: ai)
+      url    <page>                                Print current URL
+      eval   <page> <expression>                   Evaluate JS expression
+      watch  <page> <selector> [--timeout N]       Wait for a selector to appear
+      pause   <page>                               Pause automation — browser stays live
+      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
 
     Recording commands:
-      record start <name>    Start recording browser commands
-      record stop [--out path]  Stop recording and save workflow
-      record status          Show active recording name
+      record start <name>            Start recording browser commands
+      record stop  [--out PATH]      Stop recording and save workflow
+      record status                  Show active recording name
 
     Workflow commands:
-      run      <name|file> [--key value]   Run a workflow
-      workflows                            List available workflows
-      describe <name>                      Describe a workflow
+      run      <name|file> [--key value ...]   Run a workflow
+      workflows                                List available workflows
+      describe <name>                          Describe a workflow
 
     Daemon commands:
-      ping                                 Check if browserd is alive
-      shutdown                             Stop browserd
+      ping                   Check if browserd is alive
+      shutdown               Stop browserd
 
     Options:
       --daemon <name>    Connect to a named daemon instance
+      --version, -v      Print version and exit
   USAGE
   exit 0
 end
+# rubocop:enable Metrics/MethodLength
 
 daemon_idx  = ARGV.index("--daemon")
 daemon_name = if daemon_idx
@@ -88,24 +122,31 @@ when "describe"
   puts JSON.pretty_generate(runner.describe_workflow(name))
 
 when "record" then Browserctl::Commands::Record.run(args)
+when "init"   then Browserctl::Commands::Init.run(args)
 
 else
   client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
   case cmd
-  when "open"   then Browserctl::Commands::OpenPage.run(client, args)
-  when "close"  then puts client.close_page(args[0]).to_json
-  when "pages"  then puts client.list_pages.to_json
-  when "goto"   then puts client.goto(args[0], args[1]).to_json
-  when "fill"   then Browserctl::Commands::Fill.run(client, args)
-  when "click"  then Browserctl::Commands::Click.run(client, args)
-  when "shot"   then Browserctl::Commands::Screenshot.run(client, args)
-  when "snap"   then Browserctl::Commands::Snapshot.run(client, args)
-  when "url"    then puts client.url(args[0]).to_json
-  when "eval"   then puts client.evaluate(args[0], args[1]).to_json
-  when "watch"  then Browserctl::Commands::Watch.run(client, args)
-  when "ping"   then puts client.ping.to_json
-  when "shutdown" then puts client.shutdown.to_json
+  when "open"     then Browserctl::Commands::OpenPage.run(client, args)
+  when "close"    then print_result(client.close_page(args[0]))
+  when "pages"    then print_result(client.list_pages)
+  when "goto"     then print_result(client.goto(args[0], args[1]))
+  when "fill"     then Browserctl::Commands::Fill.run(client, args)
+  when "click"    then Browserctl::Commands::Click.run(client, args)
+  when "shot"     then Browserctl::Commands::Screenshot.run(client, args)
+  when "snap"     then Browserctl::Commands::Snapshot.run(client, args)
+  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 "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 "ping"     then print_result(client.ping)
+  when "shutdown" then print_result(client.shutdown)
   else
     abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
   end

data/bin/browserd

@@ -7,11 +7,13 @@ require "optimist"
 require "nokogiri"
 require "browserctl/logger"
 require "browserctl/server"
+require "browserctl/version"
 
 opts = Optimist.options do
-  opt :headed,    "Run with a visible browser window",        default: false
-  opt :log_level, "Log verbosity: debug, info, warn, error",  default: "info", type: :string
-  opt :name,      "Daemon instance name for multi-agent use", default: nil, type: :string
+  version "browserd #{Browserctl::VERSION}"
+  opt :headed,    "Run with a visible browser window",        default: false,  short: "-H"
+  opt :log_level, "Log verbosity: debug, info, warn, error",  default: "info", short: "-l", type: :string
+  opt :name,      "Daemon instance name for multi-agent use", default: nil,    short: "-n", type: :string
 end
 
 Browserctl.logger = Browserctl.build_logger(opts[:log_level])

data/examples/cloudflare_hitl.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Demonstrates the Cloudflare HITL (Human-in-the-Loop) pattern.
+#
+# When an agent navigates to a Cloudflare-protected page and hits a bot challenge,
+# it cannot interact with the real page content. This workflow detects the challenge,
+# pauses automation so a human can solve it in the live browser, then resumes.
+#
+# Run:
+#   browserctl run examples/cloudflare_hitl.rb --url https://example.com
+#
+# Note: modern Cloudflare often passes a real headed Chrome without challenge.
+# The pause/resume branch fires only when the challenge page is actually served
+# (typically against headless or CDP-fingerprinted browsers, or stricter zones).
+# When paused, the terminal prints instructions. Solve the challenge in the open
+# browser window, then run: browserctl resume main
+
+Browserctl.workflow "cloudflare_hitl" do
+  desc "Navigate a Cloudflare-protected URL with human-assisted challenge bypass"
+
+  param :url,      required: true
+  param :selector, default: "body"
+
+  step "open page" do
+    client.open_page("main")
+  end
+
+  step "navigate to target URL" do
+    res = client.goto("main", url)
+
+    if res[:challenge]
+      $stdout.puts ""
+      $stdout.puts "  ⚠  Cloudflare challenge detected on #{url}"
+      $stdout.puts "  → Pausing automation. Solve the challenge in the browser, then run:"
+      $stdout.puts "       browserctl resume main"
+      $stdout.puts ""
+
+      client.pause("main")
+
+      # Block here until the human calls `browserctl resume main`.
+      # The pause command marks the page; resume unblocks and signals the CV.
+      # In a workflow context, we poll the server until the page is unpaused
+      # by attempting a lightweight snapshot — once it succeeds, we're through.
+      loop do
+        snap = client.snapshot("main", format: "html")
+        break unless snap[:challenge]
+
+        $stdout.puts "  … still on challenge page, waiting 3s"
+        sleep 3
+      end
+
+      $stdout.puts "  ✓ Challenge cleared — resuming automation"
+    end
+  end
+
+  step "wait for content and snapshot" do
+    page(:main).wait_for(selector, timeout: 15)
+    result = page(:main).snapshot(format: "ai")
+    $stdout.puts "  Snapshot: #{result[:snapshot]&.length || 0} elements captured"
+  end
+
+  step "close page" do
+    client.close_page("main")
+  end
+end

data/lib/browserctl/client.rb

@@ -6,6 +6,7 @@ require_relative "constants"
 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
@@ -19,42 +20,138 @@ module Browserctl
       raise "browserd is not running — start it with: browserd"
     end
 
-    # Convenience wrappers matching CLI command vocabulary
-
+    # Opens or focuses a named browser page.
+    # @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)
+
+    # 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)
+
+    # Lists all open page names.
+    # @return [Hash] `{ pages: [String] }`
     def list_pages                 = call("list_pages")
+
+    # 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)
 
+    # Clicks an element identified by CSS selector or snapshot ref.
+    # @param name [String] logical page name
+    # @param selector [String, nil] CSS selector
+    # @param ref [String, nil] snapshot ref (e.g. "e3")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
     def click(name, selector = nil, ref: nil)
       raise ArgumentError, "click: provide selector or ref:" unless selector || ref
 
       call("click", name: name, selector: selector, ref: ref)
     end
 
+    # Fills an input element with a value.
+    # @param name [String] logical page name
+    # @param selector [String, nil] CSS selector
+    # @param value [String, nil] text to type
+    # @param ref [String, nil] snapshot ref
+    # @return [Hash] `{ ok: true }` or `{ error: }`
     def fill(name, selector = nil, value = nil, ref: nil)
       raise ArgumentError, "fill: provide selector or ref:" unless selector || ref
 
       call("fill", name: name, selector: selector, ref: ref, value: value)
     end
 
+    # Takes a screenshot of a named page.
+    # @param name [String] logical page name
+    # @param path [String, nil] output path (default: ~/.browserctl/screenshots/)
+    # @param full [Boolean] capture full page (default: false)
+    # @return [Hash] `{ ok: true, path: }` or `{ error: }`
     def screenshot(name, path: nil, full: false) = call("screenshot", name: name, path: path, full: full)
 
+    # Takes a DOM snapshot. Returns `challenge: true` when Cloudflare is detected.
+    # @param name [String] logical page name
+    # @param format [String] "ai" (token-efficient JSON) or "html" (raw HTML)
+    # @param diff [Boolean] return only elements changed since last snapshot
+    # @return [Hash] `{ ok: true, snapshot:, challenge: }` or `{ ok: true, html:, challenge: }` or `{ error: }`
     def snapshot(name, format: "ai", diff: false)
       call("snapshot", name: name, format: format, diff: diff)
     end
 
+    # Waits for a CSS selector to appear (short 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
 
+    # 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)
+
+    # 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)
+
+    # Checks if browserd is alive.
+    # @return [Hash] `{ ok: true, pid: }` or raises if daemon is not running
     def ping                       = call("ping")
+
+    # Shuts down browserd gracefully.
+    # @return [Hash] `{ ok: true }`
     def shutdown                   = call("shutdown")
 
+    # 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)
+
+    # 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)
+
+    # 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)
+
+    # 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)
+
+    # Sets a cookie on a named page.
+    # @param name [String] logical page name
+    # @param cookie_name [String] cookie name (e.g. "cf_clearance")
+    # @param value [String] cookie value
+    # @param domain [String] cookie domain (e.g. ".example.com")
+    # @param path [String] cookie path (default: "/")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def set_cookie(name, cookie_name, value, domain, path: "/")
+      call("set_cookie", name: name, cookie_name: cookie_name,
+                         value: value, domain: domain, path: path)
+    end
+
+    # Clears 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)
+
     private
 
     def communicate(payload)

data/lib/browserctl/commands/cli_output.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    module CliOutput
+      def print_result(res)
+        if res.is_a?(Hash) && res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        puts res.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/click.rb

@@ -1,21 +1,27 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class Click
+      extend CliOutput
+
       def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl click <page> <selector>\n       " \
+                 "browserctl click <page> --ref <ref>"
+          opt :ref, "Snapshot ref to click", type: :string, short: "-r"
+        end
         name = args.shift
-        ref  = FlagExtractor.extract_opt(args, "--ref")
-        selector = args.shift unless ref
-
-        if ref
+        if opts[:ref]
           abort "usage: browserctl click <page> --ref <ref>" unless name
-          puts client.click(name, ref: ref).to_json
+          print_result(client.click(name, ref: opts[:ref]))
         else
+          selector = args.shift
           abort "usage: browserctl click <page> <selector>" unless name && selector
-          puts client.click(name, selector).to_json
+          print_result(client.click(name, selector))
         end
       end
     end

data/lib/browserctl/commands/fill.rb

@@ -1,23 +1,37 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class Fill
+      extend CliOutput
+
       def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl fill <page> <selector> <value>\n       " \
+                 "browserctl fill <page> --ref <ref> --value <value>"
+          opt :ref,   "Snapshot ref to fill", type: :string, short: "-r"
+          opt :value, "Value to fill",        type: :string, short: "-V"
+        end
         name = args.shift
-        ref  = FlagExtractor.extract_opt(args, "--ref")
+        opts[:ref] ? fill_by_ref(client, name, opts) : fill_by_selector(client, name, args, opts[:value])
+      end
+
+      class << self
+        private
+
+        def fill_by_ref(client, name, opts)
+          abort "usage: browserctl fill <page> --ref <ref> --value <value>" unless name && opts[:value]
+          print_result(client.fill(name, nil, opts[:value], ref: opts[:ref]))
+        end
 
-        if ref
-          value = FlagExtractor.extract_opt(args, "--value")
-          abort "usage: browserctl fill <page> --ref <ref> --value <value>" unless name && value
-          puts client.fill(name, nil, value, ref: ref).to_json
-        else
+        def fill_by_selector(client, name, args, value_opt)
           selector = args.shift
-          value = args.shift
+          value    = value_opt || args.shift
           abort "usage: browserctl fill <page> <selector> <value>" unless name && selector && value
-          puts client.fill(name, selector, value).to_json
+          print_result(client.fill(name, selector, value))
         end
       end
     end

data/lib/browserctl/commands/init.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Browserctl
+  module Commands
+    class Init
+      CONFIG_TEMPLATE = <<~YAML
+        # browserctl project configuration
+        # Uncomment and edit to customise.
+
+        # daemon: default          # named daemon instance (see browserd --name)
+        # workflows_dir: .browserctl/workflows
+      YAML
+
+      def self.run(_args)
+        FileUtils.mkdir_p(".browserctl/workflows")
+        FileUtils.touch(".browserctl/workflows/.keep")
+
+        config_path = ".browserctl/config.yml"
+        File.write(config_path, CONFIG_TEMPLATE) unless File.exist?(config_path)
+
+        puts "Initialised browserctl project:"
+        puts "  .browserctl/workflows/   (place workflow .rb files here)"
+        puts "  .browserctl/config.yml   (project settings)"
+      end
+    end
+  end
+end

data/lib/browserctl/commands/inspect.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class Inspect
+      def self.run(client, args)
+        name = args.shift or abort "usage: browserctl inspect <page>"
+        res = client.inspect_page(name)
+        if res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        url = res[:devtools_url]
+        puts "Opening DevTools for '#{name}':"
+        puts "  #{url}"
+        opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
+        system(opener, url)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/open_page.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class OpenPage
+      extend CliOutput
+
       def self.run(client, args)
-        name = args.shift or abort "usage: browserctl open <name> [--url URL]"
-        url  = FlagExtractor.extract_opt(args, "--url")
-        res  = client.open_page(name, url: url)
-        puts res.to_json
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl open <page> [--url URL]"
+          opt :url, "URL to navigate to", type: :string, short: "-u"
+        end
+        name = args.shift or abort "usage: browserctl open <page> [--url URL]"
+        print_result(client.open_page(name, url: opts[:url]))
       end
     end
   end