aspera-cli 4.25.6 → 4.26.1

data/lib/aspera/cli/manager.rb

@@ -12,6 +12,20 @@ require 'optparse'
 
 module Aspera
   module Cli
+    # Exception raised when schema is asked (`help`)
+    class SchemaRequest < Error
+      # @return [String, nil] path to schema file
+      attr_reader :path
+
+      # @param type [Symbol] :argument or :option
+      # @param name [String] name of the option/argument
+      # @param schema_path [String, nil] path to schema file, or `nil` if not available
+      def initialize(type, name, schema_path)
+        super("#{type}: #{name}")
+        @path = schema_path
+      end
+    end
+
     module BoolValue
       # boolean options are set to true/false from the following values
       YES_SYM = :yes
@@ -22,23 +36,24 @@ module Aspera
       # Boolean values
       # @return [Array<true, false, :yes, :no>]
       ALL = (TRUE_VALUES + FALSE_VALUES).freeze
+      # `false` and `true`
       TYPES = [FalseClass, TrueClass].freeze
       SYMBOLS = [NO_SYM, YES_SYM].freeze
       # @return `true` if value is a value for `true` in ALL
       def true?(enum)
         Aspera.assert_values(enum, ALL){'boolean'}
-        return TRUE_VALUES.include?(enum)
+        TRUE_VALUES.include?(enum)
       end
 
       # @return [:yes, :no]
       def to_sym(enum)
         Aspera.assert_values(enum, ALL){'boolean'}
-        return TRUE_VALUES.include?(enum) ? YES_SYM : NO_SYM
+        TRUE_VALUES.include?(enum) ? YES_SYM : NO_SYM
       end
 
       # @return `true` if value is a value for `true` or `false` in ALL
       def symbol?(sym)
-        return ALL.include?(sym)
+        ALL.include?(sym)
       end
       module_function :true?, :to_sym, :symbol?
     end
@@ -52,30 +67,33 @@ module Aspera
       # Value will be coerced to int
       TYPES_INTEGER = [Integer].freeze
       TYPES_BOOLEAN = BoolValue::TYPES
-      # no value at all, it's a switch
+      # No value at all for the option, it's a switch, like `-N`
       TYPES_NONE = [].freeze
+      # Symbol
       TYPES_ENUM = [Symbol].freeze
+      # String
       TYPES_STRING = [String].freeze
     end
 
     # Description of option, how to manage
     class OptionValue
       # [Array(Class)] List of allowed types
-      attr_reader :types, :sensitive
+      attr_reader :types, :sensitive, :schema, :option
       # [Array] List of allowed values (Symbols and specific values)
       attr_accessor :values
 
-      # @param option      [Symbol] Name of option
+      # @param option [Symbol] Name of option
       # @param description [String] Description for help
-      # @param allowed  [nil,Class,Array<Class>,Array<Symbol>] Allowed values
-      # @param handler       [Hash] Accessor: keys: :o(object) and :m(method)
+      # @param allowed [nil,Class,Array<Class>,Array<Symbol>] Allowed values
+      # @param handler [Hash] Accessor: keys: :o(object) and :m(method)
       # @param deprecation [String] Deprecation message
+      # @param schema [String] Declaration of schema
       # `allowed`:
       # - `nil` No validation, so just a string
       # - `Class` The single allowed Class
       # - `Array<Class>` Multiple allowed classes
       # - `Array<Symbol>` List of allowed values
-      def initialize(option:, description:, allowed: Allowed::TYPES_STRING, handler: nil, deprecation: nil)
+      def initialize(option:, description:, allowed: Allowed::TYPES_STRING, handler: nil, deprecation: nil, schema: nil)
         Log.log.trace1{"option: #{option}, allowed: #{allowed}"}
         @option = option
         @description = description
@@ -86,6 +104,7 @@ module Aspera
         @read_method = handler&.[](:m)
         @write_method = @read_method ? "#{@read_method}=".to_sym : nil
         @deprecation = deprecation
+        @schema = schema
         @access = if @object.nil?
           :local
         elsif @object.respond_to?(@write_method)
@@ -102,7 +121,7 @@ module Aspera
           if allowed.take(Allowed::TYPES_SYMBOL_ARRAY.length) == Allowed::TYPES_SYMBOL_ARRAY
             # Special case: array of defined symbol values
             @types = Allowed::TYPES_SYMBOL_ARRAY
-            @values = allowed[Allowed::TYPES_SYMBOL_ARRAY.length..-1]
+            @values = allowed[Allowed::TYPES_SYMBOL_ARRAY.length..]
           elsif allowed.all?(Class)
             @types = allowed
             @values = BoolValue::ALL if allowed.eql?(Allowed::TYPES_BOOLEAN)
@@ -131,12 +150,14 @@ module Aspera
           when :setter then @object.send(@read_method, @option, :get)
           end
         Log.log.trace1{"#{@option} -> (#{current_value.class})#{current_value}"} if log
-        return current_value
+        current_value
       end
 
       # Assign value to option.
-      # Value can be a String, then evaluated with ExtendedValue, or directly a value.
+      # Value can be a `String`, then evaluated with `ExtendedValue`, or directly a value.
       # @param value [String, Object] Value to assign to option
+      # @param where [String] Where the value is assigned from
+      # @return [nil]
       def assign_value(value, where:)
         Aspera.assert(!@deprecation, type: warn){"Option #{@option} is deprecated: #{@deprecation}"}
         new_value = ExtendedValue.instance.evaluate(value, context: "option: #{@option}", allowed: @types)
@@ -146,11 +167,10 @@ module Aspera
         new_value = [new_value] if @types.eql?(Allowed::TYPES_STRING_ARRAY) && new_value.is_a?(String)
         # Setting a Hash to null set an empty hash
         new_value = {} if new_value.eql?(nil) && @types&.first.eql?(Hash)
-        # Setting a Array to null set an empty hash
+        # Setting a Array to null set an empty array
         new_value = [] if new_value.eql?(nil) && @types&.first.eql?(Array)
         if @types.eql?(Aspera::Cli::Allowed::TYPES_SYMBOL_ARRAY)
           new_value = [new_value] if new_value.is_a?(String)
-          Aspera.assert_type(new_value, Array, type: BadArgument)
           Aspera.assert_array_all(new_value, String, type: BadArgument)
           new_value = new_value.map{ |v| Manager.get_from_list(v, @option, @values)}
         end
@@ -166,6 +186,7 @@ module Aspera
         when :setter then @object.send(@read_method, @option, :set, new_value)
         end
         Log.log.trace1{v = value(log: false); "#{@option} <- (#{v.class})#{v}"} # rubocop:disable Style/Semicolon
+        nil
       end
     end
 
@@ -184,25 +205,34 @@ module Aspera
           Aspera.assert(!matching.empty?, multi_choice_assert_msg("unknown value for #{descr}: #{short_value}", allowed_values), type: BadArgument)
           Aspera.assert(matching.length.eql?(1), multi_choice_assert_msg("ambiguous shortcut for #{descr}: #{short_value}", matching), type: BadArgument)
           return BoolValue.true?(matching.first) if allowed_values.eql?(BoolValue::ALL)
-          return matching.first
+          matching.first
         end
 
         # Generates error message with list of allowed values
-        # @param error_msg [String] error message
-        # @param accept_list [Array] list of allowed values
+        # @param error_msg [String] Error message
+        # @param accept_list [Array<Symbol>] List of allowed values
         def multi_choice_assert_msg(error_msg, accept_list)
-          [error_msg, 'Use:'].concat(accept_list.map{ |c| "- #{c}"}.sort).join("\n")
+          [error_msg, 'Use:', *accept_list.map{ |choice| "- #{choice}"}.sort].join("\n")
         end
 
         # Change option name with dash to name with underscore
         # @param name [String] option name
         # @return [String]
         def option_line_to_name(name)
-          return name.gsub(OPTION_SEP_LINE, OPTION_SEP_SYMBOL)
+          name.gsub(OPTION_SEP_LINE, OPTION_SEP_SYMBOL)
         end
 
         def option_name_to_line(name)
-          return "#{OPTION_PREFIX}#{name.to_s.gsub(OPTION_SEP_SYMBOL, OPTION_SEP_LINE)}"
+          "#{OPTION_PREFIX}#{name.to_s.gsub(OPTION_SEP_SYMBOL, OPTION_SEP_LINE)}"
+        end
+
+        # @return [Hash{Symbol => String}, nil] `{field:,value:}` if identifier is a percent selector, else `nil`
+        def percent_selector(identifier)
+          Aspera.assert_type(identifier, String)
+          if (m = identifier.match(REGEX_LOOKUP_ID_BY_FIELD))
+            return {field: m[1], value: ExtendedValue.instance.evaluate(m[2], context: "percent selector: #{m[1]}")}
+          end
+          nil
         end
       end
 
@@ -210,6 +240,8 @@ module Aspera
       attr_accessor :ask_missing_mandatory, :ask_missing_optional
       attr_writer :fail_on_missing_mandatory
 
+      # @param program_name [String] Name of the program
+      # @param argv [Array<String>, nil] Command line arguments to parse
       def initialize(program_name, argv = nil)
         # command line values *not* starting with '-'
         @unprocessed_cmd_line_arguments = []
@@ -217,7 +249,8 @@ module Aspera
         @unprocessed_cmd_line_options = []
         # a copy of all initial options
         @initial_cli_options = []
-        # option description: option_symbol => OptionValue
+        # Option descriptions: maps option symbol to its OptionValue descriptor
+        # @type [Hash{Symbol => OptionValue}]
         @declared_options = {}
         # do we ask missing options and arguments to user ?
         @ask_missing_mandatory = false # STDIN.isatty
@@ -236,7 +269,7 @@ module Aspera
         # options can also be provided by env vars : --param-name -> ASCLI_PARAM_NAME
         env_prefix = program_name.upcase + OPTION_SEP_SYMBOL
         ENV.each do |k, v|
-          @option_pairs_env[k[env_prefix.length..-1].downcase.to_sym] = v if k.start_with?(env_prefix)
+          @option_pairs_env[k.delete_prefix(env_prefix).downcase.to_sym] = v if k.start_with?(env_prefix)
         end
         Log.log.debug{"env=#{@option_pairs_env}".red}
         @unprocessed_cmd_line_options = []
@@ -267,6 +300,14 @@ module Aspera
         # do not parse options yet, let's wait for option `-h` to be overridden
       end
 
+      # Add a type to the message if not special types
+      # @param types [Array<Class>] types to add
+      # @return [String] Types if relevant
+      def add_types_info(types)
+        return '' if !types || types.empty? || types.eql?(Allowed::TYPES_ENUM) || types.eql?(Allowed::TYPES_BOOLEAN) || types.eql?(Allowed::TYPES_STRING)
+        " (#{types.map(&:name).join(', ')})"
+      end
+
       # Declare an option
       # @param option_symbol [Symbol] option name
       # @param description   [String] description for help
@@ -275,13 +316,14 @@ module Aspera
       # @param default       [Object] default value
       # @param handler       [Hash]   handler for option value: keys: :o(object) and :m(method)
       # @param deprecation   [String] deprecation
+      # @param schema        [String] Definition of schema for Hash parameters
       # @param block [Proc] Block to execute when option is found
-      def declare(option_symbol, description, short: nil, allowed: nil, default: nil, handler: nil, deprecation: nil, &block)
+      def declare(option_symbol, description, short: nil, allowed: nil, default: nil, handler: nil, deprecation: nil, schema: nil, &block)
         Aspera.assert_type(option_symbol, Symbol)
         Aspera.assert(!@declared_options.key?(option_symbol)){"#{option_symbol} already declared"}
         Aspera.assert(description[-1] != '.'){"#{option_symbol} ends with dot"}
         Aspera.assert(description[0] == description[0].upcase){"#{option_symbol} description does not start with an uppercase"}
-        Aspera.assert(!['hash', 'extended value'].any?{ |s| description.downcase.include?(s)}){"#{option_symbol} shall use :allowed"}
+        Aspera.assert(!['hash', 'extended value'].any?{ |s| description.downcase.include?(s)}){"#{option_symbol} shall use :allowed instead of hash/extended value in option description"}
         Aspera.assert_type(handler, Hash) if handler
         Aspera.assert(handler.keys.sort.eql?(%i[m o])) if handler
         option_attrs = @declared_options[option_symbol] = OptionValue.new(
@@ -289,10 +331,11 @@ module Aspera
           description: description,
           allowed:     allowed,
           handler:     handler,
-          deprecation: deprecation
+          deprecation: deprecation,
+          schema:      schema
         )
         real_types = option_attrs.types&.reject{ |i| [NilClass, String, Symbol].include?(i)}
-        description = "#{description} (#{real_types.map(&:name).join(', ')})" if real_types && !real_types.empty? && !real_types.eql?(Allowed::TYPES_ENUM) && !real_types.eql?(Allowed::TYPES_BOOLEAN) && !real_types.eql?(Allowed::TYPES_STRING)
+        description += add_types_info(real_types)
         description = "#{description} (#{'deprecated'.blue}: #{deprecation})" if deprecation
         set_option(option_symbol, default, where: 'default') unless default.nil?
         on_args = [description]
@@ -331,32 +374,36 @@ module Aspera
       end
 
       # @param descr       [String] description for help
-      # @param mandatory   [Boolean] if true, raise error if option not set
-      # @param multiple    [Boolean] if true, return remaining arguments (Array) until END
-      # @param accept_list [Array, NilClass] list of allowed values (Symbol)
+      # @param mandatory   [Boolean] `true`: raise error no more argument
+      # @param multiple    [Boolean] `true`: return all remaining arguments (Array). String: until marker
+      # @param accept_list [Array<Symbol>, NilClass] list of allowed values
       # @param validation  [Class, Array, NilClass] Accepted value type(s) or list of Symbols
       # @param aliases     [Hash] map of aliases: key = alias, value = real value
       # @param default     [Object] default value
       # @return one value, list or nil (if optional and no default)
-      def get_next_argument(descr, mandatory: true, multiple: false, accept_list: nil, validation: Allowed::TYPES_STRING, aliases: nil, default: nil)
+      def get_next_argument(descr, mandatory: true, multiple: false, accept_list: nil, validation: Allowed::TYPES_STRING, aliases: nil, default: nil, schema: nil)
         Aspera.assert_array_all(accept_list, Symbol) unless accept_list.nil?
         Aspera.assert_hash_all(aliases, Symbol, Symbol) unless aliases.nil?
         validation = Symbol unless accept_list.nil?
         validation = [validation] unless validation.is_a?(Array) || validation.nil?
         Aspera.assert_array_all(validation, Class){'validation'} unless validation.nil?
-        descr = "#{descr} (#{validation.join(', ')})" unless validation.nil? || validation.eql?(Allowed::TYPES_STRING)
+        descr = "#{descr}#{add_types_info(validation)}"
         result =
           if !@unprocessed_cmd_line_arguments.empty?
-            if multiple
-              index = @unprocessed_cmd_line_arguments.index(SpecialValues::EOA)
-              if index.nil?
-                values = @unprocessed_cmd_line_arguments.shift(@unprocessed_cmd_line_arguments.length)
-              else
+            case multiple
+            when true
+              values = @unprocessed_cmd_line_arguments.shift(@unprocessed_cmd_line_arguments.length)
+            when false
+              values = [@unprocessed_cmd_line_arguments.shift]
+            when String
+              index = @unprocessed_cmd_line_arguments.index(multiple)
+              if index
                 values = @unprocessed_cmd_line_arguments.shift(index)
-                @unprocessed_cmd_line_arguments.shift # remove EOA
+                @unprocessed_cmd_line_arguments.shift # remove end marker
+              else
+                values = @unprocessed_cmd_line_arguments.shift(@unprocessed_cmd_line_arguments.length)
               end
-            else
-              values = [@unprocessed_cmd_line_arguments.shift]
+            else Aspera.error_unexpected_value(multiple){'multiple'}
             end
             values = values.map{ |v| ExtendedValue.instance.evaluate(v, context: "argument: #{descr}", allowed: validation)}
             # If expecting list and only one arg of type array : it is the list
@@ -369,7 +416,7 @@ module Aspera
             multiple ? values : values.first
           elsif !default.nil? then default
             # no value provided, either get value interactively, or exception
-          elsif mandatory then get_interactive(descr, multiple: multiple, accept_list: accept_list)
+          elsif mandatory then get_interactive(descr, multiple: multiple, accept_list: accept_list, schema: schema)
           end
         if result.is_a?(String) && validation&.eql?(Allowed::TYPES_INTEGER)
           int_result = Integer(result, exception: false)
@@ -383,23 +430,51 @@ module Aspera
         if validation && (mandatory || !result.nil?)
           value_list = multiple ? result : [result]
           value_list.each do |value|
+            raise SchemaRequest.new(:argument, descr, schema) if validation.include?(Hash) && value.eql?(HELP)
             raise Cli::BadArgument,
               "Argument #{descr} is a #{value.class} but must be #{'one of: ' if validation.length > 1}#{validation.map(&:name).join(', ')}" unless validation.any?{ |t| value.is_a?(t)}
           end
         end
-        return result
+        result
       end
 
-      def get_next_command(command_list, aliases: nil); return get_next_argument('command', accept_list: command_list, aliases: aliases); end
+      # Resource identifier as positional parameter
+      #
+      # @param description [String] description of the identifier
+      # @param block       [Proc] block to search for identifier based on attribute value
+      # @return   [String, Array<String>] identifier or list of IDs (if `bulk` option is set)
+      # @yieldparam field [String] The field name from percent selector
+      # @yieldparam value [String] The value from percent selector
+      # @yieldreturn [String] Resolved identifier
+      def instance_identifier(description: 'identifier', &block)
+        res_id = get_next_argument(description, multiple: get_option(:bulk)) if res_id.nil?
+        # Can be an Array
+        if res_id.is_a?(String) && (m = Manager.percent_selector(res_id))
+          Aspera.assert(block_given?, type: Cli::BadArgument){"Percent syntax for #{description} not supported in this context"}
+          res_id = yield(m[:field], m[:value])
+        end
+        res_id
+      end
+
+      def get_next_command(command_list, aliases: nil); get_next_argument('command', accept_list: command_list, aliases: aliases); end
+
+      # Get an option definition by name
+      # @param option_symbol [Symbol]
+      # @return [OptionValue] Option definition
+      # @raise [Cli::BadArgument] if option not found
+      def option_def(option_symbol)
+        Aspera.assert(@declared_options.key?(option_symbol), type: Cli::BadArgument){"Unknown option: #{option_symbol}"}
+        @declared_options[option_symbol]
+      end
 
       # Get an option value by name
       # either return value or calls handler, can return nil
       # ask interactively if requested/required
+      # @param option_symbol [Symbol]
       # @param mandatory [Boolean] if true, raise error if option not set
       def get_option(option_symbol, mandatory: false)
         Aspera.assert_type(option_symbol, Symbol)
-        Aspera.assert(@declared_options.key?(option_symbol), type: Cli::BadArgument){"Unknown option: #{option_symbol}"}
-        option_attrs = @declared_options[option_symbol]
+        option_attrs = option_def(option_symbol)
         result = option_attrs.value
         # Do not fail for manual generation if option mandatory but not set
         return :skip_missing_mandatory if result.nil? && mandatory && !@fail_on_missing_mandatory
@@ -408,11 +483,11 @@ module Aspera
             Aspera.assert(!mandatory, type: Cli::BadArgument){"Missing mandatory option: #{option_symbol}"}
           elsif @ask_missing_optional || mandatory
             # ask_missing_mandatory
-            result = get_interactive(option_symbol.to_s, check_option: true, accept_list: option_attrs.values)
+            result = get_interactive(option_symbol.to_s, check_option: true, accept_list: option_attrs.values, schema: option_attrs.schema)
             set_option(option_symbol, result, where: 'interactive')
           end
         end
-        return result
+        result
       end
 
       # Set an option value by name, either store value or call handler
@@ -422,15 +497,15 @@ module Aspera
       # @param where [String] Where the value comes from
       def set_option(option_symbol, value, where: 'code override')
         Aspera.assert_type(option_symbol, Symbol)
-        Aspera.assert(@declared_options.key?(option_symbol), type: Cli::BadArgument){"Unknown option: #{option_symbol}"}
-        @declared_options[option_symbol].assign_value(value, where: where)
+        option = option_def(option_symbol)
+        raise SchemaRequest.new(:option, option.option, option.schema) if option.types&.include?(Hash) && value.eql?(HELP)
+        option.assign_value(value, where: where)
       end
 
       # Set option to `nil`
       def clear_option(option_symbol)
         Aspera.assert_type(option_symbol, Symbol)
-        Aspera.assert(@declared_options.key?(option_symbol), type: Cli::BadArgument){"Unknown option: #{option_symbol}"}
-        @declared_options[option_symbol].clear
+        option_def(option_symbol).clear
       end
 
       # Adds each of the keys of specified hash as an option
@@ -453,7 +528,7 @@ module Aspera
 
       # Check if there were unprocessed values to generate error
       def command_or_arg_empty?
-        return @unprocessed_cmd_line_arguments.empty?
+        @unprocessed_cmd_line_arguments.empty?
       end
 
       # Unprocessed options or arguments ?
@@ -461,7 +536,7 @@ module Aspera
         result = []
         result.push("unprocessed options: #{@unprocessed_cmd_line_options}") unless @unprocessed_cmd_line_options.empty?
         result.push("unprocessed values: #{@unprocessed_cmd_line_arguments}") unless @unprocessed_cmd_line_arguments.empty?
-        return result
+        result
       end
 
       # Get all original options on command line used to generate a config in config file
@@ -471,7 +546,7 @@ module Aspera
         @initial_cli_options.each do |option_argument|
           # ignore short options
           next unless option_argument.start_with?(OPTION_PREFIX)
-          name, value = option_argument[OPTION_PREFIX.length..-1].split(OPTION_VALUE_SEPARATOR, 2)
+          name, value = option_argument.delete_prefix(OPTION_PREFIX).split(OPTION_VALUE_SEPARATOR, 2)
           # ignore options without value
           next if value.nil?
           Log.log.debug{"option #{name}=#{value}"}
@@ -480,7 +555,7 @@ module Aspera
           DotContainer.dotted_to_container(path, smart_convert(value), result)
           @unprocessed_cmd_line_options.delete(option_argument)
         end
-        return result
+        result
       end
 
       # @param only_defined [Boolean] if true, only return options that were defined
@@ -493,7 +568,7 @@ module Aspera
         rescue => e
           result[option_symbol] = e.to_s
         end
-        return result
+        result
       end
 
       # Removes already known options from the list
@@ -508,14 +583,14 @@ module Aspera
         begin
           # remove known options one by one, exception if unknown
           Log.log.trace1('Before parse')
-          Log.dump(:unprocessed_cmd_line_options, @unprocessed_cmd_line_options)
+          Log.dump(:unprocessed_cmd_line_options, @unprocessed_cmd_line_options, level: :trace1)
           @parser.parse!(@unprocessed_cmd_line_options)
           Log.log.trace1('After parse')
         rescue OptionParser::InvalidOption => e
           Log.log.trace1{"InvalidOption #{e}".red}
           # An option like --a.b.c=d does: a={"b":{"c":ext_val(d)}}
           if e.args.first.start_with?(OPTION_PREFIX)
-            name, value = e.args.first[OPTION_PREFIX.length..-1].split(OPTION_VALUE_SEPARATOR, 2)
+            name, value = e.args.first.delete_prefix(OPTION_PREFIX).split(OPTION_VALUE_SEPARATOR, 2)
             if !value.nil?
               path = name.split(DotContainer::SEPARATOR)
               option_sym = self.class.option_line_to_name(path.shift).to_sym
@@ -541,7 +616,7 @@ module Aspera
         print("#{prompt}> ")
         line = $stdin.gets
         Aspera.assert_type(line, String){'Unexpected end of standard input'}
-        return line.chomp
+        line.chomp
       end
 
       # prompt user for input in a list of symbols
@@ -562,20 +637,19 @@ module Aspera
       # Prompt user for input in a list of symbols
       # @param descr        [String] description for help
       # @param check_option [Boolean] Check attributes of option with name=descr
-      # @param multiple     [Boolean] true if multiple values expected
-      # @param accept_list  [Array] list of expected values
-      def get_interactive(descr, check_option: false, multiple: false, accept_list: nil)
+      # @param multiple     [Boolean, String] `true` if multiple values expected
+      # @param accept_list  [Array<Symbol>,NilClass] List of expected values
+      # @return [String] user input
+      def get_interactive(descr, check_option: false, multiple: false, accept_list: nil, schema: nil)
         option_attrs = @declared_options[descr.to_sym]
         what = option_attrs ? 'option' : 'argument'
+        default_prompt = "#{what}: #{descr}"
         if !@ask_missing_mandatory
-          message = "missing #{what}: #{descr}"
-          if accept_list.nil?
-            raise Cli::BadArgument, message
-          else
-            Aspera.assert(false, self.class.multi_choice_assert_msg(message, accept_list), type: Cli::MissingArgument)
-          end
+          message = "Missing #{default_prompt}"
+          message = self.class.multi_choice_assert_msg(message, accept_list) if accept_list
+          message += "\nGive `#{HELP}` as argument to retrieve the schema of the missing argument." if schema
+          raise Cli::MissingArgument, message
         end
-        default_prompt = "#{what}: #{descr}"
         # ask interactively
         result = []
         puts(' (one per line, end with empty line)') if multiple
@@ -589,18 +663,20 @@ module Aspera
           return entry unless multiple
           result.push(entry)
         end
-        return result
+        result
       end
 
-      # Read remaining args and build an Array or Hash
-      # @param value [nil] Argument to `@:` extended value
-      def args_as_extended(arg)
+      # Read remaining args and build an `Array` or `Hash`
+      # @param value [String] Argument to `@:` extended value
+      # @return [Hash, Array] Object representing dot-path values
+      def args_as_extended(end_marker)
         # This extended value does not take args (`@:`)
-        ExtendedValue.assert_no_value(arg, :p)
+        # ExtendedValue.assert_no_value(end_marker, :p)
+        end_marker = SpecialValues::EOA if end_marker.empty?
         result = nil
-        get_next_argument(:args, multiple: true).each do |arg|
-          Aspera.assert(arg.include?(OPTION_VALUE_SEPARATOR)){"Positional argument: #{arg} does not include #{OPTION_VALUE_SEPARATOR}"}
-          path, value = arg.split(OPTION_VALUE_SEPARATOR, 2)
+        get_next_argument('args', multiple: end_marker).each do |argument|
+          Aspera.assert(argument.include?(OPTION_VALUE_SEPARATOR)){"Positional argument: #{argument} does not include #{OPTION_VALUE_SEPARATOR}"}
+          path, value = argument.split(OPTION_VALUE_SEPARATOR, 2)
           result = DotContainer.dotted_to_container(path.split(DotContainer::SEPARATOR), smart_convert(value), result)
         end
         result
@@ -627,7 +703,7 @@ module Aspera
       def symbol_to_option(symbol, opt_val = nil)
         result = [OPTION_PREFIX, symbol.to_s.gsub(OPTION_SEP_SYMBOL, OPTION_SEP_LINE)].join
         result = [result, OPTION_VALUE_SEPARATOR, opt_val].join unless opt_val.nil?
-        return result
+        result
       end
 
       # TODO: use formatter
@@ -678,8 +754,12 @@ module Aspera
       # when this is alone, this stops option processing
       OPTIONS_STOP = '--'
       SOURCE_USER = 'cmdline' # cspell:disable-line
+      # Percent selector: select by this field for this value
+      REGEX_LOOKUP_ID_BY_FIELD = /^%([^:]+):(.*)$/
+      # Ask for schema of Extended value
+      HELP = 'help'
 
-      private_constant :OPTION_SEP_LINE, :OPTION_SEP_SYMBOL, :OPTION_VALUE_SEPARATOR, :OPTION_PREFIX, :OPTIONS_STOP, :SOURCE_USER
+      private_constant :OPTION_SEP_LINE, :OPTION_SEP_SYMBOL, :OPTION_VALUE_SEPARATOR, :OPTION_PREFIX, :OPTIONS_STOP, :SOURCE_USER, :REGEX_LOOKUP_ID_BY_FIELD
     end
   end
 end

data/lib/aspera/cli/options.schema.yaml

@@ -0,0 +1,82 @@
+openapi: 3.0.0
+info:
+  title: Aspera CLI Options Schema
+  version: 1.0.0
+  description: Schema definitions for Aspera CLI options
+paths: {}
+components:
+  schemas:
+    TransferInfo:
+      type: object
+      description: Optional parameters to control multi-session transfers, Web Socket Session, resume policy, and additional arguments for `ascp`.
+      properties:
+        wss:
+          type: boolean
+          description: Enable Web Socket Session when available.
+          default: true
+        quiet:
+          type: boolean
+          description: Suppress the `ascp` progress bar display.
+          default: false
+        trusted_certs:
+          type: array
+          description: List of trusted certificate repositories.
+          items:
+            type: string
+        client_ssh_key:
+          type: string
+          description: SSH key type to use for token-based transfers.
+          enum:
+            - rsa
+            - dsa_rsa
+            - per_client
+          default: rsa
+        ascp_args:
+          type: array
+          description: List of native `ascp` command-line arguments.
+          items:
+            type: string
+          default: []
+        spawn_timeout_sec:
+          type: number
+          format: float
+          description: Multi session - Maximum time (in seconds) to verify that `ascp` is running.
+          default: 3
+        spawn_delay_sec:
+          type: number
+          format: float
+          description: Multi session - Delay (in seconds) between starting each `ascp` session.
+          default: 2
+        multi_incr_udp:
+          type: boolean
+          description: >-
+            Multi session - Increment UDP port for each session.
+            
+            If `true`, each session uses a different UDP port starting at `fasp_port` (default: 33001).
+            
+            If `false`, all sessions use the same `fasp_port` (or `ascp` default).
+          default: true
+        resume:
+          type: object
+          description: Configuration for automatic transfer resume on interruption.
+          properties:
+            iter_max:
+              type: integer
+              description: Maximum number of retry attempts on error.
+              default: 7
+            sleep_initial:
+              type: integer
+              description: Initial sleep duration (in seconds) before first retry.
+              default: 2
+            sleep_factor:
+              type: integer
+              description: Multiplier applied to sleep duration between consecutive retry attempts.
+              default: 2
+            sleep_max:
+              type: integer
+              description: Maximum sleep duration (in seconds) between retry attempts.
+              default: 60
+        monitor:
+          type: boolean
+          description: Enable use of the `ascp` management port for transfer monitoring.
+          default: true