aspera-cli 4.26.2 → 4.27.1

data/lib/aspera/cli/runner.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
+require 'aspera/cli/command_spec'
 require 'aspera/cli/context'
-require 'aspera/cli/manager'
+require 'aspera/cli/parser'
 require 'aspera/cli/formatter'
 require 'aspera/cli/plugins/factory'
+require 'aspera/cli/bootstrapper'
 require 'aspera/cli/plugins/config'
+require 'aspera/cli/mailer'
+require 'aspera/cli/secret_finder'
 require 'aspera/cli/extended_value'
 require 'aspera/cli/transfer_agent'
 require 'aspera/cli/version'
 require 'aspera/cli/info'
 require 'aspera/cli/hints'
 require 'aspera/cli/result'
+require 'aspera/transfer/result'
 require 'aspera/secret_hider'
 require 'aspera/log'
 require 'aspera/assert'
@@ -25,38 +30,45 @@ module Aspera
     class Runner
       # Plugins store transfer result using this key and use result_transfer_multiple()
       STATUS_FIELD = 'status'
-      COMMAND_CONFIG = :config
-      COMMAND_HELP = :help
-      # Types that go to result of type = text
-      SCALAR_TYPES = [String, Integer, Symbol].freeze
-      USER_INTERFACES = %i[text graphical].freeze
-
-      private_constant :COMMAND_CONFIG, :COMMAND_HELP, :SCALAR_TYPES, :USER_INTERFACES
 
       class << self
-        # Process statuses of finished transfer sessions
-        # @param statuses [Array] array of transfer session statuses
-        # @raise [Symbol] exception if there is one error
-        # @return [Result] empty status result if all transfers succeeded
-        def result_transfer(statuses)
-          worst = TransferAgent.session_status(statuses)
-          raise worst unless worst.eql?(:success)
-          return Result::Nothing.new
+        # Process the typed result of a finished (or submitted) transfer.
+        # @param transfer_result [Transfer::Result] typed result from TransferAgent#start
+        # @raise [StandardError] if the transfer failed
+        # @return [Result] CLI result object
+        def result_transfer(transfer_result)
+          case transfer_result
+          when Transfer::Result::Async
+            return Result::SingleObject.new(transfer_result.to_h)
+          when Transfer::Result::Error
+            raise transfer_result.exception
+          when Transfer::Result::Success
+            return Result::Nothing.new
+          else
+            raise "Unexpected transfer result type: #{transfer_result.class}"
+          end
         end
 
         # Used when one command executes several transfer jobs (each job being possibly multi session)
-        # @param status_table [Array] [{STATUS_FIELD=>[status array],...},...]
+        # @param status_table [Array] [{STATUS_FIELD=>Transfer::Result,...},...]
         # @return [Result] a status object suitable as command result
-        # Each element has a key STATUS_FIELD which contains the result of possibly multiple sessions
         def result_transfer_multiple(status_table)
-          global_status = :success
-          # Transform status array into string and find if there was problem
+          failed_result = nil
           status_table.each do |item|
-            worst = TransferAgent.session_status(item[STATUS_FIELD])
-            global_status = worst unless worst.eql?(:success)
-            item[STATUS_FIELD] = item[STATUS_FIELD].join(',')
+            tr = item[STATUS_FIELD]
+            case tr
+            when Transfer::Result::Error
+              failed_result ||= tr
+              item[STATUS_FIELD] = tr.exception.message
+            when Transfer::Result::Success
+              item[STATUS_FIELD] = 'success'
+            when Transfer::Result::Async
+              item[STATUS_FIELD] = "async:#{tr.job_id}"
+            else
+              item[STATUS_FIELD] = tr.to_s
+            end
           end
-          raise global_status unless global_status.eql?(:success)
+          raise failed_result.exception unless failed_result.nil?
           return Result::ObjectList.new(status_table)
         end
       end
@@ -72,73 +84,80 @@ module Aspera
         @context = Context.new
       end
 
-      # This is the main function called by initial script just after constructor
-      # Processes command line arguments, executes commands, and handles exceptions
-      # @return [nil]
-      def run
-        # Catch exception information , if any
-        exception_info = nil
-        # False if command shall not be executed (e.g. --show-config)
-        execute_command = true
-        # Catch exceptions
-        begin
-          init_agents_and_options
-          # Find plugins, shall be after parse! ?
-          Plugins::Factory.instance.add_plugins_from_lookup_folders
-          # Help requested without command ? (plugins must be known here)
-          show_usage if @option_help && @context.options.command_or_arg_empty?
-          @context.config.periodic_check_newer_gem_version
-          command_sym =
-            if @option_show_config && @context.options.command_or_arg_empty?
-              COMMAND_CONFIG
-            else
-              @context.options.get_next_command(Plugins::Factory.instance.plugin_list.unshift(COMMAND_HELP))
-            end
-          # Command will not be executed, but we need manual
-          @context.options.fail_on_missing_mandatory = false if @option_help || @option_show_config
-          # Main plugin is not dynamically instantiated
-          case command_sym
-          when COMMAND_HELP
-            show_usage
-          when COMMAND_CONFIG
-            command_plugin = @context.config
+      attr_reader :context
+
+      # Execute the command and return the raw `Result` object.
+      # Pure computation: no display, no Process.exit - raises on any error.
+      # @return [Result, nil] the result of the command, or nil if nothing to execute
+      def run_with_result
+        init_agents_and_options
+        Plugins::Factory.instance.add_plugins_from_lookup_folders
+        # Help requested without command? Show global options + plugin list
+        return result_usage if @option_help && @context.options.command_or_arg_empty?
+        @context.config.periodic_check_newer_gem_version
+        command_sym =
+          if @option_show_config && @context.options.command_or_arg_empty?
+            COMMAND_CONFIG
           else
-            # Get plugin, set options, etc
-            command_plugin = get_plugin_instance_with_options(command_sym)
-            # Parse plugin specific options
-            @context.options.parse_options!
+            @context.options.get_next_command(Plugins::Factory.instance.plugin_list.unshift(COMMAND_HELP))
           end
-          # Help requested for current plugin
-          show_usage(all: false) if @option_help
-          if @option_show_config
-            @context.formatter.display_results(Result::SingleObject.new(@context.options.known_options(only_defined: true).stringify_keys))
+        @context.options.fail_on_missing_mandatory = false if @option_help || @option_show_config
+        case command_sym
+        when COMMAND_HELP
+          return result_usage
+        when COMMAND_CONFIG
+          command_plugin = @context.config
+        else
+          command_plugin = get_plugin_instance_with_options(command_sym)
+          @context.options.parse_options!
+        end
+        # --help after a plugin name: if no positional args remain, show plugin-level help now.
+        # If args remain (e.g. `ascli aoc files -h`), let the dispatch consume them and
+        # intercept --help at the right depth via Cli::HelpRequest.
+        return result_usage(plugin: command_plugin) if @option_help && @context.options.command_or_arg_empty?
+        if @option_show_config
+          result = Result::SingleObject.new(@context.options.known_options(only_defined: true).stringify_keys)
+          @context.presets.save_if_needed
+          @context.transfer.shutdown
+          TempFileManager.instance.cleanup
+          return result
+        end
+        execute_command = true
+        lock_port = @context.options.get_option(:lock_port)
+        if !lock_port.nil?
+          begin
+            Log.log.debug { "Opening lock port #{lock_port}" }
+            @tcp_server = TCPServer.new('127.0.0.1', lock_port)
+          rescue StandardError => e
             execute_command = false
+            Log.log.warn { "Another instance is already running (#{e.message})." }
           end
-          # Locking for single execution (only after "per plugin" option, in case lock port is there)
-          lock_port = @context.options.get_option(:lock_port)
-          if !lock_port.nil?
-            begin
-              # No need to close later, will be freed on process exit. must save in member else it is garbage collected
-              Log.log.debug{"Opening lock port #{lock_port}"}
-              # Loopback address, could also be 'localhost'
-              @tcp_server = TCPServer.new('127.0.0.1', lock_port)
-            rescue StandardError => e
-              execute_command = false
-              Log.log.warn{"Another instance is already running (#{e.message})."}
-            end
-          end
-          pid_file = @context.options.get_option(:pid_file)
-          if !pid_file.nil?
-            File.write(pid_file, Process.pid)
-            Log.log.debug{"Wrote pid #{Process.pid} to #{pid_file}"}
-            at_exit{File.delete(pid_file)}
-          end
-          # Execute and display (if not exclusive execution)
-          @context.formatter.display_results(command_plugin.execute_action) if execute_command
-          # Save config file if command modified it
-          @context.config.save_config_file_if_needed
-          # Finish
+        end
+        pid_file = @context.options.get_option(:pid_file)
+        if !pid_file.nil?
+          File.write(pid_file, Process.pid)
+          Log.log.debug { "Wrote pid #{Process.pid} to #{pid_file}" }
+          at_exit { File.delete(pid_file) }
+        end
+        begin
+          result = command_plugin.execute_action if execute_command
+        rescue Cli::HelpRequest => e
+          return result_usage(plugin: e.plugin)
+        ensure
+          @context.presets.save_if_needed
           @context.transfer.shutdown
+          TempFileManager.instance.cleanup
+        end
+        return result
+      end
+
+      # Main entry point: execute the command, display results, exit on error.
+      # @return [nil]
+      def run
+        exception_info = nil
+        begin
+          result = run_with_result
+          @context.formatter.display_results(result) if result
         rescue Net::SSH::AuthenticationFailed => e; exception_info = {e: e, t: 'SSH', security: true}
         rescue OpenSSL::SSL::SSLError => e;         exception_info = {e: e, t: 'SSL'}
         rescue Cli::BadArgument => e;               exception_info = {e: e, t: 'Argument', usage: true}
@@ -152,73 +171,196 @@ module Aspera
         rescue StandardError => e;                  exception_info = {e: e, t: "Other(#{e.class.name})", debug: true}
         rescue Interrupt => e;                      exception_info = {e: e, t: 'Interruption', debug: true}
         end
-        # Cleanup file list files
-        TempFileManager.instance.cleanup
         # 1- processing of error condition
         unless exception_info.nil?
           Log.log.warn(exception_info[:e].message) if Log.instance.logger_type.eql?(:syslog) && exception_info[:security]
-          Log.log.error{"#{exception_info[:t]}: #{exception_info[:e].message}"} unless exception_info[:e].is_a?(Cli::SchemaRequest)
-          Log.log.debug{(['Backtrace:'] + exception_info[:e].backtrace).join("\n")} if exception_info[:debug]
+          Log.log.error { "#{exception_info[:t]}: #{exception_info[:e].message}" } unless exception_info[:e].is_a?(Cli::SchemaRequest)
+          Log.log.debug { (['Backtrace:'] + exception_info[:e].backtrace).join("\n") } if exception_info[:debug]
           @context.formatter.display_message(:error, 'Use option -h to get help.') if exception_info[:usage]
-          # Is that a known error condition with proposal for remediation ?
           Hints.hint_for(exception_info[:e], @context.formatter)
-          # Requested help for a Hash parameter/option ?
           if exception_info[:e].is_a?(Cli::SchemaRequest)
-            Log.log.info{"#{exception_info[:t]}: #{exception_info[:e].message}"}
+            Log.log.info { "#{exception_info[:t]}: #{exception_info[:e].message}" }
             schema_path = exception_info[:e].path
             if schema_path.nil?
-              Log.log.warn{'Sorry, no schema provided yet. Please refer to the manual or API.'}
+              Log.log.warn { 'Sorry, no schema provided yet. Please refer to the manual or API.' }
             else
-              builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(schema_path)).build
-              @context.formatter.display_results(Result::ObjectList.new(builder.rows, fields: builder.columns))
+              reader = Schema::Registry.instance.reader(schema_path)
+              rows   = reader.to_rows.map do |row|
+                if row.key?('enum')
+                  row = row.dup
+                  row['type'] = 'enum'
+                  row['description'] = "#{row['description']}\nAllowed: #{row['enum'].join(', ')}"
+                end
+                row
+              end
+              @context.formatter.display_results(Result::ObjectList.new(rows, fields: %w[name type required description]))
             end
           end
         end
-        # 2- processing of command not processed (due to exception or bad command line)
-        if execute_command || @option_show_config
-          @context.options.final_errors.each do |msg|
-            Log.log.error{"Argument: #{msg}"}
-            # Add code as exception if there is not already an error
+        # 2- processing of unprocessed arguments (skip when help was displayed: sub-commands are not consumed)
+        unless @option_help
+          @context.options&.final_errors&.each do |msg|
+            Log.log.error { "Argument: #{msg}" }
             exception_info = {e: Exception.new(msg), t: 'UnusedArg'} if exception_info.nil?
           end
         end
-        # 3- in case of error, fail the process status
+        # 3- exit on error
         unless exception_info.nil?
-          # Show stack trace in debug mode
           raise exception_info[:e] if Log.log.debug?
-          # Else give hint and exit
           @context.formatter.display_message(:error, 'Use --log-level=debug to get more details.') if exception_info[:debug]
           Process.exit(1)
         end
         return
       end
 
-      # Display usage information and help
-      # @param all [Boolean] if true, show help for all plugins; if false, show only current plugin
-      # @param exit [Boolean] if true, exit the process after displaying help
+      # Display usage information and exit (used by the interactive CLI).
+      # @param plugin [Plugins::Base, nil] plugin instance to show subcommands for
       # @return [nil]
-      def show_usage(all: true, exit: true)
-        # Display main plugin options (+config)
-        @context.formatter.display_message(:error, @context.options.parser)
-        if all
-          @context.only_manual!
-          # List plugins that have a "require" field, i.e. all but main plugin
-          Plugins::Factory.instance.plugin_list.each do |plugin_name_sym|
-            # Config was already included in the global options
-            next if plugin_name_sym.eql?(COMMAND_CONFIG)
-            # Override main option parser with a brand new, to avoid having global options
-            @context.options = Manager.new(Info::CMD_NAME)
-            @context.options.parser.banner = '' # Remove default banner
-            get_plugin_instance_with_options(plugin_name_sym)
-            # Display generated help for plugin options
-            @context.formatter.display_message(:error, @context.options.parser.help)
+      def show_usage(plugin: nil)
+        @context.formatter.display_message(:error, usage_text(plugin: plugin))
+        Process.exit(0)
+      end
+
+      # Return usage as a Result::Text (used by run_with_result, no display, no exit).
+      # @param plugin [Plugins::Base, nil] plugin instance to show subcommands for
+      # @return [Result::Text]
+      def result_usage(plugin: nil)
+        Result::Text.new(usage_text(plugin: plugin))
+      end
+
+      # Composite option handler for the `log` option (dot-notation sub-properties).
+      # Supported sub-properties: +level+, +type+, +format+
+      # @param _option_sym [Symbol] Option name (unused, always :log)
+      # @param operation   [Symbol] +:set+ or +:get+
+      # @param value       [Hash,nil] Hash of sub-properties to set (only for +:set+)
+      def option_log(_option_sym, operation, value = nil)
+        Aspera.assert_values(operation, %i[set get])
+        case operation
+        when :set
+          Aspera.assert_type(value, Hash)
+          value.each do |k, v|
+            case k.to_sym
+            when :level   then Log.instance.level = v.to_sym
+            when :type    then Log.instance.logger_type = v.to_sym
+            when :format  then Log.instance.formatter = v
+            when :secrets then SecretHider.instance.log_secrets = BoolValue.true?(v)
+            else Aspera.error_unexpected_value(k) { 'log sub-option (level, type, format, secrets)' }
+            end
           end
+        when :get
+          return {level: Log.instance.level, type: Log.instance.logger_type, format: Log.instance.formatter, secrets: SecretHider.instance.log_secrets}
         end
-        Process.exit(0) if exit
+        nil
       end
 
       private
 
+      # Build the usage/help text.
+      #
+      # - No plugin:   global options + list of top-level plugins
+      # - With plugin: global options + plugin options + subcommands at the path
+      #                 that was reached before --help was encountered
+      #
+      # @param plugin [Plugins::Base, nil] plugin instance (carries the current dispatch path)
+      # @return [String] the full help text
+      def usage_text(plugin: nil)
+        lines = [@context.options.help_text(banner: app_banner)]
+        if plugin.nil?
+          # Top-level: list all available plugins
+          plugin_names = Plugins::Factory.instance.plugin_list.reject { |s| s.eql?(COMMAND_CONFIG) }.sort
+          lines << "\nPLUGINS"
+          col_w = plugin_names.map { |n| n.to_s.length }.max + 2
+          plugin_names.each do |name|
+            app = Plugins::Factory.instance.plugin_class(name).application_name
+            lines << "    #{name.to_s.ljust(col_w)}  #{app}"
+          end
+        else
+          path     = plugin.help_path || []
+          registry = plugin.class.command_registry
+          cmds     = registry.children_of(path)
+          label    = plugin.class.name.split('::').last.downcase
+          # Build label with positional argument slots inserted after each intermediate node
+          # e.g. [:access_keys, :do, :download] -> "node access_keys do <access_key_id> download"
+          path.each_with_index do |seg, i|
+            label += " #{seg}"
+            seg_path = path[0..i]
+            seg_spec = registry[seg_path]
+            if seg_spec && registry.children_of(seg_path).any? && seg_spec.arguments
+              seg_spec.arguments.each do |arg_spec|
+                label += " <#{arg_spec.name}>"
+              end
+            end
+          end
+          if cmds.none?
+            leaf_spec = registry[path]
+            leaf_spec&.arguments&.each do |arg_spec|
+              argument = arg_spec.mandatory ? "<#{arg_spec.name}>" : "[#{arg_spec.name}]"
+              argument += '...' if arg_spec.multiple
+              label += " #{argument}"
+            end
+          end
+          if cmds.any?
+            # Intermediate node: show current command + description, then list subcommands
+            lines << "\nCOMMAND: #{label}"
+            node_spec = path.empty? ? nil : registry[path]
+            lines << "  #{node_spec.description}" if node_spec&.description
+            lines << "\n  SUBCOMMANDS:"
+            col_w = cmds.keys.map { |k| k.to_s.length }.max + 2
+            cmds.each do |id, spec|
+              lines << "    #{id.to_s.ljust(col_w)}  #{spec.description}"
+            end
+          else
+            # Leaf node: show description + arguments.
+            spec = registry[path]
+            lines << "\nCOMMAND: #{label}"
+            lines << "    #{spec.description}" if spec&.description
+            display_args = spec&.arguments || []
+            # transfer_paths commands use --sources for the file list; default is positional args (@args)
+            if spec&.transfer_paths
+              file_desc = if spec.transfer_paths == :receive
+                "Remote path(s) to download (default --sources=#{TransferAgent::FILE_LIST_FROM_ARGS}; see also --to-folder)"
+              else
+                "Source file(s) to upload (default --sources=#{TransferAgent::FILE_LIST_FROM_ARGS}; see also --src-type, --to-folder)"
+              end
+              display_args += [ArgumentSpec.new(name: :source_file, description: file_desc, mandatory: false, multiple: true)]
+            end
+            if display_args.any?
+              lines << "\nARGUMENTS:"
+              col_w = display_args.map { |a| a.name.to_s.length }.max + 2
+              display_args.each do |arg|
+                flag  = arg.mandatory ? arg.name.to_s : "[#{arg.name}]"
+                flag += '...' if arg.multiple
+                types = case arg.type
+                when :identifier then 'identifier'
+                when Array       then arg.type.map(&:name).join(', ')
+                when nil         then ''
+                else arg.type.name
+                end
+                hint  = Array(arg.type).include?(Hash) && arg.schema ? '  (schema shown below)' : ''
+                lines << "    #{flag.ljust(col_w)}  #{arg.description || types}#{hint}"
+                lines.concat(schema_help_lines(arg)) if Array(arg.type).include?(Hash) && arg.schema
+              end
+            end
+            lines << "\nTIP: use --query=help to list available query parameters" if spec&.query_schema
+          end
+        end
+        lines.join("\n")
+      end
+
+      # Render the structure of a Hash argument's JSON schema in command help.
+      # @param arg [ArgumentSpec]
+      # @return [Array<String>]
+      def schema_help_lines(arg)
+        builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(arg.schema)).build
+        rows = builder.rows.reject { |row| row['type'].eql?('&nbsp;') }.map do |row|
+          builder.columns.map { |column| row[column].to_s }
+        end
+        style = {}
+        style[:border] = :unicode_round if Environment.terminal_supports_unicode?
+        table = Terminal::Table.new(headings: builder.columns, rows: rows, style: style).to_s
+        ["\n    SCHEMA: #{arg.name}", table.lines.map { |line| "    #{line.chomp}" }.join("\n")]
+      end
+
       # Initialize agents and options
       # This can throw exception if there is a problem with the environment, needs to be caught by execute method
       # @raise [StandardError] if there is a problem with the environment
@@ -228,28 +370,42 @@ module Aspera
         # Create formatter, in case there is an exception, it is used to display.
         @context.formatter = Formatter.new
         # Create command line manager with arguments
-        @context.options = Manager.new(Info::CMD_NAME, @argv)
-        # Formatter adds options
-        @context.formatter.declare_options(@context.options)
+        @context.options = Parser.new(Info::CMD_NAME, @argv)
+        ExtendedValue.instance.on(EXTEND_ARGS) { |v| @context.options.args_as_extended(v) }
+        # Formatter: declare metadata (class method), then bind to the instance
+        Formatter.declare_options(@context.options)
+        @context.formatter.bind_options(@context.options)
         # Compare $0 with expected name
         current_prog_name = File.basename($PROGRAM_NAME)
-        Aspera.assert(current_prog_name.eql?(Info::CMD_NAME), type: :warn){"Please use '#{Info::CMD_NAME}' instead of '#{current_prog_name}'"}
+        Aspera.assert(current_prog_name.eql?(Info::CMD_NAME), type: :warn) { "Please use '#{Info::CMD_NAME}' instead of '#{current_prog_name}'" }
         # Declare and parse global options
         declare_global_options
+        # Bootstrap: populate context services (main_folder, persistency, presets, http_config,
+        # progress_bar) and configure global singletons before any plugin is instantiated.
+        # The vault callback is lazy: @vault extended-values are only resolved after Config.new,
+        # so @context.config is always set by the time it is called.
+        @bootstrapper = Bootstrapper.new(@context)
+        @bootstrapper.run(
+          gem_plugins_folder: Plugins::Config.gem_plugins_folder,
+          vault_value_cb:     ->(v) { @context.config.vault_value(v) }
+        )
         # Do not display config commands if help is asked
         @context.man_header = false
-        # The Config plugin adds the @preset parser, so declare before TransferAgent which may use it
+        # Config declares remaining plugin options on top of what Bootstrapper already parsed
         @context.config = Plugins::Config.new(context: @context)
         @context.man_header = true
-        # Data persistency is set in config
-        Aspera.assert(@context.persistency, 'missing persistency object')
+        # Sync cache_tokens from Config into the OAuth persist_mgr (now that option is parsed)
+        OAuth::Factory.instance.persist_mgr = @context.persistency if @context.config.option_cache_tokens
+        # Email service: depends on options declared by Config
+        @context.mailer = Mailer.new(@context.options, @context.main_folder)
+        # Secret finder: depends on options (:secret) and presets, both set by Bootstrapper
+        @context.secret_finder = SecretFinder.new(@context.options, @context.presets)
         # The TransferAgent plugin may use the @preset parser
-        @context.transfer = TransferAgent.new(@context.options, @context.config)
+        @context.transfer = TransferAgent.new(@context)
         # Add commands for config plugin after all options have been added
         @context.config.add_manual_header(false)
         @context.validate
         # Set banner when all environment is created so that additional extended value modifiers are known, e.g. @preset
-        @context.options.parser.banner = app_banner
       end
 
       # Generate the application banner for help display
@@ -261,7 +417,7 @@ module Aspera
           #{t}#{Info::CMD_NAME} -- a command line tool for Aspera Applications (v#{Cli::VERSION})
 
           SYNOPSIS
-          #{t}#{Info::CMD_NAME} COMMANDS [OPTIONS] [ARGS]
+          #{t}#{Info::CMD_NAME} [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
 
           DESCRIPTION
           #{t}Use Aspera application to perform operations on command line.
@@ -280,8 +436,8 @@ module Aspera
           OPTIONS
           #{t}Options begin with a '-' (minus), and value is provided on command line.
           #{t}Special values are supported beginning with special prefix @pfx:, where pfx is one of:
-          #{t}#{ExtendedValue.instance.modifiers.join(', ')}
-          #{t}Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
+          #{t}#{ExtendedValue.instance.modifiers.reject(&:empty?).join(', ')}
+          #{t}Dates format is 'YYYY-MM-DD HH:MM:SS', or 'now' or '-<num>h'
 
           ARGS
           #{t}Some commands require mandatory arguments, e.g. a path.
@@ -292,29 +448,33 @@ module Aspera
       # @return [nil]
       def declare_global_options
         Log.log.debug('declare_global_options')
-        @context.options.declare(:help, 'Show this message', allowed: Allowed::TYPES_NONE, short: 'h'){@option_help = true}
-        @context.options.declare(:show_config, 'Display parameters used for the provided action', allowed: Allowed::TYPES_NONE){@option_show_config = true}
-        @context.options.declare(:version, 'Display version', allowed: Allowed::TYPES_NONE, short: 'v'){@context.formatter.display_message(:data, Cli::VERSION); Process.exit(0)} # rubocop:disable Style/Semicolon
+        @context.options.declare(:help, description: 'Show this message', allowed: Type::NONE, short: 'h') do
+          @option_help = true
+          @context.options.help_requested = true
+        end
+        @context.options.declare(:show_config, description: 'Display parameters used for the provided action', allowed: Type::NONE) { @option_show_config = true }
+        @context.options.declare(:version, description: 'Display version', allowed: Type::NONE, short: 'v') { @context.formatter.display_message(:data, Cli::VERSION); Process.exit(0) } # rubocop:disable Style/Semicolon
         @context.options.declare(
-          :ui, 'Method to start browser',
+          :ui, description: 'Method to start browser',
           allowed: USER_INTERFACES,
           handler: {o: Environment.instance, m: :url_method}
         )
         @context.options.declare(
-          :invalid_characters, 'Replacement character and invalid filename characters',
+          :invalid_characters, description: 'Replacement character and invalid filename characters',
           handler: {o: Environment.instance, m: :file_illegal_characters}
         )
-        @context.options.declare(:log_level, 'Log level', allowed: Log::LEVELS, handler: {o: Log.instance, m: :level})
-        @context.options.declare(:log_format, 'Log formatter', allowed: [Proc, Logger::Formatter, String], handler: {o: Log.instance, m: :formatter})
-        @context.options.declare(:logger, 'Logging method', allowed: Log::LOG_TYPES, handler: {o: Log.instance, m: :logger_type})
-        @context.options.declare(:lock_port, 'Prevent dual execution of a command, e.g. in cron', allowed: Allowed::TYPES_INTEGER)
-        @context.options.declare(:once_only, 'Process only new items (some commands)', allowed: Allowed::TYPES_BOOLEAN, default: false)
-        @context.options.declare(:log_secrets, 'Show passwords in logs', allowed: Allowed::TYPES_BOOLEAN, handler: {o: SecretHider.instance, m: :log_secrets})
-        @context.options.declare(:clean_temp, 'Cleanup temporary files on exit', allowed: Allowed::TYPES_BOOLEAN, handler: {o: TempFileManager.instance, m: :cleanup_on_exit})
-        @context.options.declare(:temp_folder, 'Temporary folder', handler: {o: TempFileManager.instance, m: :global_temp})
-        @context.options.declare(:pid_file, 'Write process identifier to file, delete on exit')
+        @context.options.declare(:log_level, description: 'Log level', allowed: Log::LEVELS, handler: {o: Log.instance, m: :level})
+        @context.options.declare(:log_format, description: 'Log formatter', allowed: [Proc, Logger::Formatter, String], handler: {o: Log.instance, m: :formatter})
+        @context.options.declare(:logger, description: 'Logging method', allowed: Log::LOG_TYPES, handler: {o: Log.instance, m: :logger_type})
+        @context.options.declare(:log, description: 'Logging options (dot-notation: level, type, format, secrets)', handler: {o: self, m: :option_log}, schema: Schema::Registry::LOG_OPTIONS)
+        @context.options.declare(:lock_port, description: 'Prevent dual execution of a command, e.g. in cron', allowed: Type::INTEGER)
+        @context.options.declare(:once_only, description: 'Process only new items (some commands)', allowed: Type::BOOLEAN, default: false)
+        @context.options.declare(:log_secrets, description: 'Show passwords in logs', allowed: Type::BOOLEAN, handler: {o: SecretHider.instance, m: :log_secrets})
+        @context.options.declare(:clean_temp, description: 'Cleanup temporary files on exit', allowed: Type::BOOLEAN, handler: {o: TempFileManager.instance, m: :cleanup_on_exit})
+        @context.options.declare(:temp_folder, description: 'Temporary folder', handler: {o: TempFileManager.instance, m: :global_temp})
+        @context.options.declare(:pid_file, description: 'Write process identifier to file, delete on exit')
         @context.options.declare(
-          :parser, 'Default parser for structured parameters and options',
+          :parser, description: 'Default parser for structured parameters and options',
           handler: {o: ExtendedValue.instance, m: :default_decoder},
           allowed: ExtendedValue::DEFAULT_DECODERS,
           default: ExtendedValue::DEFAULT_DECODERS.first
@@ -328,12 +488,22 @@ module Aspera
       # @param plugin_name_sym [Symbol] symbol for plugin name
       # @return [Plugins::Base] the plugin instance
       def get_plugin_instance_with_options(plugin_name_sym)
-        Log.log.debug{"get_plugin_instance_with_options(#{plugin_name_sym})"}
-        # Load default params only if no param already loaded before plugin instantiation
-        @context.config.add_plugin_default_preset(plugin_name_sym)
+        Log.log.debug { "get_plugin_instance_with_options(#{plugin_name_sym})" }
+        # Load default preset options for this plugin from config file
+        default_config_name = @context.presets.plugin_default_name(plugin_name_sym)
+        Log.log.debug { "add_plugin_default_preset:#{plugin_name_sym}:#{default_config_name}" }
+        @context.options.add_option_preset(@context.presets.by_name(default_config_name), 'default_plugin', override: false) unless default_config_name.nil?
         command_plugin = Plugins::Factory.instance.create(plugin_name_sym, context: @context)
         return command_plugin
       end
+      COMMAND_CONFIG = :config
+      COMMAND_HELP = :help
+      # Types that go to result of type = text
+      SCALAR_TYPES = [String, Integer, Symbol].freeze
+      USER_INTERFACES = %i[text graphical].freeze
+      EXTEND_ARGS = :''
+
+      private_constant :COMMAND_CONFIG, :COMMAND_HELP, :SCALAR_TYPES, :USER_INTERFACES, :EXTEND_ARGS
     end
   end
 end