aspera-cli 4.25.3 → 4.26.0.pre

data/lib/aspera/api/aoc.rb

@@ -7,11 +7,15 @@ require 'aspera/hash_ext'
 require 'aspera/data_repository'
 require 'aspera/transfer/spec'
 require 'aspera/api/node'
+require 'aspera/rest_list'
 require 'base64'
 
 module Aspera
   module Api
+    # Aspera on Cloud API client
     class AoC < Rest
+      include RestList
+
       PRODUCT_NAME = 'Aspera on Cloud'
       # use default workspace if it is set, else none
       DEFAULT_WORKSPACE = ''
@@ -144,12 +148,11 @@ module Aspera
 
         # Call `block` with same query using paging and response information.
         # Block must return a 2 element `Array` with data and http response
-        # @param query    [Hash] Additionnal query parameters
-        # @param progress [nil, Object] Uses methods: `long_operation_running` and `long_operation_terminated`
+        # @param query    [Hash] Additional query parameters
         # @return [Hash] Items and total number of items
         # @option return [Array<Hash>] :items The list of items
         # @option return [Integer] :total The total number of items
-        def call_paging(query: {}, progress: nil)
+        def call_paging(query: {})
           Aspera.assert_type(query, Hash){'query'}
           Aspera.assert(block_given?)
           # set default large page if user does not specify own parameters. AoC Caps to 1000 anyway
@@ -177,9 +180,9 @@ module Aspera
             break if !max_items.nil? && item_list.count >= max_items
             break if !max_pages.nil? && page_count >= max_pages
             break if total_count&.<=(item_list.count)
-            progress&.long_operation_running("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
+            RestParameters.instance.spinner_cb.call("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
           end
-          progress&.long_operation_terminated
+          RestParameters.instance.spinner_cb.call(action: :success)
           item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
           return {items: item_list, total: total_count}
         end
@@ -210,7 +213,7 @@ module Aspera
           when 'upload' then %w[mkdir write]
           when Array
             Aspera.assert_array_all(levels, String){'access_levels'}
-            levels.each{ |level| Aspera.assert_value(level, Node::ACCESS_LEVELS){'access_level'}}
+            levels.each{ |level| Aspera.assert_values(level, Node::ACCESS_LEVELS){'access_level'}}
             levels
           else Aspera.error_unexpected_value(levels){"access_levels must be a list of #{Node::ACCESS_LEVELS.join(', ')} or one of edit, preview, download, upload"}
           end
@@ -232,8 +235,7 @@ module Aspera
         username: nil,
         password: nil,
         workspace: nil,
-        secret_finder: nil,
-        progress_disp: nil
+        secret_finder: nil
       )
         # Test here because link may set url
         Aspera.assert(url, 'Missing mandatory option: url', type: ParameterError)
@@ -244,7 +246,6 @@ module Aspera
         # key: access key
         # value: associated secret
         @secret_finder = secret_finder
-        @progress_disp = progress_disp
         @workspace_name = workspace
         @cache_user_info = nil
         @cache_url_token_info = nil
@@ -309,7 +310,7 @@ module Aspera
       # @param query [nil, Hash] Additional query
       # @return [Hash] {items: , total: }
       def read_with_paging(subpath, query = nil)
-        return self.class.call_paging(query: query, progress: @progress_disp) do |paged_query|
+        return self.class.call_paging(query: query) do |paged_query|
           read(subpath, query: paged_query, ret: :both)
         end
       end
@@ -495,7 +496,7 @@ module Aspera
       # in that case, the name is resolved and replaced with {type: , id: }
       # @param package_data    [Hash]   The whole package creation payload
       # @param rcpt_lst_field  [String] The field in structure, i.e. recipients or bcc_recipients
-      # @param new_user_option [Hash]   Additionnal fields for contact creation
+      # @param new_user_option [Hash]   Additional fields for contact creation
       # @return nil, `package_data` is modified
       def resolve_package_recipients(package_data, rcpt_lst_field, new_user_option)
         return unless package_data.key?(rcpt_lst_field)
@@ -513,7 +514,7 @@ module Aspera
             # email: user, else dropbox
             entity_type = short_recipient_info.include?('@') ? 'contacts' : 'dropboxes'
             begin
-              full_recipient_info = lookup_by_name(entity_type, short_recipient_info, query: {'current_workspace_id' => ws_id})
+              full_recipient_info = lookup_by_name(entity_type, short_recipient_info, query: {'workspace_id' => ws_id})
             rescue EntityNotFound
               # dropboxes cannot be created on the fly
               Aspera.assert_values(entity_type, 'contacts', type: Error){"No such shared inbox in workspace #{ws_id}"}

data/lib/aspera/api/ats.rb

@@ -5,7 +5,7 @@ require 'aspera/rest'
 
 module Aspera
   module Api
-    # ATS API without authentication
+    # Aspera Transfer Service API client without authentication
     class Ats < Aspera::Rest
       SERVICE_BASE_URL = 'https://ats.aspera.io'
       # currently supported clouds

data/lib/aspera/api/cos_node.rb

@@ -7,9 +7,11 @@ require 'xmlsimple'
 
 module Aspera
   module Api
+    # Cloud Object Storage Node API Client
     class CosNode < Node
       IBM_CLOUD_TOKEN_URL = 'https://iam.cloud.ibm.com/identity'
       TOKEN_FIELD = 'delegated_refresh_token'
+      FASP_INFO_KEYS = %w[ATSEndpoint AccessKey].freeze
       class << self
         def parameters_from_svc_credentials(service_credentials, bucket_region)
           # check necessary contents
@@ -60,6 +62,9 @@ module Aspera
         ).body
         ats_info = XmlSimple.xml_in(xml_result_text, {'ForceArray' => false})
         Log.dump(:ats_info, ats_info)
+        Aspera.assert_hash_all(ats_info, String, nil){'ats_info'}
+        Aspera.assert((FASP_INFO_KEYS - ats_info.keys).empty?){'ats_info missing required keys'}
+        Aspera.assert_hash_all(ats_info['AccessKey'], String, String){'ats_info'}
         @storage_credentials = {
           'type'  => 'token',
           'token' => {TOKEN_FIELD => nil}

data/lib/aspera/api/faspex.rb

@@ -2,10 +2,11 @@
 
 require 'aspera/rest'
 require 'aspera/oauth/base'
+require 'aspera/rest_list'
 require 'digest'
 
 module Aspera
-  # Implement OAuth for Faspex public link
+  # OAuth for Faspex public link
   class FaspexPubLink < OAuth::Base
     class << self
       attr_accessor :additional_info
@@ -55,7 +56,10 @@ module Aspera
   end
   OAuth::Factory.instance.register_token_creator(FaspexPubLink)
   module Api
+    # Aspera Faspex 5 API Client
     class Faspex < Aspera::Rest
+      include RestList
+
       # endpoint for authentication API
       PATH_AUTH = 'auth'
       PATH_API_V5 = 'api/v5'
@@ -91,7 +95,7 @@ module Aspera
       JOB_RUNNING = %w[queued working].freeze
       PATH_STANDARD_ROOT = '/aspera/faspex'
       PATH_API_DETECT = "#{PATH_API_V5}/#{PATH_HEALTH}"
-      HEADER_ITERATION_TOKEN = 'X-Aspera-Next-Iteration-Token'
+      HEADER_X_NEXT_ITER_TOKEN = 'X-Aspera-Next-Iteration-Token'
       HEADER_FASPEX_VERSION = 'X-IBM-Aspera'
       EMAIL_NOTIF_LIST = %w[
         welcome_email
@@ -136,6 +140,15 @@ module Aspera
       end
       attr_reader :pub_link_context
 
+      # @param url             Faspex URL, can be a public link
+      # @param auth            Authentication method: :boot (token in header), :web (open browser), :jwt (client_id + private key), :public_link (context in URL)
+      # @param password        For :boot auth, the token copied directly from browser in developer mode
+      # @param client_id       For :web and :jwt auth, the client_id of web UI application
+      # @param client_secret   For :web auth, the client_secret of web UI application (not needed for :jwt)
+      # @param redirect_uri    For :web auth, the redirect_uri of web UI application (must be the same as in application configuration)
+      # @param username        For :jwt auth, the username of the user to impersonate
+      # @param private_key     For :jwt auth, the private key to sign JWT token
+      # @param passphrase      For :jwt auth, the passphrase of the private key
       def initialize(
         url:,
         auth:,

data/lib/aspera/api/httpgw.rb

@@ -4,6 +4,7 @@ require 'aspera/log'
 require 'aspera/rest'
 require 'aspera/transfer/faux_file'
 require 'aspera/assert'
+require 'net/protocol'
 require 'securerandom'
 require 'websocket'
 require 'base64'
@@ -11,6 +12,7 @@ require 'json'
 
 module Aspera
   module Api
+    # Aspera HTTP Gateway API client
     # Start a transfer using Aspera HTTP Gateway, using web socket secure for uploads
     # ref: https://api.ibm.com/explorer/catalog/aspera/product/ibm-aspera/api/http-gateway-api/doc/guides-toc
     # https://developer.ibm.com/apis/catalog?search=%22aspera%20http%22

data/lib/aspera/api/node.rb

@@ -6,16 +6,17 @@ require 'aspera/oauth'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/environment'
-require 'zlib'
 require 'base64'
 require 'openssl'
 require 'pathname'
+require 'zlib'
 require 'net/ssh/buffer'
 
 module Aspera
   module Api
-    # Provides additional functions using node API with gen4 extensions (access keys)
-    class Node < Aspera::Rest
+    # Aspera Node API client
+    # with gen4 extensions (access keys)
+    class Node < Rest
       # Format of node scope : node.<access key>:<scope>
       module Scope
         # Node sub-scopes
@@ -42,9 +43,10 @@ module Aspera
       ACCESS_LEVELS = %w[delete list mkdir preview read rename write].freeze
       # Special HTTP Headers
       HEADER_X_ASPERA_ACCESS_KEY = 'X-Aspera-AccessKey'
-      HEADER_X_TOTAL_COUNT = 'X-Total-Count'
       HEADER_X_CACHE_CONTROL = 'X-Aspera-Cache-Control'
+      HEADER_X_TOTAL_COUNT = 'X-Total-Count'
       HEADER_X_NEXT_ITER_TOKEN = 'X-Aspera-Next-Iteration-Token'
+      HEADER_ACCEPT_VERSION = 'Accept-Version'
       # / in cloud
       PATH_SEPARATOR = '/'
 
@@ -52,22 +54,36 @@ module Aspera
       OAuth::Factory.instance.register_decoder(lambda{ |token| Node.decode_bearer_token(token)})
 
       # Class instance variable, access with accessors on class
-      @use_standard_ports = true
-      @use_node_cache = true
-
-      class << self
+      @api_options = {
         # Set to false to read transfer parameters from download_setup
-        attr_accessor :use_standard_ports
+        standard_ports: true,
         # Set to false to bypass cache in redis
-        attr_accessor :use_node_cache
+        cache:          true,
+        accept_v4:      true
+      }
+      OPTIONS = @api_options.keys.freeze
+
+      class << self
+        attr_reader :api_options
         attr_reader :use_dynamic_key
 
-        # Adds cache control header, as globally specified to read request
-        # Use like this: read(...,**cache_control)
-        def cache_control
-          headers = {'Accept' => Mime::JSON}
-          headers[HEADER_X_CACHE_CONTROL] = 'no-cache' unless use_node_cache
-          {headers: headers}
+        def api_options=(h)
+          Aspera.assert_type(h, Hash)
+          h.each do |k, v|
+            Aspera.assert(@api_options.key?(k.to_sym)){"unknown api option: #{k} (#{OPTIONS.join(', ')})"}
+            Aspera.assert_type(v, TrueClass, FalseClass){"api options value for #{k} should be boolean"}
+            @api_options[k.to_sym] = v
+          end
+        end
+
+        # Adds cache control header for node API /files/:id
+        # as globally specified to read request
+        # Use like this: read(..., headers: add_cache_control)
+        # @param headers [Hash] optional initial headers to add to
+        # @return [Hash] headers with cache control header added if needed
+        def add_cache_control(headers = {})
+          headers[HEADER_X_CACHE_CONTROL] = 'no-cache' unless api_options[:cache]
+          headers
         end
 
         # Set private key to be used
@@ -180,8 +196,8 @@ module Aspera
             Aspera.assert(!access_key.nil?)
           end
           return {
-            Node::HEADER_X_ASPERA_ACCESS_KEY => access_key,
-            'Authorization'                  => bearer_auth
+            HEADER_X_ASPERA_ACCESS_KEY => access_key,
+            'Authorization'            => bearer_auth
           }
         end
       end
@@ -248,6 +264,50 @@ module Aspera
         return false
       end
 
+      # Read folder content, with pagination management for gen4, not recursive
+      # if `Accept-Version: 4.0` is not specified:
+      #     if `page` and `per_page` are not specified, then all entries are returned.
+      #     if either `page` or `per_page` is specified, then both are required, else 400
+      # if `Accept-Version: 4.0` is specified:
+      #     those queries are not available: page (not mentioned), sort, min_size, max_size, min_modified_time, max_modified_time, target_id, target_node_id, files_prefetch_count, page, name_iglob : either ignored or result in API error 400.
+      #     query include is accepted, but seems to do nothing as access_levels and recursive_counts are already included in results.
+      #     query `iteration_token` is accepted and allows to get paginated results, with `X-Aspera-Next-Iteration-Token` header in response to get next page token. `X-Aspera-Total-Count` header gives total count of entries.
+      def read_folder_content(file_id, query = nil, exception: true, path: nil)
+        folder_items = []
+        begin
+          query ||= {}
+          headers = self.class.add_cache_control
+          use_v4 = self.class.api_options[:accept_v4]
+          return read("files/#{file_id}/files", query, headers: headers) unless use_v4 || query.key?('page') || query.key?('per_page')
+          if use_v4
+            headers[HEADER_ACCEPT_VERSION] = '4.0'
+            query['per_page'] = 1000 unless query.key?('per_page')
+          elsif query.key?('per_page') && !query.key?('page')
+            query['page'] = 0
+          end
+          loop do
+            RestParameters.instance.spinner_cb.call(folder_items.count)
+            data, http = read("files/#{file_id}/files", query, headers: headers, ret: :both)
+            folder_items.concat(data)
+            if use_v4
+              iteration_token = http[HEADER_X_NEXT_ITER_TOKEN]
+              break if iteration_token.nil? || iteration_token.empty?
+              query['iteration_token'] = iteration_token
+            else
+              break if data['item_count'].eql?(0)
+              query['offset'] += data['item_count']
+            end
+          end
+        rescue StandardError => e
+          raise e if exception
+          Log.log.warn{"#{path}: #{e.class} #{e.message}"}
+          Log.log.debug{(['Backtrace:'] + e.backtrace).join("\n")}
+        ensure
+          RestParameters.instance.spinner_cb.call(folder_items.count, action: :success)
+        end
+        folder_items
+      end
+
       # Recursively browse in a folder (with non-recursive method)
       # Entries of folders are processed if the processing method returns true
       # Links are processed on the respective node
@@ -267,14 +327,7 @@ module Aspera
           current_item = folders_to_explore.shift
           Log.log.debug{"Exploring #{current_item[:path]}".bg_green}
           # Get folder content
-          folder_contents =
-            begin
-              # TODO: use header
-              read("files/#{current_item[:id]}/files", query, **self.class.cache_control)
-            rescue StandardError => e
-              Log.log.warn{"#{current_item[:path]}: #{e.class} #{e.message}"}
-              []
-            end
+          folder_contents = read_folder_content(current_item[:id], query, exception: false, path: current_item[:path])
           Log.dump(:folder_contents, folder_contents)
           folder_contents.each do |entry|
             if entry.key?('error')
@@ -309,7 +362,7 @@ module Aspera
       # @param path [String] file or folder path (end with "/" is like setting process_last_link)
       # @param process_last_link [Boolean] if true, follow the last link
       # @return [Hash] Result data
-      # @option return [Aspera::Rest] :api     REST client instance
+      # @option return [Rest] :api     REST client instance
       # @option return [String]       :file_id File identifier
       def resolve_api_fid(top_file_id, path, process_last_link = false)
         Aspera.assert_type(top_file_id, String)
@@ -445,7 +498,7 @@ module Aspera
         # Add application specific tags (AoC)
         @app_info[:api].add_ts_tags(transfer_spec: transfer_spec, app_info: @app_info) unless @app_info.nil?
         # Add remote host info
-        if self.class.use_standard_ports
+        if self.class.api_options[:standard_ports]
           # Get default TCP/UDP ports and transfer user
           transfer_spec.merge!(Transfer::Spec::AK_TSPEC_BASE)
           # By default: same address as node API
@@ -456,7 +509,7 @@ module Aspera
           # Get the transfer user from info on access key
           transfer_spec['remote_user'] = info['transfer_user'] if info['transfer_user']
           # Get settings from name.value array to hash key.value
-          settings = info['settings']&.each_with_object({}){ |i, h| h[i['name']] = i['value']}
+          settings = info['settings']&.to_h{ |i| [i['name'], i['value']]}
           # Check WSS ports
           Transfer::Spec::WSS_FIELDS.each do |i|
             transfer_spec[i] = settings[i] if settings.key?(i)

data/lib/aspera/ascp/installation.rb

@@ -83,16 +83,15 @@ module Aspera
 
       # @return [Hash] with key = file name (String), and value = path to file
       def file_paths
-        return SDK_FILES.each_with_object({}) do |v, m|
-          m[v.to_s] =
-            begin
-              path(v)
-            rescue Errno::ENOENT => e
-              e.message.gsub(/.*assertion failed: /, '').gsub(/\): .*/, ')')
-            rescue => e
-              e.message
-            end
-        end
+        return SDK_FILES.to_h do |v|
+                 [v.to_s, begin
+                   path(v)
+                 rescue Errno::ENOENT => e
+                   e.message.gsub(/.*assertion failed: /, '').gsub(/\): .*/, ')')
+                 rescue => e
+                   e.message
+                 end]
+               end
       end
 
       # TODO: if using another product than SDK, should use files from there

data/lib/aspera/cli/error.rb

@@ -9,7 +9,15 @@ module Aspera
     class MissingArgument < Error; end
     class NoSuchElement < Error; end
 
+    # Raised when a lookup for a specific entity fails to return exactly one result.
+    #
+    # Provides a formatted message indicating whether the entity was missing
+    # or if multiple matches were found (ambiguity).
     class BadIdentifier < Error
+      # @param res_type [String] The type of entity being looked up (e.g., 'user').
+      # @param res_id   [String] The value of the identifier that failed.
+      # @param field    [String] The name of the field used for lookup (defaults to 'identifier').
+      # @param count    [Integer] The number of matches found (0 for not found, >1 for ambiguous).
       def initialize(res_type, res_id, field: 'identifier', count: 0)
         msg = count.eql?(0) ? 'not found' : "found #{count}"
         super("#{res_type} with #{field}=#{res_id}: #{msg}")

data/lib/aspera/cli/formatter.rb

@@ -128,20 +128,34 @@ module Aspera
         @spinner = nil
       end
 
-      # call this after REST calls if several api calls are expected
-      def long_operation_running(title = '')
+      def long_operation(title = nil, action: :spin)
         return unless Environment.terminal?
-        if @spinner.nil?
+        return if %i[error data].include?(@options[:display])
+
+        # Handle the "delayed start" state
+        return @spinner = :starting if action == :spin && @spinner.nil?
+
+        # Cleanup if we try to stop a spinner that never actually started
+        @spinner = nil if action != :spin && @spinner == :starting
+        return if @spinner.nil?
+
+        # Initialize the real TTY object if it's currently just the :starting symbol
+        if @spinner == :starting
           @spinner = TTY::Spinner.new('[:spinner] :title', format: :classic)
+          @spinner.update(title: '')
           @spinner.start
         end
-        @spinner.update(title: title)
-        @spinner.spin
-      end
 
-      def long_operation_terminated
-        @spinner&.stop
-        @spinner = nil
+        @spinner.update(title: title) if title
+
+        case action
+        when :spin
+          @spinner.spin
+        when :success, :fail
+          action == :success ? @spinner.success : @spinner.error
+          @spinner.stop
+          @spinner = nil
+        end
       end
 
       def declare_options(options)
@@ -150,9 +164,9 @@ module Aspera
         else
           {}
         end
+        options.declare(:display, 'Output only some information', allowed: DISPLAY_LEVELS, handler: {o: self, m: :option_handler}, default: :data)
         options.declare(:format, 'Output format', allowed: DISPLAY_FORMATS, handler: {o: self, m: :option_handler}, default: :table)
         options.declare(:output, 'Destination for results', handler: {o: self, m: :option_handler})
-        options.declare(:display, 'Output only some information', allowed: DISPLAY_LEVELS, handler: {o: self, m: :option_handler}, default: :info)
         options.declare(
           :fields, "Comma separated list of: fields, or #{SpecialValues::ALL}, or #{SpecialValues::DEF}", handler: {o: self, m: :option_handler},
           allowed: [String, Array, Regexp, Proc],
@@ -178,6 +192,8 @@ module Aspera
           @options[option_symbol] = value
           # special handling of some options
           case option_symbol
+          when :format
+            @options[:display] = value.eql?(:table) ? :info : :data
           when :output
             $stdout = if value.eql?('-')
               STDOUT # rubocop:disable Style/GlobalStdStream
@@ -197,7 +213,7 @@ module Aspera
         nil
       end
 
-      # main output method
+      # Main output method
       # data: for requested data, not displayed if level==error
       # info: additional info, displayed if level==info
       # error: always displayed on stderr

data/lib/aspera/cli/info.rb

@@ -7,7 +7,8 @@ module Aspera
       CMD_NAME = 'ascli'
       # Name of the containing gem, same as in <gem name>.gemspec
       GEM_NAME = 'aspera-cli'
-      DOC_URL  = "https://www.rubydoc.info/gems/#{GEM_NAME}"
+      DOC_URL  = 'https://ibm.biz/ascli-doc'
+      RUBYDOC_URL = "https://www.rubydoc.info/gems/#{GEM_NAME}"
       GEM_URL  = "https://rubygems.org/gems/#{GEM_NAME}"
       SRC_URL  = 'https://github.com/IBM/aspera-cli'
       CONTAINER = 'docker.io/martinlaurent/ascli'

data/lib/aspera/cli/main.rb

@@ -12,18 +12,34 @@ require 'aspera/cli/hints'
 require 'aspera/secret_hider'
 require 'aspera/log'
 require 'aspera/assert'
+require 'net/ssh/errors'
+require 'openssl'
 
 module Aspera
   module Cli
     # Global objects shared with plugins
     class Context
+      # @!attribute [rw] options
+      #   @return [Manager] the command line options manager
+      # @!attribute [rw] transfer
+      #   @return [TransferAgent] the transfer agent, used by transfer plugins
+      # @!attribute [rw] config
+      #   @return [Plugins::Config] the configuration plugin, used by plugins to get configuration values and presets
+      # @!attribute [rw] formatter
+      #   @return [Formatter] the formatter, used by plugins to display results and messages
+      # @!attribute [rw] persistency
+      #   @return [Object] # whatever the type is
+      # @!attribute [rw] man_header
+      #   @return [Boolean] whether to display the manual header in plugin help
       MEMBERS = %i[options transfer config formatter persistency man_header].freeze
       attr_accessor(*MEMBERS)
 
+      # Initialize all members to nil, so that they are defined and can be validated later
       def initialize
-        @man_header = true
+        MEMBERS.each{ |i| instance_variable_set(:"@#{i}", nil)}
       end
 
+      # Validate that all members are set, raise exception if not
       def validate
         MEMBERS.each do |i|
           Aspera.assert(instance_variable_defined?(:"@#{i}"))
@@ -35,7 +51,7 @@ module Aspera
         transfer.eql?(:only_manual)
       end
 
-      def only_manual
+      def only_manual!
         @transfer = :only_manual
       end
     end
@@ -89,13 +105,15 @@ module Aspera
           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].map(&:to_s).join(',')
+            item[STATUS_FIELD] = item[STATUS_FIELD].join(',')
           end
           raise global_status unless global_status.eql?(:success)
           return result_object_list(status_table)
         end
 
         # Display image for that URL or directly blob
+        #
+        # @param url_or_blob [String] URL or blob to display as image
         def result_image(url_or_blob)
           return {type: :image, data: url_or_blob}
         end
@@ -111,6 +129,9 @@ module Aspera
         end
 
         # A list of values
+        #
+        # @param data [Array] The list of values
+        # @param name [String] The name of the list (used for display)
         def result_value_list(data, name: 'id')
           Aspera.assert_type(data, Array)
           Aspera.assert_type(name, String)
@@ -155,7 +176,9 @@ module Aspera
         execute_command = true
         # Catch exceptions
         begin
-          init_agents_options_plugins
+          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?
           generate_bash_completion if @bash_completion
@@ -253,17 +276,11 @@ module Aspera
         return
       end
 
-      def init_agents_options_plugins
-        init_agents_and_options
-        # Find plugins, shall be after parse! ?
-        Plugins::Factory.instance.add_plugins_from_lookup_folders
-      end
-
       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
+          @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
@@ -283,6 +300,7 @@ module Aspera
 
       # This can throw exception if there is a problem with the environment, needs to be caught by execute method
       def init_agents_and_options
+        @context.man_header = true
         # Create formatter, in case there is an exception, it is used to display.
         @context.formatter = Formatter.new
         # Create command line manager with arguments
@@ -336,7 +354,7 @@ 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.map(&:to_s).join(', ')}
+          #{t}#{ExtendedValue.instance.modifiers.join(', ')}
           #{t}Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
 
           ARGS