aspera-cli 4.27.0 → 4.27.1

data/lib/aspera/cli/sync_actions.rb

@@ -7,13 +7,18 @@ require 'pathname'
 
 module Aspera
   module Cli
-    # Manage command line arguments to provide to Sync::Operations and Sync::Database
+    # Helpers shared by plugins that expose Aspera Sync (async) operations.
+    # Provides DSL registration, argument-to-sync-info conversion, and action methods.
     module SyncActions
       # Translate state id (int) to string
       STATE_STR = (['Nil'] +
-        (1..18).map{ |i| "P(#{i})"} +
+        (1..18).map { |i| "P(#{i})" } +
         %w[Syncd Error Confl Pconf] +
-        (23..24).map{ |i| "P(#{i})"}).freeze
+        (23..24).map { |i| "P(#{i})" }).freeze
+      # Positional arguments shared by sync transfer commands (push/pull/bidi) and sync admin commands.
+      PATH_AND_INFO_ARGS = [{name: :path, type: String}, {name: :sync_info, type: Hash, mandatory: false, default: {}}].freeze
+      # Names of the leaf commands registered under any `sync admin` node.
+      ADMIN_COMMANDS = %i[find status meta counters file_info overview query].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
@@ -24,17 +29,16 @@ module Aspera
         # 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]
+        # @param admin_path  [Symbol, Array<Symbol>]  path relative to current scope, e.g. :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)
+            base.command(:status,    description: 'Show sync session status',     arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_status)
+            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
@@ -43,16 +47,11 @@ module Aspera
       # 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 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
+      # @param path      [String]          local/remote path
+      # @param sync_info [Hash]            extra sync info (may be empty)
+      # @param direction [Symbol,NilClass] one of DIRECTIONS, or nil for admin commands
       # @return [Hash] sync info
-      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 ||= {}
+      def async_info_from_args(path:, sync_info: {}, direction: nil)
         # is the positional path a remote path ?
         path_is_remote = direction.eql?(:pull)
         if sync_info.key?('sessions') || sync_info.key?('instance')
@@ -61,33 +60,33 @@ 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'
-          Aspera.assert(!session.key?(dir_key)){"Parameter #{dir_key} shall not be in sync_info"}
+          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'
-            Aspera.assert(!session.key?(dir_key)){"Parameter #{dir_key} shall not be in sync_info"}
+            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"]}
+            local_remote = %w[local remote].map { |i| session["#{i}_dir"] }
           end
         else
           # `conf`
           session = sync_info
           dir_key = path_is_remote ? 'remote' : 'local'
           session[dir_key] ||= {}
-          Aspera.assert(!session[dir_key].key?('path')){"Parameter #{dir_key}.path shall not be in sync_info"}
+          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] ||= {}
-            Aspera.assert(!session[dir_key].key?('path')){"Parameter #{dir_key}.path shall not be in sync_info"}
+            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']}
+            local_remote = %w[local remote].map { |i| session[i]['path'] }
           end
           # `conf` is quiet by default
           session['quiet'] = false if !session.key?('quiet') && Environment.terminal?
         end
         if direction
-          Aspera.assert(!session.key?('direction'), type: BadArgument){'direction shall not be in sync_info'}
+          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')
@@ -105,16 +104,16 @@ module Aspera
       end
 
       # 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)
+      # @param path      [String] local path
+      # @param sync_info [Hash]   extra sync info (may be empty)
+      def db_from_args(path:, sync_info: {})
         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)
-          Aspera.assert(dbs.length == 1){"#{dbs.length} session found in #{local_db_dir}, please provide a name"}
+          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))
@@ -126,7 +125,7 @@ module Aspera
 
       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]}})
+        Result::ObjectList.new(dbs.keys.map { |n| {name: n, path: dbs[n]} })
       end
 
       def action_sync_admin_meta(path:, sync_info: {}, **)
@@ -159,10 +158,12 @@ module Aspera
       end
 
       # Execute a sync transfer for a given direction.
-      # @param direction [Symbol] one of Sync::Operations::DIRECTIONS (:push, :pull, :bidi)
+      # @param direction [Symbol]    one of Sync::Operations::DIRECTIONS (:push, :pull, :bidi)
+      # @param path      [String]    local or remote path (depends on direction)
+      # @param sync_info [Hash]      extra sync configuration (may be empty)
       # @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)
+      def run_sync_transfer(direction, path:, sync_info: {}, &block)
+        Sync::Operations.start(async_info_from_args(path: path, sync_info: sync_info, direction: direction), transfer.user_transfer_spec, &block)
         Result::Success.new
       end
     end

data/lib/aspera/cli/terminal_formatter.rb

@@ -29,13 +29,13 @@ module Aspera
       # Format special values with colors (dim for empty, reverse for others)
       def special_format(what)
         result = "<#{what}>"
-        return %w[null empty].any?{ |s| what.include?(s)} ? result.dim : result.reverse_color
+        return %w[null empty].any? { |s| what.include?(s) } ? result.dim : result.reverse_color
       end
 
       # Prepare table row for terminal display (word wrap arrays)
       def check_row(row)
         row.each_key do |k|
-          row[k] = row[k].map{ |i| WordWrap.ww(i.to_s, 120).chomp}.join("\n") if row[k].is_a?(Array)
+          row[k] = row[k].map { |i| WordWrap.ww(i.to_s, 120).chomp }.join("\n") if row[k].is_a?(Array)
         end
       end
 

data/lib/aspera/cli/transfer_actions.rb

@@ -24,7 +24,10 @@ module Aspera
       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}"}
+        Aspera.assert(!entry.nil?, type: Cli::BadArgument) { "Unknown job_id: #{job_id}" }
+        # Inject the in-process agent reference (direct/httpgw) if still alive in this process.
+        ref = store.agent_ref(job_id)
+        entry['agent_params']['_agent_ref'] = ref if ref
         live = query_live_status(entry)
         if live
           entry.merge!(live)
@@ -46,7 +49,7 @@ module Aspera
       def action_transfer_cleanup(**)
         store = async_transfer_store
         deleted = store.list
-          .select{ |e| TERMINAL_STATUSES.include?(e['status'])}
+          .select { |e| TERMINAL_STATUSES.include?(e['status']) }
           .map do |e|
           store.delete(e['job_id'])
           e['job_id']
@@ -57,25 +60,29 @@ module Aspera
       private
 
       # Lazy accessor - requires context.persistency (available in all Base sub-classes).
+      # Delegate to the TransferAgent's store so that the in-memory agent-ref
+      # registry is shared between the two components in the same process.
       def async_transfer_store
-        @async_transfer_store ||= AsyncTransferStore.new(persistency)
+        context.transfer.async_store
       end
 
       # Delegate to the appropriate agent class method.
-      # Returns nil for direct transfers (in-process only, not re-queryable across processes).
+      # All agent types are supported:
+      # - in-process agents (direct, httpgw): re-queryable while the same process lives
+      #   (e.g. MCP mode); '_agent_ref' in agent_params points to the live instance.
+      #   When the process has restarted, '_agent_ref' is nil and transfer_status returns
+      #   {'status' => 'unknown'} — which is the correct and safe answer.
+      # - daemon agents (node, desktop, connect, transferd): re-query via their REST/IPC API.
       def query_live_status(entry)
-        agent_type  = entry['agent_type']
-        transfer_id = entry['transfer_id']
+        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}"}
+        Log.log.warn { "Could not re-query #{entry['agent_type']} agent for job #{entry['job_id']}: #{e}" }
         nil
       end
     end

data/lib/aspera/cli/transfer_agent.rb

@@ -2,6 +2,7 @@
 
 require 'aspera/agent/factory'
 require 'aspera/schema/registry'
+require 'aspera/cli/option_declarator'
 require 'aspera/transfer/result'
 require 'aspera/transfer/spec'
 require 'aspera/cli/info'
@@ -35,23 +36,19 @@ module Aspera
         :FILE_LIST_OPTIONS,
         :DEFAULT_TRANSFER_NOTIFY_TEMPLATE
 
-      class << self
-        # 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
+      extend OptionDeclarator
+
+      option :ts,            description: 'Override transfer spec values', schema: Schema::Registry::TRANSFER_SPEC
+      option :to_folder,     description: 'Destination folder for transferred files'
+      option :sources,       description: "How list of transferred files is provided (#{FILE_LIST_OPTIONS.join(',')})",               default: FILE_LIST_FROM_ARGS
+      option :src_type,      description: 'Type of file list',                                                                        allowed: %i[list pair], default: :list
+      option :transfer,      description: 'Transfer agent type, or agent parameters with optional agent key',                         allowed: [Hash, String], schema: Schema::Registry::TRANSFER_AGENT_OPTIONS
+      option :transfer_info, description: 'Parameters for transfer agent',                                                            deprecation: 'use --transfer instead', schema: Schema::Registry::TRANSFER_AGENT_OPTIONS
 
       # @param context [Context] Application context
       def initialize(context)
-        Aspera.assert_type(context, Context){'context'}
-        Aspera.assert_type(context.options, Parser){'context.options'}
+        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 = {
@@ -120,13 +117,13 @@ module Aspera
         when :node
           if !agent_options.key?(:url)
             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)}"}
+            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){@context.http_config.ignore_cert?(host, port)}
+          agent_options[:check_ignore_cb] = ->(host, port) { @context.http_config.ignore_cert?(host, port) }
           # JRuby
           agent_options[:trusted_certs] = @context.http_config.trusted_cert_locations unless agent_options.key?(:trusted_certs)
         when :httpgw
@@ -137,7 +134,7 @@ module Aspera
         end
         # get agent instance
         self.agent_instance = Agent::Factory.instance.create(agent_type, agent_options)
-        Log.log.debug{"transfer agent is a #{@agent.class}"}
+        Log.log.debug { "transfer agent is a #{@agent.class}" }
         return @agent
       end
 
@@ -168,7 +165,7 @@ module Aspera
 
       # @param httpgw_url_proc [Proc]
       def httpgw_url_cb=(httpgw_url_proc)
-        Aspera.assert_type(httpgw_url_proc, Proc){'httpgw_url_cb'}
+        Aspera.assert_type(httpgw_url_proc, Proc) { 'httpgw_url_cb' }
         @httpgw_url_lambda = httpgw_url_proc
       end
 
@@ -180,10 +177,10 @@ module Aspera
           case source_type
           when :list
             # when providing a list, just specify source
-            file_list.map{ |i| {'source' => i}}
+            file_list.map { |i| {'source' => i} }
           when :pair
-            Aspera.assert(file_list.length.even?, type: Cli::BadArgument){"When using pair, provide an even number of paths: #{file_list.length}"}
-            file_list.each_slice(2).map{ |s, d| {'source' => s, 'destination' => d}}
+            Aspera.assert(file_list.length.even?, type: Cli::BadArgument) { "When using pair, provide an even number of paths: #{file_list.length}" }
+            file_list.each_slice(2).map { |s, d| {'source' => s, 'destination' => d} }
           else Aspera.error_unexpected_value(source_type)
           end
       end
@@ -215,16 +212,16 @@ module Aspera
             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'}
+            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
             Log.log.debug('getting file list as extended value')
-            Aspera.assert_array_all(sources, String, type: Cli::BadArgument){'sources must be a Array of String'}
+            Aspera.assert_array_all(sources, String, type: Cli::BadArgument) { 'sources must be a Array of String' }
             list_to_paths(sources)
-          else Aspera.error_unexpected_value(sources){'sources'}
+          else Aspera.error_unexpected_value(sources) { 'sources' }
           end
-        Log.log.debug{"paths=#{@transfer_paths}"}
+        Log.dump(:paths, @transfer_paths)
         return @transfer_paths
       end
 
@@ -233,7 +230,7 @@ module Aspera
       # @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'}
+        Aspera.assert_type(transfer_spec, Hash) { 'transfer_spec' }
         raise "Wrong remote host: #{CP4I_REMOTE_HOST_LB}" if transfer_spec['remote_host'].eql?(CP4I_REMOTE_HOST_LB)
         # process :src option
         case transfer_spec['direction']
@@ -261,7 +258,7 @@ module Aspera
         # 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?}
+        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'] = @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
@@ -269,31 +266,36 @@ module Aspera
         # --- 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.
+          # In-process agents (direct, httpgw) expose last_job_id directly.
+          # Remote-daemon agents do not override last_job_id (returns nil): generate a UUID.
+          job_id = agent_instance.last_job_id || SecureRandom.uuid
+          # Base agent_params from transfer options (strip internal keys)
           agent_params = @transfer_options.except('agent', 'asynchronous')
+          # For daemon agents: capture any runtime-resolved connection detail
           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
+          # Register an in-process agent reference for direct/httpgw agents so that
+          # config transfer status can re-query them while the same process is alive
+          # (e.g. MCP server mode). The ref is stored in AsyncTransferStore's memory map,
+          # never on disk.
+          async_store.register_agent_ref(job_id, agent_instance) if %w[direct httpgw].include?(agent_type)
+          # transfer_id: in-process agents use job_id; daemon agents expose @transfer_id
+          transfer_id =
+            if %w[direct httpgw].include?(agent_type)
+              job_id
+            else
+              agent_instance.instance_variable_get(:@transfer_id).to_s
+            end
           async_store.write(job_id, {
             'job_id'            => job_id,
             'agent_type'        => agent_type,
-            'transfer_id'       => agent_instance.instance_variable_get(:@transfer_id).to_s,
+            'transfer_id'       => transfer_id,
             'agent_params'      => agent_params,
             'status'            => 'running',
             'bytes_transferred' => 0,
@@ -301,7 +303,7 @@ module Aspera
             'ended_at'          => nil,
             'error'             => nil
           })
-          Log.log.info{"Async transfer started: job_id=#{job_id}"}
+          Log.log.info { "Async transfer started: job_id=#{job_id}, agent=#{agent_type}" }
           return Transfer::Result.async(job_id: job_id)
         end
         # --- synchronous mode (default) ---
@@ -315,9 +317,7 @@ module Aspera
         @agent.shutdown if @agent.respond_to?(:shutdown)
       end
 
-      private
-
-      # Lazy accessor for the async transfer store (only created when needed)
+      # Lazy accessor for the async transfer store (shared with TransferActions via context.transfer).
       def async_store
         @async_store ||= AsyncTransferStore.new(@context.persistency)
       end

data/lib/aspera/cli/transfer_progress.rb

@@ -29,12 +29,12 @@ module Aspera
       # @param type [Symbol] one of: sessions_init, session_start, session_size, transfer, session_end and end
       # @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}"}
+        Log.log.trace1 { "progress: #{type} #{session_id} #{info}" }
         return if @completed
         if @progress_bar.nil?
           @progress_bar = ProgressBar.create(
             format:      '%t %a %B %p%% %r Mbps %E',
-            rate_scale:  lambda{ |rate| rate / Environment::BYTES_PER_MEBIBIT},
+            rate_scale:  lambda { |rate| rate / Environment::BYTES_PER_MEBIBIT },
             title:       '',
             total:       nil
           )
@@ -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')
-          Aspera.assert(!@sessions[session_id]){"Session #{session_id} already started"}
+          Aspera.assert(!@sessions[session_id]) { "Session #{session_id} already started" }
           @sessions[session_id] = {
             job_size: 0, # Total size of transfer (pre-calc)
             current:  0,
@@ -83,19 +83,19 @@ module Aspera
           Aspera.assert(session_id.nil?, 'session_id must be nil for :end event')
           Aspera.assert(info.nil?, 'info must be nil for :end event')
           @progress_bar.finish
-        else Aspera.error_unexpected_value(type){'event type'}
+        else Aspera.error_unexpected_value(type) { 'event type' }
         end
-        new_title = @sessions.length < 2 ? @title.to_s : "[#{@sessions.count{ |_i, d| d[:running]}}] #{@title}"
+        new_title = @sessions.length < 2 ? @title.to_s : "[#{@sessions.count { |_i, d| d[:running] }}] #{@title}"
         @progress_bar&.title = new_title unless @progress_bar&.title.eql?(new_title)
         @progress_bar&.increment if !progress_provided && @progress_bar.progress.nil?
       rescue ProgressBar::InvalidProgressError => e
-        Log.log.error{"Progress error: #{e}"}
+        Log.log.error { "Progress error: #{e}" }
       end
 
       private
 
       def total(key)
-        @sessions.values.inject(0){ |m, s| m + s[key]}
+        @sessions.values.inject(0) { |m, s| m + s[key] }
       end
     end
   end

data/lib/aspera/cli/vault_manager.rb

@@ -3,46 +3,68 @@
 require 'aspera/cli/error'
 require 'aspera/log'
 require 'aspera/assert'
+require 'json'
 
 module Aspera
   module Cli
     # Mixin providing vault/keychain functionality to Plugin::Config.
     # Depends on `options` and `context.main_folder` being available in the including class.
     module VaultManager
-      def action_vault_show(label:, **)
-        Result::SingleObject.new(vault.get(label: label))
+      def action_vault_show(label:, id: nil, **)
+        v = vault_required
+        kwargs = id && v.method(:get).parameters.any? { |_t, n| n == :id } ? {id: id} : {}
+        Result::SingleObject.new(v.get(label: label, **kwargs))
       end
 
       def action_vault_create(info:, **)
-        vault.set(info.symbolize_keys)
+        vault_required.set(info.symbolize_keys)
         Result::Status.new('Secret added')
       end
 
-      def action_vault_delete(label:, **)
-        vault.delete(label: label)
+      # Import secrets from a JSON array; skips entries missing :label
+      def action_vault_import(secrets:, **)
+        bulk_result(secrets, command: :import, id_result: 'label') do |entry|
+          vault_required.set(entry.symbolize_keys)
+          {'label' => entry['label'] || entry[:label]}
+        end
+      end
+
+      def action_vault_delete(label:, id: nil, **)
+        v = vault_required
+        kwargs = id && v.method(:delete).parameters.any? { |_t, n| n == :id } ? {id: id} : {}
+        v.delete(label: label, **kwargs)
         Result::Status.new("Secret deleted: #{label}")
       end
 
       def action_vault_password(new_password:, **)
-        Aspera.assert(vault.respond_to?(:change_password), 'Vault does not support password change')
-        vault.change_password(new_password)
+        Aspera.assert(vault_required.respond_to?(:change_password), 'Vault does not support password change')
+        vault_required.change_password(new_password)
         Result::Status.new('Vault password updated')
       end
 
+      # @return [Keychain::Base] vault instance, raises if not configured
+      def vault_required
+        Aspera.assert(!vault.nil?, type: Cli::BadArgument) { 'Missing mandatory option: vault' }
+        vault
+      end
+
       # @return [String] value from vault matching <name>.<param>
       def vault_value(name)
         m = name.split('.')
-        Aspera.assert(m.length.eql?(2), type: BadArgument){'vault name shall match <name>.<param>'}
-        info = vault.get(label: m[0])
+        Aspera.assert(m.length.eql?(2), type: BadArgument) { 'vault name shall match <name>.<param>' }
+        info = vault_required.get(label: m[0])
         value = info[m[1].to_sym]
         raise "no such entry value: #{m[1]}" if value.nil?
         return value
       end
 
-      # @return [Keychain::Base] vault instance, lazily created from options
+      # @return [Keychain::Base, nil] vault instance, lazily created from options, or nil if not configured
       def vault
-        return @vault_instance unless @vault_instance.nil?
-        info = options.get_option(:vault, mandatory: true).symbolize_keys
+        return @vault_instance if @vault_instance_initialized
+        @vault_instance_initialized = true
+        info = options.get_option(:vault, mandatory: false)
+        return @vault_instance = nil if info.nil? || (info.is_a?(Hash) && info.empty?)
+        info = info.symbolize_keys
         info[:type] ||= 'file'
         require 'aspera/keychain/factory'
         @vault_instance = Keychain::Factory.create(

data/lib/aspera/cli/version.rb

@@ -4,6 +4,6 @@ module Aspera
   module Cli
     # For beta add extension : .beta1
     # For dev version add extension : .pre
-    VERSION = '4.27.0'
+    VERSION = '4.27.1'
   end
 end