browserctl 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff8250901d49ad1038c686f51d303f2139fe673c708746804cdb59e1239890fe
-  data.tar.gz: b47c1e8dbf9093ffe43001d8cacf02c490c887fb5e58336449f1b7aedebfda0b
+  metadata.gz: 0f20046bbdcf3ff57a52790137144c5f1197b6d3f8651f250bf6feb1cc9988f7
+  data.tar.gz: 1d928edc69e4691cc720b9bb7f32ea4001d1fd5df636a4af7fc59341f7714174
 SHA512:
-  metadata.gz: e11c9a8300e7ec744e70ad5f33b645c9afc59e4e5212696045e899f4f2da017d1e4589f750db65b004d8e8208092d6a031724474a2a8feb48f249ed1daa83262
-  data.tar.gz: 1a48cb05e7d92ab6dfd2de777abd0d8904a30b27c8d03fdaee2c00d1b5b734a9f8499be90ea30db686022a5c0d9ad7532ea1c1f148f0e1047a0583a954048dd8
+  metadata.gz: 87be1521e16f71d8f77c699712fb03c7a339b2421102e6ad0d4bc9c1a0e860ff29882c81d0e5819a802b3364962922594bd9a08d80cdf5521e50ea09659dac98
+  data.tar.gz: 29256e3d109bdfa651e8bea5fb82eef18fcb2b299c648db937015cebbfddd0d947e3e042b848adf32b61006f99d69150aaf38acf2a1356946c1584e2dc7a00b6

data/CHANGELOG.md

@@ -10,6 +10,44 @@ 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.11.0](https://github.com/patrick204nqh/browserctl/compare/v0.10.0...v0.11.0) (2026-05-10)
+
+
+### Features
+
+* .bctl bundle codec ([#94](https://github.com/patrick204nqh/browserctl/issues/94)) ([75a4370](https://github.com/patrick204nqh/browserctl/commit/75a43704abf9cf766435fff35409333514fd3c73))
+* auth_required detector ([#99](https://github.com/patrick204nqh/browserctl/issues/99)) ([6d9554f](https://github.com/patrick204nqh/browserctl/commit/6d9554f7cbe9b8e93d22c42b03ff2ce59e594f28))
+* AUTH_REQUIRED structured error code ([#100](https://github.com/patrick204nqh/browserctl/issues/100)) ([9928a4e](https://github.com/patrick204nqh/browserctl/commit/9928a4e7d456d0382b2244096fb38ebeee55013d))
+* browserctl flow run/list/describe CLI ([#89](https://github.com/patrick204nqh/browserctl/issues/89)) ([5016fe5](https://github.com/patrick204nqh/browserctl/commit/5016fe54ee1414b967025f450ded79565ef9bcfb))
+* drift telemetry (WS-2.4) ([#114](https://github.com/patrick204nqh/browserctl/issues/114)) ([712da07](https://github.com/patrick204nqh/browserctl/commit/712da075e623a2aa27a779958b94c0f6e92384c8))
+* element fingerprint (WS-1.2) ([#107](https://github.com/patrick204nqh/browserctl/issues/107)) ([8a8b6b4](https://github.com/patrick204nqh/browserctl/commit/8a8b6b45121cb179919fae8c3f87a4584d4b4bc1))
+* enriched recording log (WS-3.1) ([#115](https://github.com/patrick204nqh/browserctl/issues/115)) ([c00787d](https://github.com/patrick204nqh/browserctl/commit/c00787dc5f208cf69cd4a0326d4df19ed31e3bfc))
+* fingerprint matcher (WS-2.1) ([#111](https://github.com/patrick204nqh/browserctl/issues/111)) ([1d99d20](https://github.com/patrick204nqh/browserctl/commit/1d99d208f5d3815c8ef1e59e3d549d15c3719712))
+* flow registry ([#86](https://github.com/patrick204nqh/browserctl/issues/86)) ([31579dd](https://github.com/patrick204nqh/browserctl/commit/31579dd20156a700ace15137b34b120d16c86b6f))
+* inferred waits (WS-3.3) ([#117](https://github.com/patrick204nqh/browserctl/issues/117)) ([9332754](https://github.com/patrick204nqh/browserctl/commit/93327545b1d21e00c16037c6730f019b574bc572))
+* invoke flows from workflow DSL ([#88](https://github.com/patrick204nqh/browserctl/issues/88)) ([61fdc0a](https://github.com/patrick204nqh/browserctl/commit/61fdc0a6c98fdaf29c5034b80ccc54fdfb447e3a))
+* load_state auto re-run + on_auth_required hook ([#101](https://github.com/patrick204nqh/browserctl/issues/101)) ([8328d13](https://github.com/patrick204nqh/browserctl/commit/8328d1348d2be8ec685ece9dec3cafb0eb26eb90))
+* postcondition extraction (WS-3.4) ([#118](https://github.com/patrick204nqh/browserctl/issues/118)) ([56e76d5](https://github.com/patrick204nqh/browserctl/commit/56e76d50814d9c9a539ea56b20e6936d62509fcf))
+* replay fallback in PageProxy (WS-2.2) ([#112](https://github.com/patrick204nqh/browserctl/issues/112)) ([50714fc](https://github.com/patrick204nqh/browserctl/commit/50714fcd2ff16614af0d18c8b390084e3f32511e))
+* stable ref derivation (v0.11 WS-1.1) ([#106](https://github.com/patrick204nqh/browserctl/issues/106)) ([86df66a](https://github.com/patrick204nqh/browserctl/commit/86df66aaa9fc0b6c7a3a285c572ba2941b301e55))
+* state export/import with file/s3/op transports ([#96](https://github.com/patrick204nqh/browserctl/issues/96)) ([f1dd97b](https://github.com/patrick204nqh/browserctl/commit/f1dd97b895503ee19e60f14bbb9df81dcb321bd1))
+* state rotate ([#97](https://github.com/patrick204nqh/browserctl/issues/97)) ([78bb091](https://github.com/patrick204nqh/browserctl/commit/78bb091194e12e12867d7be0f566d426bdcb3b14))
+* state save/load/list/info/delete ([#95](https://github.com/patrick204nqh/browserctl/issues/95)) ([4502cd1](https://github.com/patrick204nqh/browserctl/commit/4502cd1e8992f486b34ce2288a34a9ef78808617))
+* stdlib flow — cloudflare_solve ([#93](https://github.com/patrick204nqh/browserctl/issues/93)) ([b4411b9](https://github.com/patrick204nqh/browserctl/commit/b4411b94af669d435346006c5f9304258456ba7b))
+* stdlib flow — totp_2fa ([#90](https://github.com/patrick204nqh/browserctl/issues/90)) ([c23e574](https://github.com/patrick204nqh/browserctl/commit/c23e574887e1ef3324e41e988a8f8047079ac998))
+* stdlib flows — basic_auth, magic_link_email ([#91](https://github.com/patrick204nqh/browserctl/issues/91)) ([e401d60](https://github.com/patrick204nqh/browserctl/commit/e401d60b4cf5b4b9f2b4138c45a9b19275a089e7))
+* stdlib flows — oauth_google, oauth_github ([#92](https://github.com/patrick204nqh/browserctl/issues/92)) ([04c9586](https://github.com/patrick204nqh/browserctl/commit/04c9586ff83503b7d94a2c73fe9c3360f01dc4ca))
+* workflow generate (WS-3.2) ([#116](https://github.com/patrick204nqh/browserctl/issues/116)) ([90dca3b](https://github.com/patrick204nqh/browserctl/commit/90dca3bada9b53f91e9be39e3d94d0208dcfa181))
+* workflow promote --as-flow (WS-3.7) ([#121](https://github.com/patrick204nqh/browserctl/issues/121)) ([a5e4b30](https://github.com/patrick204nqh/browserctl/commit/a5e4b30a30559e8fa6b3f4ff3df7189dc3d6bd1e))
+* workflow promote (WS-3.6) ([#120](https://github.com/patrick204nqh/browserctl/issues/120)) ([4355353](https://github.com/patrick204nqh/browserctl/commit/4355353213586dedf9f348f0fd211d1f0d3d72c6))
+* workflow run --check + drift report (WS-2.3) ([#113](https://github.com/patrick204nqh/browserctl/issues/113)) ([7cb4bc7](https://github.com/patrick204nqh/browserctl/commit/7cb4bc7d967f4045e5709eacabb0408edf21f9f1))
+* workflow run --check snapshot-diff (WS-3.5) ([#119](https://github.com/patrick204nqh/browserctl/issues/119)) ([1d131d8](https://github.com/patrick204nqh/browserctl/commit/1d131d85ea6e7948e9e734de6531c2d8dd194388))
+
+
+### Bug Fixes
+
+* pass first open page to flow during load_state auto-rotate ([#105](https://github.com/patrick204nqh/browserctl/issues/105)) ([2c67733](https://github.com/patrick204nqh/browserctl/commit/2c67733fc4f879fc40833194e9e71e32cd3096a8))
+
 ## [0.10.0](https://github.com/patrick204nqh/browserctl/compare/v0.9.0...v0.10.0) (2026-05-09)
 
 

data/README.md

@@ -196,7 +196,7 @@ The daemon shuts itself down after 30 minutes of inactivity.
 |---|---|
 | [Getting Started](docs/getting-started.md) | Install, first session, first snapshot |
 | [Agent Integration](docs/guides/agent-integration.md) | Call browserctl from Python, shell, or Anthropic tool-use agents |
-| [Concepts](docs/concepts/) | Sessions, snapshots, human-in-the-loop |
+| [Concepts](docs/concepts/) | Sessions, snapshots, [state](docs/concepts/state.md), [flows](docs/concepts/flows.md), human-in-the-loop |
 | [Guides](docs/guides/) | Writing workflows, handling challenges, smoke testing |
 | [Examples](examples/) | Runnable scripts: session reuse, Cloudflare HITL, and more |
 | [Command Reference](docs/reference/commands.md) | Every command and flag |

data/bin/browserctl

@@ -25,15 +25,18 @@ require "browserctl/commands/page"
 require "browserctl/commands/cookie"
 require "browserctl/commands/storage"
 require "browserctl/commands/session"
+require "browserctl/commands/state"
 require "browserctl/commands/daemon"
 require "browserctl/commands/workflow"
+require "browserctl/commands/flow"
 require "browserctl/commands/dialog"
 require "browserctl/commands/ask"
 
 def print_result(res)
-  if res.is_a?(Hash) && res[:error]
-    warn "Error: #{res[:error]}"
-    exit 1
+  if res.is_a?(Hash) && (res[:error] || res["error"])
+    warn "Error: #{res[:error] || res['error']}"
+    puts res.to_json
+    exit((res[:code] || res["code"]) == "AUTH_REQUIRED" ? 7 : 1)
   end
   puts res.to_json
 end
@@ -95,15 +98,36 @@ def usage
       session export <name> <path>
       session import <path>
 
+    Auth detection:
+      auth-check <page> [--cookies] [--state NAME] [--flow NAME]
+        # Exits 7 with code: AUTH_REQUIRED when the page needs login.
+
+    State (.bctl bundles — cookies + storage + flow binding):
+      state save   <name> [--encrypt] [--origins a,b] [--flow NAME]
+      state load   <name>
+      state list
+      state info   <name>
+      state delete <name>
+      state rotate <name> [--page NAME] [--params FILE] [--key value ...]
+      state export <name> <destination>     # file path, s3://..., op://Vault/Item
+      state import <source> [--name NAME]
+
     Recording:
       record start <name>
       record stop  [--out PATH]
       record status
 
     Workflow:
-      workflow run      <name|file> [--params file] [--key value ...]
+      workflow run      <name|file> [--check] [--params file] [--key value ...]
       workflow list
       workflow describe <name>
+      workflow generate <recording> [--out PATH]
+      workflow promote  <name> [--force] [--threshold N] [--as-flow]
+
+    Flow:
+      flow run      <name|file> [--page NAME] [--params file] [--key value ...]
+      flow list
+      flow describe <name>
 
     Daemon:
       daemon start  [--headed] [--name NAME]
@@ -142,11 +166,28 @@ else
   client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
   case cmd
+  when "flow"     then Browserctl::Commands::Flow.run(client, args)
   when "page"     then Browserctl::Commands::Page.run(client, args)
   when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
   when "storage"  then Browserctl::Commands::Storage.run(client, args)
   when "session"  then Browserctl::Commands::Session.run(client, args)
+  when "state"    then Browserctl::Commands::State.run(client, args)
   when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
+  when "auth-check"
+    page_name = args.shift or abort "usage: browserctl auth-check <page> [--cookies] [--state NAME] [--flow NAME]"
+    include_cookies = args.delete("--cookies") ? true : false
+    state_idx = args.index("--state")
+    state_arg = if state_idx
+                  (args.delete_at(state_idx)
+                   args.delete_at(state_idx))
+                end
+    flow_idx  = args.index("--flow")
+    flow_arg  = if flow_idx
+                  (args.delete_at(flow_idx)
+                   args.delete_at(flow_idx))
+                end
+    print_result(client.auth_check(page_name, include_cookies: include_cookies,
+                                              state: state_arg, suggested_flow: flow_arg))
   when "navigate" then print_result(client.navigate(args[0], args[1]))
   when "fill"     then Browserctl::Commands::Fill.run(client, args)
   when "click"    then Browserctl::Commands::Click.run(client, args)

data/lib/browserctl/client.rb

@@ -15,7 +15,7 @@ module Browserctl
 
     def call(cmd, **params)
       result = communicate(JSON.generate({ cmd: cmd }.merge(params)))
-      Recording.append(cmd, **params) if result[:ok]
+      Recording.append(cmd, response: result, **params) if result[:ok]
       result
     rescue Errno::ENOENT, Errno::ECONNREFUSED
       raise DaemonUnavailableError, "browserd is not running — start it with: browserd"
@@ -50,7 +50,8 @@ module Browserctl
     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)
+      call("click", name: name, selector: selector, ref: ref,
+                    capture_post_snapshot: Recording.active ? true : nil)
     end
 
     # Fills an input element with a value.
@@ -62,7 +63,8 @@ module Browserctl
     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)
+      call("fill", name: name, selector: selector, ref: ref, value: value,
+                   capture_post_snapshot: Recording.active ? true : nil)
     end
 
     # Takes a screenshot of a named page.
@@ -308,6 +310,48 @@ module Browserctl
       call("session_delete", session_name: session_name)
     end
 
+    # Saves browser state (cookies + storage) into a single .bctl bundle.
+    # @return [Hash] `{ ok:, path:, origins:, cookies:, encrypted: }` or `{ error: }`
+    def state_save(name, origins: nil, flow: nil, flow_version: nil, passphrase: nil)
+      call("state_save",
+           name: name, origins: origins, flow: flow,
+           flow_version: flow_version, passphrase: passphrase)
+    end
+
+    # Restores a .bctl bundle into the running daemon. The daemon runs the
+    # auth_required detector against the bundle's cookies before applying;
+    # callers that have already verified the bundle (e.g. workflow
+    # `load_state` after a successful rotate) can pass `skip_auth_check: true`
+    # to bypass it.
+    def state_load(name, passphrase: nil, skip_auth_check: false)
+      call("state_load", name: name, passphrase: passphrase, skip_auth_check: skip_auth_check)
+    end
+
+    # Lists all stored state bundles (manifest only — no payload decryption).
+    def state_list = call("state_list")
+
+    # Reads a single bundle's manifest.
+    def state_info(name) = call("state_info", name: name)
+
+    # Permanently deletes a state bundle.
+    def state_delete(name) = call("state_delete", name: name)
+
+    # Runs the auth_required detector against a named page. Returns either
+    # `{ ok: true, auth_required: false }` or an AUTH_REQUIRED error response.
+    # @param name [String] page name
+    # @param include_cookies [Boolean] also feed the page's current cookies
+    #   into the detector (catches expired-cookie auth)
+    # @param state [String, nil] bundle name the caller was working with;
+    #   passed back verbatim so callers can recover without bookkeeping
+    # @param suggested_flow [String, nil] flow name to surface when triggered
+    def auth_check(name, include_cookies: false, state: nil, suggested_flow: nil)
+      call("auth_check",
+           name: name,
+           include_cookies: include_cookies,
+           state: state,
+           suggested_flow: suggested_flow)
+    end
+
     private
 
     def auto_discover_socket

data/lib/browserctl/commands/cli_output.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
+
 module Browserctl
   module Commands
     module CliOutput
+      AUTH_REQUIRED_EXIT_CODE = Browserctl::AuthRequiredError::AUTH_REQUIRED_EXIT_CODE
+
       def print_result(res)
-        if res.is_a?(Hash) && res[:error]
-          warn "Error: #{res[:error]}"
-          exit 1
+        if res.is_a?(Hash) && (res[:error] || res["error"])
+          warn "Error: #{res[:error] || res['error']}"
+          puts res.to_json
+          exit exit_code_for(res)
         end
         puts res.to_json
       end
+
+      # Maps a daemon error response onto a process exit code. Defaults to 1;
+      # special-cased only for codes that callers programmatically branch on.
+      def exit_code_for(res)
+        return AUTH_REQUIRED_EXIT_CODE if (res[:code] || res["code"]) == "AUTH_REQUIRED"
+
+        1
+      end
     end
   end
 end

data/lib/browserctl/commands/flow.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cli_output"
+require_relative "../flow_registry"
+require_relative "../runner"
+
+module Browserctl
+  module Commands
+    module Flow
+      extend CliOutput
+
+      USAGE = "Usage: browserctl flow <run|list|describe> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "run"      then run_flow(client, args)
+        when "list"     then run_list
+        when "describe" then run_describe(args)
+        else abort "unknown flow subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_flow(client, args)
+        name = args.shift or
+          abort "usage: browserctl flow run <name|file> [--page NAME] [--params FILE] [--key value ...]"
+
+        flow = resolve(name)
+        page_name, params = parse_run_args(args)
+        page_proxy = page_name ? Browserctl::PageProxy.new(page_name, client) : nil
+
+        result = flow.run(page: page_proxy, client: client, **params)
+        puts JSON.generate(ok: true, flow: flow.name, result: serialisable(result))
+      rescue Browserctl::FlowError => e
+        warn "Error: #{e.message}"
+        puts JSON.generate(ok: false, code: e.code, error: e.message)
+        exit 1
+      end
+
+      def self.run_list
+        entries = Browserctl::FlowRegistry.list
+        puts JSON.generate(flows: entries)
+      end
+
+      def self.run_describe(args)
+        name = args.shift or abort "usage: browserctl flow describe <name>"
+        flow = resolve(name)
+        puts JSON.pretty_generate(
+          name: flow.name,
+          desc: flow.description,
+          version: flow.version_string,
+          requires_browserctl: flow.min_browserctl_version,
+          params: format_params(flow),
+          preconditions: flow.preconditions.map(&:label),
+          steps: flow.steps.map(&:label),
+          postconditions: flow.postconditions.map(&:label),
+          produces_state: !flow.produces_state_block.nil?
+        )
+      end
+
+      def self.resolve(name_or_path)
+        if File.exist?(name_or_path)
+          before = Browserctl.flow_registry_snapshot.keys
+          load File.expand_path(name_or_path)
+          new_name = (Browserctl.flow_registry_snapshot.keys - before).first
+          new_name ||= File.basename(name_or_path, ".rb")
+          flow = Browserctl.lookup_flow(new_name)
+        else
+          flow = Browserctl::FlowRegistry.resolve(name_or_path)
+        end
+        flow or abort "flow '#{name_or_path}' not found"
+      end
+
+      def self.parse_run_args(args)
+        page_name = take_option(args, "--page")
+        params_path = take_option(args, "--params")
+        file_params = params_path ? load_params_file(params_path) : {}
+        cli_params = pair_args(args)
+        [page_name, file_params.merge(cli_params)]
+      end
+
+      def self.take_option(args, flag)
+        idx = args.index(flag)
+        return nil unless idx
+
+        value = args.delete_at(idx + 1)
+        args.delete_at(idx)
+        value
+      end
+
+      def self.load_params_file(path)
+        Browserctl::Runner.load_params_file(path)
+      rescue StandardError => e
+        abort "Error loading params file: #{e.message}"
+      end
+
+      def self.pair_args(args)
+        out = {}
+        args.each_slice(2) do |flag, val|
+          out[flag.sub(/\A--/, "").to_sym] = val
+        end
+        out
+      end
+
+      def self.format_params(flow)
+        flow.param_defs.transform_values do |p|
+          entry = { required: p.required, secret: p.secret, default: p.default }
+          entry[:secret_ref] = p.secret_ref if p.secret_ref
+          entry
+        end
+      end
+
+      def self.serialisable(value)
+        case value
+        when nil, true, false, Numeric, String, Hash, Array then value
+        when Symbol then value.to_s
+        else value.respond_to?(:to_h) ? value.to_h : value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/commands/state.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "json"
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    # `browserctl state` — top-level command for portable, encrypted, origin-
+    # scoped browser state. Wraps the daemon's state_* RPCs.
+    module State
+      extend CliOutput
+
+      USAGE = "Usage: browserctl state <save|load|list|info|delete|rotate|export|import> [args]"
+
+      DAEMON_SUBCOMMANDS = {
+        "save" => :run_save, "load" => :run_load, "list" => :run_list,
+        "info" => :run_info, "delete" => :run_delete, "rotate" => :run_rotate
+      }.freeze
+
+      LOCAL_SUBCOMMANDS = { "export" => :run_export, "import" => :run_import }.freeze
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+
+        if (m = DAEMON_SUBCOMMANDS[sub])
+          sub == "list" ? send(m, client) : send(m, client, args)
+        elsif (m = LOCAL_SUBCOMMANDS[sub])
+          send(m, args)
+        else
+          abort "unknown state subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_save(client, args)
+        encrypt = args.delete("--encrypt")
+        origins = extract_value!(args, "--origins")
+        flow    = extract_value!(args, "--flow")
+        name    = args.shift or abort "usage: browserctl state save <name> [--encrypt] " \
+                                      "[--origins a,b] [--flow NAME]"
+
+        passphrase = encrypt ? prompt_passphrase(confirm: true) : nil
+        origin_list = parse_origins(origins)
+
+        print_result(client.state_save(name, origins: origin_list, flow: flow, passphrase: passphrase))
+      end
+
+      def self.parse_origins(value)
+        return nil unless value
+
+        value.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def self.run_load(client, args)
+        name = args.shift or abort "usage: browserctl state load <name>"
+        passphrase = state_needs_passphrase?(client, name) ? prompt_passphrase : nil
+        print_result(client.state_load(name, passphrase: passphrase))
+      end
+
+      def self.run_list(client)
+        print_result(client.state_list)
+      end
+
+      def self.run_info(client, args)
+        name = args.shift or abort "usage: browserctl state info <name>"
+        print_result(client.state_info(name))
+      end
+
+      def self.run_delete(client, args)
+        name = args.shift or abort "usage: browserctl state delete <name>"
+        print_result(client.state_delete(name))
+      end
+
+      # Re-runs the flow bound to <name> and re-saves the bundle. The flow is
+      # read from the manifest (set when the bundle was originally produced
+      # via `state save --flow ...`). Params come from --params or k=v pairs.
+      def self.run_rotate(client, args)
+        require "browserctl/flow_registry"
+        page_name   = extract_value!(args, "--page")
+        params_path = extract_value!(args, "--params")
+        name        = args.shift or abort "usage: browserctl state rotate <name> " \
+                                          "[--page NAME] [--params FILE] [--key value ...]"
+
+        manifest = read_manifest!(client, name)
+        flow     = resolve_bound_flow!(manifest)
+        params   = build_rotate_params(params_path, args)
+        page_proxy = page_name ? Browserctl::PageProxy.new(page_name, client) : nil
+
+        flow.run(page: page_proxy, client: client, **params)
+
+        save_result = client.state_save(name,
+                                        flow: flow.name,
+                                        flow_version: flow.version_string,
+                                        origins: manifest[:origins])
+        print_result(save_result.merge(rotated_flow: flow.name))
+      rescue Browserctl::FlowError => e
+        warn "Error: #{e.message}"
+        exit 1
+      end
+
+      def self.read_manifest!(client, name)
+        info = client.state_info(name)
+        abort "Error: #{info[:error] || info['error']}" if info[:error] || info["error"]
+
+        info[:info] || info["info"] || {}
+      end
+      private_class_method :read_manifest!
+
+      def self.resolve_bound_flow!(manifest)
+        flow_name = manifest[:flow] || manifest["flow"]
+        abort "Error: state has no bound flow — re-save with `state save --flow NAME` first" if flow_name.nil? ||
+                                                                                                flow_name.to_s.empty?
+
+        flow = Browserctl::FlowRegistry.resolve(flow_name)
+        abort "Error: flow '#{flow_name}' not found in registry" unless flow
+
+        flow
+      end
+      private_class_method :resolve_bound_flow!
+
+      def self.build_rotate_params(params_path, args)
+        require "browserctl/runner"
+        file_params = params_path ? Browserctl::Runner.load_params_file(params_path) : {}
+        cli_params  = args.each_slice(2).to_h { |flag, val| [flag.to_s.sub(/\A--/, "").to_sym, val] }
+        file_params.merge(cli_params)
+      end
+      private_class_method :build_rotate_params
+
+      def self.run_export(args)
+        name        = args.shift or abort "usage: browserctl state export <name> <destination>"
+        destination = args.shift or abort "usage: browserctl state export <name> <destination>"
+        require "browserctl/state"
+        result = Browserctl::State.export(name, destination)
+        puts result.to_json
+      rescue Browserctl::State::Transport::TransportError, Browserctl::Error, ArgumentError => e
+        warn "Error: #{e.message}"
+        exit 1
+      end
+
+      def self.run_import(args)
+        name_override = extract_value!(args, "--name")
+        source        = args.shift or abort "usage: browserctl state import <source> [--name NAME]"
+        require "browserctl/state"
+        result = Browserctl::State.import(source, name: name_override)
+        puts result.to_json
+      rescue Browserctl::State::Transport::TransportError,
+             Browserctl::State::Bundle::BundleError,
+             Browserctl::Error, ArgumentError => e
+        warn "Error: #{e.message}"
+        exit 1
+      end
+
+      private_class_method :parse_origins
+
+      def self.extract_value!(args, flag)
+        idx = args.index(flag)
+        return nil unless idx
+
+        args.delete_at(idx)
+        args.delete_at(idx) or abort "missing value for #{flag}"
+      end
+      private_class_method :extract_value!
+
+      def self.prompt_passphrase(confirm: false)
+        return ENV["BROWSERCTL_STATE_PASSPHRASE"] if ENV["BROWSERCTL_STATE_PASSPHRASE"]
+
+        $stderr.print "Passphrase: "
+        pass = $stdin.noecho(&:gets).to_s.chomp
+        $stderr.puts
+
+        if confirm
+          $stderr.print "Confirm passphrase: "
+          confirm_pass = $stdin.noecho(&:gets).to_s.chomp
+          $stderr.puts
+          abort "Passphrases do not match." unless pass == confirm_pass
+        end
+
+        pass
+      end
+      private_class_method :prompt_passphrase
+
+      # Peek at the manifest first so we only prompt for a passphrase when needed.
+      def self.state_needs_passphrase?(client, name)
+        info = client.state_info(name)
+        return false if info[:error] || info["error"]
+
+        manifest = info[:info] || info["info"] || {}
+        manifest[:encrypted] || manifest["encrypted"] || false
+      end
+      private_class_method :state_needs_passphrase?
+    end
+  end
+end