aspera-cli 4.26.2 → 4.27.0

data/lib/aspera/cli/sync_actions.rb

@@ -14,21 +14,45 @@ module Aspera
         (1..18).map{ |i| "P(#{i})"} +
         %w[Syncd Error Confl Pconf] +
         (23..24).map{ |i| "P(#{i})"}).freeze
+      # When a plugin class includes SyncActions, register the :sql option
+      # in that class's DSL registry so Base#initialize auto-declares it.
       class << self
-        def declare_options(options)
-          options.declare(:sql, 'SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)')
+        def included(base)
+          base.option(:sql, description: 'SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)')
+        end
+
+        # DSL helper: register the 7 `sync admin` leaf commands under the given parent path.
+        # Called at class-load time from any plugin that includes SyncActions.
+        # @param base        [Class]          the plugin class (receiver of DSL methods)
+        # @param admin_path  [Symbol, Array<Symbol>]  full parent path, e.g. %i[sync admin]
+        def register_sync_admin_commands(base, admin_path)
+          path_and_info_args = [{name: :path, type: String}, {name: :sync_info, type: Hash, mandatory: false, default: {}}]
+          base.commands_under(admin_path) do
+            base.command(:status,    description: 'Show sync session status',     arguments: path_and_info_args, action: :action_sync_admin_status)
+            base.command(:find,      description: 'Find sync database files',     arguments: [{name: :path, type: String}], action: :action_sync_admin_find)
+            base.command(:meta,      description: 'Show sync session metadata',   arguments: path_and_info_args, action: :action_sync_admin_meta)
+            base.command(:counters,  description: 'Show sync counters',           arguments: path_and_info_args, action: :action_sync_admin_counters)
+            base.command(:file_info, description: 'Show per-file sync state',     arguments: path_and_info_args, action: :action_sync_admin_file_info)
+            base.command(:overview,  description: 'Show sync database overview',  arguments: path_and_info_args, action: :action_sync_admin_overview)
+            base.command(:query,     description: 'Execute a raw SQL query',      arguments: path_and_info_args, action: :action_sync_admin_query)
+          end
         end
       end
 
-      # Read 1 or 2 command line arguments and converts to `sync_info` format
+      # Convert path + sync_info to internal `sync_info` format.
       # The resulting sync_info has `args` format only if it contains one of the `sessions` or `instance` keys.
       # It has the `conf` format (default) otherwise.
       # If the `conf` format is detected, then both `local` and `remote` keys are set.
-      # @param direction [Symbol,NilClass] One of directions, or `nil` if only for admin command
+      # @param path      [String,NilClass]  local/remote path; when nil, read from CLI
+      # @param sync_info [Hash,NilClass]    extra sync info; when nil, read from CLI
+      # @param direction [Symbol,NilClass]  one of DIRECTIONS, or nil for admin commands
       # @return [Hash] sync info
-      def async_info_from_args(direction: nil)
-        path = options.get_next_argument('path')
-        sync_info = options.get_next_argument('sync info', mandatory: false, validation: Hash, default: {}, schema: Schema::Registry::SYNC_CONF)
+      def async_info_from_args(path: nil, sync_info: nil, direction: nil)
+        if path.nil?
+          path = options.get_next_argument('path')
+          sync_info = options.get_next_argument('sync info', mandatory: false, validation: Hash, default: {}, schema: Schema::Registry::SYNC_CONF)
+        end
+        sync_info ||= {}
         # is the positional path a remote path ?
         path_is_remote = direction.eql?(:pull)
         if sync_info.key?('sessions') || sync_info.key?('instance')
@@ -37,11 +61,11 @@ module Aspera
           Aspera.assert(sync_info['sessions'].length == 1, 'Only one session is supported')
           session = sync_info['sessions'].first
           dir_key = path_is_remote ? 'remote_dir' : 'local_dir'
-          raise "Parameter #{dir_key} shall not be in sync_info" if session.key?(dir_key)
+          Aspera.assert(!session.key?(dir_key)){"Parameter #{dir_key} shall not be in sync_info"}
           session[dir_key] = path
           if direction
             dir_key = path_is_remote ? 'local_dir' : 'remote_dir'
-            raise "Parameter #{dir_key} shall not be in sync_info" if session.key?(dir_key)
+            Aspera.assert(!session.key?(dir_key)){"Parameter #{dir_key} shall not be in sync_info"}
             session[dir_key] = transfer.destination_folder(path_is_remote ? Transfer::Spec::DIRECTION_RECEIVE : Transfer::Spec::DIRECTION_SEND)
             local_remote = %w[local remote].map{ |i| session["#{i}_dir"]}
           end
@@ -50,12 +74,12 @@ module Aspera
           session = sync_info
           dir_key = path_is_remote ? 'remote' : 'local'
           session[dir_key] ||= {}
-          raise "Parameter #{dir_key}.path shall not be in sync_info" if session[dir_key].key?('path')
+          Aspera.assert(!session[dir_key].key?('path')){"Parameter #{dir_key}.path shall not be in sync_info"}
           session[dir_key]['path'] = path
           if direction
             dir_key = path_is_remote ? 'local' : 'remote'
             session[dir_key] ||= {}
-            raise "Parameter #{dir_key}.path shall not be in sync_info" if session[dir_key].key?('path')
+            Aspera.assert(!session[dir_key].key?('path')){"Parameter #{dir_key}.path shall not be in sync_info"}
             session[dir_key]['path'] = transfer.destination_folder(path_is_remote ? Transfer::Spec::DIRECTION_RECEIVE : Transfer::Spec::DIRECTION_SEND)
             local_remote = %w[local remote].map{ |i| session[i]['path']}
           end
@@ -63,7 +87,7 @@ module Aspera
           session['quiet'] = false if !session.key?('quiet') && Environment.terminal?
         end
         if direction
-          raise BadArgument, 'direction shall not be in sync_info' if session.key?('direction')
+          Aspera.assert(!session.key?('direction'), type: BadArgument){'direction shall not be in sync_info'}
           session['direction'] = direction.to_s
           # generate name if not provided by user
           if !session.key?('name')
@@ -80,66 +104,66 @@ module Aspera
         sync_info
       end
 
-      # Provide database object from command line arguments for admin ops
-      def db_from_args
-        sync_info = async_info_from_args
+      # Provide database object from path + sync_info for admin ops
+      # @param path [String,NilClass] when nil, read from CLI
+      # @param sync_info [Hash,NilClass] when nil, read from CLI
+      def db_from_args(path: nil, sync_info: nil)
+        sync_info = async_info_from_args(path: path, sync_info: sync_info)
         session = sync_info.key?('sessions') ? sync_info['sessions'].first : sync_info
         # if name not provided, check in db folder if there is only one name
         if !session.key?('name')
           local_db_dir = Sync::Operations.local_db_folder(sync_info)
           dbs = Sync::Operations.list_db_files(local_db_dir)
-          raise "#{dbs.length} session found in #{local_db_dir}, please provide a name" unless dbs.length == 1
+          Aspera.assert(dbs.length == 1){"#{dbs.length} session found in #{local_db_dir}, please provide a name"}
           session['name'] = dbs.keys.first
         end
         Sync::Database.new(Sync::Operations.session_db_file(sync_info))
       end
 
-      def execute_sync_admin
-        command2 = options.get_next_command(%i[status find meta counters file_info overview query])
-        require 'aspera/sync/database' unless command2.eql?(:status)
-        sql_suffix = options.get_option(:sql)
-        case command2
-        when :status
-          return Result::SingleObject.new(Sync::Operations.admin_status(async_info_from_args))
-        when :find
-          folder = options.get_next_argument('path')
-          dbs = Sync::Operations.list_db_files(folder)
-          return Result::ObjectList.new(dbs.keys.map{ |n| {name: n, path: dbs[n]}})
-        when :meta, :counters
-          return Result::SingleObject.new(db_from_args.send(command2, sql_suffix))
-        when :file_info
-          result = db_from_args.file_info(sql_suffix)
-          result.each do |r|
-            r['sstate'] = SyncActions::STATE_STR[r['state']] if r['state']
-          end
-          return Result::ObjectList.new(
-            result,
-            fields: %w[sstate record_id f_meta_path message]
-          )
-        when :overview
-          return Result::ObjectList.new(
-            db_from_args.overview,
-            fields: %w[table name type]
-          )
-        when :query
-          return Result.auto(db_from_args.execute(options.get_option(:sql, mandatory: true)))
-        else Aspera.error_unexpected_value(command2)
-        end
+      def action_sync_admin_status(path:, sync_info: {}, **)
+        Result::SingleObject.new(Sync::Operations.admin_status(async_info_from_args(path: path, sync_info: sync_info)))
+      end
+
+      def action_sync_admin_find(path:, **)
+        dbs = Sync::Operations.list_db_files(path)
+        Result::ObjectList.new(dbs.keys.map{ |n| {name: n, path: dbs[n]}})
+      end
+
+      def action_sync_admin_meta(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).meta(options.get_option(:sql)))
+      end
+
+      def action_sync_admin_counters(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).counters(options.get_option(:sql)))
       end
 
-      # Execute sync action
-      # @param &block [nil, Proc] block to generate transfer spec, takes: `direction` (one of DIRECTIONS), `local_dir`, `remote_dir`
-      def execute_sync_action(&block)
-        command = options.get_next_command(%i[admin] + Sync::Operations::DIRECTIONS)
-        # try to get 3 arguments as simple arguments
-        case command
-        when *Sync::Operations::DIRECTIONS
-          Sync::Operations.start(async_info_from_args(direction: command), transfer.user_transfer_spec, &block)
-          return Result::Success.new
-        when :admin
-          return execute_sync_admin
-        else Aspera.error_unexpected_value(command)
+      def action_sync_admin_file_info(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        result = db_from_args(path: path, sync_info: sync_info).file_info(options.get_option(:sql))
+        result.each do |r|
+          r['sstate'] = SyncActions::STATE_STR[r['state']] if r['state']
         end
+        Result::ObjectList.new(result, fields: %w[sstate record_id f_meta_path message])
+      end
+
+      def action_sync_admin_overview(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result::ObjectList.new(db_from_args(path: path, sync_info: sync_info).overview, fields: %w[table name type])
+      end
+
+      def action_sync_admin_query(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result.auto(db_from_args(path: path, sync_info: sync_info).execute(options.get_option(:sql, mandatory: true)))
+      end
+
+      # Execute a sync transfer for a given direction.
+      # @param direction [Symbol] one of Sync::Operations::DIRECTIONS (:push, :pull, :bidi)
+      # @param block     [Proc, nil] block to generate transfer spec; receives (direction, local_dir, remote_dir)
+      def run_sync_transfer(direction, &block)
+        Sync::Operations.start(async_info_from_args(direction: direction), transfer.user_transfer_spec, &block)
+        Result::Success.new
       end
     end
   end

data/lib/aspera/cli/terminal_formatter.rb

@@ -14,7 +14,7 @@ module Aspera
       HINT = 'HINT:'.bg_green.gray.blink.freeze
       include FormatterInterface
 
-      # Format boolean with colored symbol (✓/✗ or Y/ )
+      # Format boolean with colored symbol (+/- or Y/ )
       def tick(yes)
         result =
           if Environment.terminal_supports_unicode?

data/lib/aspera/cli/transfer_actions.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/async_transfer_store'
+require 'aspera/agent/factory'
+require 'aspera/log'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Mixin for Config plugin: async transfer management actions.
+    # Exposes three sub-commands under `config transfer`:
+    #   status  --id=<job_id>   Re-query a running/completed transfer
+    #   list                    List all persisted async transfer entries
+    #   cleanup                 Remove completed/failed/cancelled entries
+    #
+    # Architecture:
+    #   - remote-daemon agents (desktop, node, connect, transferd): transfer_id + agent_params
+    #     are persisted in AsyncTransferStore; status is re-queried via Agent::Xxx.transfer_status
+    #   - direct agent: transfers live in Ruby threads - store is the agent's @sessions;
+    #     status is not persistable across process restarts (returns an informational message)
+    module TransferActions
+      # Re-query the status of a single async transfer job.
+      # @param job_id [String] UUID returned at submission time
+      def action_transfer_status(job_id:, **)
+        store = async_transfer_store
+        entry = store.read(job_id)
+        Aspera.assert(!entry.nil?, type: Cli::BadArgument){"Unknown job_id: #{job_id}"}
+        live = query_live_status(entry)
+        if live
+          entry.merge!(live)
+          store.write(job_id, entry)
+        end
+        Result::SingleObject.new(entry)
+      end
+
+      # List all persisted async transfer entries.
+      def action_transfer_list(**)
+        rows = async_transfer_store.list
+        Result::ObjectList.new(rows, fields: %w[job_id agent_type status started_at ended_at bytes_transferred transfer_id])
+      end
+
+      TERMINAL_STATUSES = %w[completed failed cancelled].freeze
+      private_constant :TERMINAL_STATUSES
+
+      # Delete completed, failed, and cancelled entries from the store.
+      def action_transfer_cleanup(**)
+        store = async_transfer_store
+        deleted = store.list
+          .select{ |e| TERMINAL_STATUSES.include?(e['status'])}
+          .map do |e|
+          store.delete(e['job_id'])
+          e['job_id']
+        end
+        Result::Status.new("Deleted #{deleted.size} completed transfer(s)#{": #{deleted.join(', ')}" unless deleted.empty?}")
+      end
+
+      private
+
+      # Lazy accessor - requires context.persistency (available in all Base sub-classes).
+      def async_transfer_store
+        @async_transfer_store ||= AsyncTransferStore.new(persistency)
+      end
+
+      # Delegate to the appropriate agent class method.
+      # Returns nil for direct transfers (in-process only, not re-queryable across processes).
+      def query_live_status(entry)
+        agent_type  = entry['agent_type']
+        transfer_id = entry['transfer_id']
+        agent_params = entry['agent_params'] || {}
+
+        # direct transfers live in Ruby threads - not persistable across process restarts
+        return if agent_type.eql?('direct')
+
+        require "aspera/agent/#{agent_type}"
+        agent_class = Aspera::Agent.const_get(agent_type.capitalize)
+        agent_class.transfer_status(transfer_id, agent_params)
+      rescue StandardError => e
+        Log.log.warn{"Could not re-query #{entry['agent_type']} agent for job #{entry['job_id']}: #{e}"}
+        nil
+      end
+    end
+  end
+end

data/lib/aspera/cli/transfer_agent.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require 'aspera/agent/factory'
+require 'aspera/schema/registry'
+require 'aspera/transfer/result'
 require 'aspera/transfer/spec'
 require 'aspera/cli/info'
+require 'aspera/cli/async_transfer_store'
 require 'aspera/log'
 require 'aspera/assert'
-require 'aspera/schema/registry'
+require 'securerandom'
 
 module Aspera
   module Cli
@@ -28,53 +31,50 @@ module Aspera
         <%=ts.to_yaml%>
       END_OF_TEMPLATE
       CP4I_REMOTE_HOST_LB = 'N/A'
-      private_constant :FILE_LIST_FROM_ARGS,
-        :FILE_LIST_FROM_TRANSFER_SPEC,
+      private_constant :FILE_LIST_FROM_TRANSFER_SPEC,
         :FILE_LIST_OPTIONS,
         :DEFAULT_TRANSFER_NOTIFY_TEMPLATE
 
       class << self
-        # Analyze transfer session statuses and return a global status
-        #
-        # @param statuses [Array] list of session status, each status is :success or an error message string
-        # @return [:success]  if all sessions statuses returned by "start" are success
-        # @return [Exception] if one sessions statuses returned by "start" is failed
-        def session_status(statuses)
-          error_statuses = statuses.reject{ |i| i.eql?(:success)}
-          return :success if error_statuses.empty?
-          return error_statuses.first
+        # Declare all transfer CLI options (metadata only - no handler binding yet).
+        # @param options [Aspera::Cli::Parser]
+        def declare_options(options)
+          options.declare(:ts,            description: 'Override transfer spec values', schema: Schema::Registry::TRANSFER_SPEC)
+          options.declare(:to_folder,     description: 'Destination folder for transferred files')
+          options.declare(:sources,       description: "How list of transferred files is provided (#{FILE_LIST_OPTIONS.join(',')})",               default: FILE_LIST_FROM_ARGS)
+          options.declare(:src_type,      description: 'Type of file list',                                                                        allowed: %i[list pair], default: :list)
+          options.declare(:transfer,      description: 'Transfer agent type, or agent parameters with optional agent key',                         allowed: [Hash, String], schema: Schema::Registry::TRANSFER_AGENT_OPTIONS)
+          options.declare(:transfer_info, description: 'Parameters for transfer agent',                                                            allowed: Hash, deprecation: 'use --transfer instead', schema: Schema::Registry::TRANSFER_AGENT_OPTIONS)
         end
       end
 
-      # @param opt_mgr       [Manager] Option manager
-      # @param config_plugin [Config]  Config plugin
-      def initialize(opt_mgr, config_plugin)
-        @opt_mgr = opt_mgr
-        @config = config_plugin
+      # @param context [Context] Application context
+      def initialize(context)
+        Aspera.assert_type(context, Context){'context'}
+        Aspera.assert_type(context.options, Parser){'context.options'}
+        @context = context
         # Command line can override transfer spec
         @user_transfer_spec = {
           'create_dir'    => true,
           'resume_policy' => 'sparse_csum'
         }
-        # options for transfer agent
-        @transfer_info = {}
+        # options for transfer agent (agent type + agent-specific parameters)
+        @transfer_options = {}
         # the currently selected transfer agent
         @agent = nil
         # source/destination pair, like "paths" of transfer spec
         @transfer_paths = nil
         # HTTPGW URL provided by webapp
         @httpgw_url_lambda = nil
-        @opt_mgr.declare(:ts, 'Override transfer spec values', allowed: Hash, handler: {o: self, m: :user_transfer_spec}, schema: Schema::Registry::TRANSFER_SPEC)
-        @opt_mgr.declare(:to_folder, 'Destination folder for transferred files')
-        @opt_mgr.declare(:sources, "How list of transferred files is provided (#{FILE_LIST_OPTIONS.join(',')})", default: FILE_LIST_FROM_ARGS)
-        @opt_mgr.declare(:src_type, 'Type of file list', allowed: %i[list pair], default: :list)
-        @opt_mgr.declare(:transfer, 'Type of transfer agent', allowed: Agent::Factory::ALL.keys, default: :direct)
-        @opt_mgr.declare(:transfer_info, 'Parameters for transfer agent', allowed: Hash, handler: {o: self, m: :transfer_info}, schema: Schema::Registry::TRANSFER_INFO)
-        @opt_mgr.parse_options!
+        self.class.declare_options(@context.options)
+        @context.options.set_handler(:ts,            object: self, method: :user_transfer_spec)
+        @context.options.set_handler(:transfer,      object: self, method: :option_transfer)
+        @context.options.set_handler(:transfer_info, object: self, method: :transfer_options)
+        @context.options.parse_options!
         @notification_cb = nil
-        if !@opt_mgr.get_option(:notify_to).nil?
+        if !@context.options.get_option(:notify_to).nil?
           @notification_cb = ->(transfer_spec, global_status) do
-            @config.send_email_template(email_template_default: DEFAULT_TRANSFER_NOTIFY_TEMPLATE, values: {
+            @context.mailer.send_email_template(email_template_default: DEFAULT_TRANSFER_NOTIFY_TEMPLATE, values: {
               subject: "#{Info::CMD_NAME} transfer: #{global_status}",
               status:  global_status,
               ts:      transfer_spec
@@ -83,7 +83,23 @@ module Aspera
         end
       end
 
-      attr_accessor :user_transfer_spec, :transfer_info
+      attr_accessor :user_transfer_spec, :transfer_options
+
+      # Composite option handler for :transfer
+      # String value: shorthand for agent type, stored as {'agent' => value}
+      # Hash value:   merged into @transfer_options (may include 'agent' key)
+      def option_transfer(_option_sym, operation, value = nil)
+        Aspera.assert_values(operation, %i[set get])
+        case operation
+        when :set
+          value = {'agent' => value} if value.is_a?(String)
+          Aspera.assert_type(value, Hash)
+          @transfer_options = @transfer_options.deep_merge(value)
+        when :get
+          return @transfer_options
+        end
+        nil
+      end
 
       def agent_instance=(instance)
         @agent = instance
@@ -92,25 +108,27 @@ module Aspera
       # analyze options and create new agent if not already created or set
       def agent_instance
         return @agent unless @agent.nil?
-        agent_type = @opt_mgr.get_option(:transfer, mandatory: true)
-        # set keys as symbols
-        agent_options = @opt_mgr.get_option(:transfer_info).symbolize_keys
-        agent_options[:progress] = @config.progress_bar
-        agent_options[:config_dir] = @config.main_folder
+        # agent type: from composite option 'agent' key, default :direct
+        raw_type = @transfer_options['agent'] || :direct
+        agent_type = Parser.get_from_list(raw_type.to_s, 'transfer agent', Agent::Factory::ALL.keys)
+        # set keys as symbols, strip internal keys not forwarded to the agent constructor
+        agent_options = @transfer_options.except('agent', 'asynchronous').symbolize_keys
+        agent_options[:progress] = @context.progress_bar
+        agent_options[:config_dir] = @context.main_folder
         # special cases
         case agent_type
         when :node
           if !agent_options.key?(:url)
-            param_set_name = @config.get_plugin_default_config_name(:node)
-            raise Cli::BadArgument, "No default node configured. Please specify #{Manager.option_name_to_line(:transfer_info)}" if param_set_name.nil?
-            agent_options.merge!(@config.preset_by_name(param_set_name).symbolize_keys)
+            param_set_name = @context.presets.plugin_default_name(:node)
+            Aspera.assert(!param_set_name.nil?, type: Cli::BadArgument){"No default node configured. Please specify #{Options.option_name_to_line(:transfer)}.url or #{Options.option_name_to_line(:transfer)}"}
+            agent_options.merge!(@context.presets.by_name(param_set_name).symbolize_keys)
           end
         when :direct
           # by default do not display ascp native progress bar
           agent_options[:quiet] = true unless agent_options.key?(:quiet)
-          agent_options[:check_ignore_cb] = ->(host, port){@config.ignore_cert?(host, port)}
+          agent_options[:check_ignore_cb] = ->(host, port){@context.http_config.ignore_cert?(host, port)}
           # JRuby
-          agent_options[:trusted_certs] = @config.trusted_cert_locations unless agent_options.key?(:trusted_certs)
+          agent_options[:trusted_certs] = @context.http_config.trusted_cert_locations unless agent_options.key?(:trusted_certs)
         when :httpgw
           unless agent_options.key?(:url) || @httpgw_url_lambda.nil?
             Log.log.debug('retrieving HTTPGW URL from webapp')
@@ -127,7 +145,7 @@ module Aspera
       # @param direction [String] `send`` or `receive``
       # @return [String] Destination folder for transfers (with default based on direction)
       def destination_folder(direction)
-        dest_folder = @opt_mgr.get_option(:to_folder)
+        dest_folder = @context.options.get_option(:to_folder)
         # do not expand path, if user wants to expand path: user @path:
         return dest_folder unless dest_folder.nil?
         dest_folder = @user_transfer_spec['destination_root']
@@ -157,7 +175,7 @@ module Aspera
       # Transform the list of paths to a list of hash with source/dest
       # @param file_list [Array<Hash>]
       def list_to_paths(file_list)
-        source_type = @opt_mgr.get_option(:src_type, mandatory: true)
+        source_type = @context.options.get_option(:src_type, mandatory: true)
         @transfer_paths =
           case source_type
           when :list
@@ -181,23 +199,23 @@ module Aspera
         # start with lower priority : get paths from transfer spec on command line
         @transfer_paths = @user_transfer_spec['paths'] if @user_transfer_spec.key?('paths')
         # is there a source list option ?
-        sources = @opt_mgr.get_option(:sources)
+        sources = @context.options.get_option(:sources)
         @transfer_paths =
           case sources
           when FILE_LIST_FROM_ARGS
             Log.log.debug('getting file list as parameters')
             Aspera.assert_type(default, Array, NilClass)
             # get remaining arguments
-            list = @opt_mgr.get_next_argument('source file list', multiple: true, default: default)
+            list = @context.options.get_next_argument('source file list', multiple: true, default: default)
             raise Cli::BadArgument, 'specify at least one file on command line or use ' \
               "--sources=#{FILE_LIST_FROM_TRANSFER_SPEC} to use transfer spec" if !list.is_a?(Array) || list.empty?
             list_to_paths(list)
           when FILE_LIST_FROM_TRANSFER_SPEC
             Log.log.debug('assume list provided in transfer spec')
             special_case_direct_with_list =
-              @opt_mgr.get_option(:transfer, mandatory: true).eql?(:direct) &&
-              Transfer::Parameters.ascp_args_file_list?(@opt_mgr.get_option(:transfer_info)['ascp_args'])
-            raise Cli::BadArgument, 'transfer spec on command line must have sources' if @transfer_paths.nil? && !special_case_direct_with_list
+              (@transfer_options['agent'] || :direct).to_sym.eql?(:direct) &&
+              Transfer::Parameters.ascp_args_file_list?(@transfer_options['ascp_args'])
+            Aspera.assert(!@transfer_paths.nil? || special_case_direct_with_list, type: Cli::BadArgument){'transfer spec on command line must have sources'}
             # can be nil
             @transfer_paths
           when Array
@@ -211,8 +229,8 @@ module Aspera
       end
 
       # Start a transfer and wait for completion, plugins shall use this method
-      # @param transfer_spec [Hash]
-      # @param rest_token    [Rest] if oauth token regeneration supported
+      # @param transfer_spec [Hash] transfer specification
+      # @param rest_token    [Rest, nil] if oauth token regeneration supported
       def start(transfer_spec, rest_token: nil)
         # check parameters
         Aspera.assert_type(transfer_spec, Hash){'transfer_spec'}
@@ -240,15 +258,55 @@ module Aspera
         @user_transfer_spec['paths'] = transfer_spec['paths'] || ts_source_paths
         # updated transfer spec with command line
         transfer_spec.deep_merge!(@user_transfer_spec)
+        # resolve pseudo-parameter: target_rate -> target_rate_kbps (overrides target_rate_kbps if both are present)
+        transfer_spec['target_rate_kbps'] = Transfer::Spec.rate_string_to_kbps(transfer_spec.delete('target_rate')) if transfer_spec.key?('target_rate')
         # recursively remove values that are nil (user wants to delete)
         transfer_spec.deep_do{ |hash, key, value, _unused| hash.delete(key) if value.nil?}
         # if TS from app has content_protection (e.g. F5), that means content is protected: ask password if not provided
-        transfer_spec['content_protection_password'] = @opt_mgr.prompt_user_input('content protection password', sensitive: true) if transfer_spec['content_protection'].eql?('decrypt') && !transfer_spec.key?('content_protection_password')
+        transfer_spec['content_protection_password'] = @context.options.prompt_user_input('content protection password', sensitive: true) if transfer_spec['content_protection'].eql?('decrypt') && !transfer_spec.key?('content_protection_password')
         # create transfer agent
         agent_instance.start_transfer(transfer_spec, token_regenerator: rest_token)
-        # list of: :success or "error message string"
+        # --- async mode ---
+        if @transfer_options['asynchronous']
+          agent_type = (@transfer_options['agent'] || 'direct').to_s
+          raise Cli::BadArgument, 'asynchronous mode is not supported for agent httpgw' if agent_type.eql?('httpgw')
+          # For direct agent: the transfer lives in this Ruby process (threads).
+          # We return the job_id from the agent itself; no persistent store needed.
+          if agent_type.eql?('direct')
+            job_id = agent_instance.instance_variable_get(:@sessions).last[:job_id]
+            Log.log.info{"Async direct transfer started: job_id=#{job_id}"}
+            return Transfer::Result.async(job_id: job_id)
+          end
+          # For remote-daemon agents (desktop, node, connect, transferd): persist transfer_id
+          # so the status can be re-queried in a later process invocation.
+          agent_params = @transfer_options.except('agent', 'asynchronous')
+          case agent_type
+          when 'desktop'
+            agent_params['application_id'] = agent_instance.application_id
+          when 'connect'
+            agent_params['app_id'] = agent_instance.app_id
+          when 'transferd'
+            # store the resolved daemon endpoint (auto-port may have been assigned)
+            agent_params['url'] = agent_instance.daemon_endpoint
+          end
+          job_id = SecureRandom.uuid
+          async_store.write(job_id, {
+            'job_id'            => job_id,
+            'agent_type'        => agent_type,
+            'transfer_id'       => agent_instance.instance_variable_get(:@transfer_id).to_s,
+            'agent_params'      => agent_params,
+            'status'            => 'running',
+            'bytes_transferred' => 0,
+            'started_at'        => Time.now.utc.iso8601,
+            'ended_at'          => nil,
+            'error'             => nil
+          })
+          Log.log.info{"Async transfer started: job_id=#{job_id}"}
+          return Transfer::Result.async(job_id: job_id)
+        end
+        # --- synchronous mode (default) ---
         result = agent_instance.wait_for_completion
-        @notification_cb&.call(transfer_spec, self.class.session_status(result))
+        @notification_cb&.call(transfer_spec, result)
         return result
       end
 
@@ -256,6 +314,13 @@ module Aspera
       def shutdown
         @agent.shutdown if @agent.respond_to?(:shutdown)
       end
+
+      private
+
+      # Lazy accessor for the async transfer store (only created when needed)
+      def async_store
+        @async_store ||= AsyncTransferStore.new(@context.persistency)
+      end
     end
   end
 end

data/lib/aspera/cli/transfer_progress.rb

@@ -25,9 +25,9 @@ module Aspera
       end
 
       # Called by user of progress bar with a status on a transfer session
-      # @param session_id the unique identifier of a transfer session
+      # @param session_id [String] the unique identifier of a transfer session
       # @param type [Symbol] one of: sessions_init, session_start, session_size, transfer, session_end and end
-      # @param info optional specific additional info for the given event type
+      # @param info [Object, nil] optional specific additional info for the given event type
       def event(type, session_id: nil, info: nil)
         Log.log.trace1{"progress: #{type} #{session_id} #{info}"}
         return if @completed
@@ -50,7 +50,7 @@ module Aspera
         when :session_start
           Aspera.assert_type(session_id, String)
           Aspera.assert(info.nil?, 'info must be nil for :session_start event')
-          raise "Session #{session_id} already started" if @sessions[session_id]
+          Aspera.assert(!@sessions[session_id]){"Session #{session_id} already started"}
           @sessions[session_id] = {
             job_size: 0, # Total size of transfer (pre-calc)
             current:  0,