aspera-cli 4.27.2 → 4.27.4

data/lib/aspera/cli/plugins/config.rb

@@ -8,6 +8,7 @@ require 'aspera/cli/extended_value'
 require 'aspera/cli/special_values'
 require 'aspera/cli/version'
 require 'aspera/cli/formatter'
+require 'aspera/cli/http'
 require 'aspera/cli/info'
 require 'aspera/cli/wizard'
 require 'aspera/cli/sync_actions'
@@ -30,6 +31,7 @@ require 'aspera/rest'
 require 'aspera/oauth/jwt'
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/string_ext'
 require 'openssl'
 require 'digest'
 require 'open3'
@@ -81,66 +83,66 @@ module Aspera
         end
 
         DEFAULT_CHECK_NEW_VERSION_DAYS = 7
-        private_constant :DEFAULT_CHECK_NEW_VERSION_DAYS
+        # Shells with a completion script in COMPLETION_FOLDER
+        COMPLETION_SHELLS = %i[bash zsh fish].freeze
+        COMPLETION_FOLDER = File.expand_path('../completion', __dir__)
+        private_constant :DEFAULT_CHECK_NEW_VERSION_DAYS, :COMPLETION_SHELLS, :COMPLETION_FOLDER
 
-        option :preset,             description: 'Load the named option preset from current config file',             short: 'P', handler: :option_preset
+        option :preset,             description: 'Load the named option preset from current config file',             short: 'P', on_set: :load_preset
         option :version_check_days, description: 'Period in days to check new version (zero to disable)',             allowed: Type::INTEGER, default: DEFAULT_CHECK_NEW_VERSION_DAYS
-        option :plugin_folder,      description: 'Folder where to find additional plugins',                           handler: :option_plugin_folder
+        option :plugin_folder,      description: 'Folder where to find additional plugins',                           on_set: :add_plugin_folders
         option :sdk_url,            description: 'Ascp: URL to get Aspera Transfer Executables',                      default: SpecialValues::DEF
-        option :locations_url,      description: 'Ascp: URL to get download locations of Aspera Transfer Daemon',    handler: {o: Ascp::Installation.instance, m: :transferd_urls}
-        option :sdk_folder,         description: 'Ascp: Path to folder with ascp (or product with "product:")',      handler: {o: Products::Transferd, m: :sdk_directory}
+        option :locations_url,      description: 'Ascp: URL to get download locations of Aspera Transfer Daemon',    default: Ascp::Installation.instance.transferd_urls, on_set: Ascp::Installation.instance.method(:transferd_urls=)
+        option :sdk_folder,         description: 'Ascp: Path to folder with ascp (or product with "product:")',      on_set: Ascp::Installation.instance.method(:sdk_folder=)
         option :smtp,               schema: Schema::Registry::SMTP_OPTIONS
         option :notify_to,          description: 'Email: Recipient for notification of transfers'
         option :notify_template,    description: 'Email: ERB template for notification of transfers'
-        option :cache_tokens,       description: 'Save and reuse OAuth tokens', allowed: Type::BOOLEAN, default: true, handler: :option_cache_tokens
+        option :cache_tokens,       description: 'Save and reuse OAuth tokens', allowed: Type::BOOLEAN, default: true
+        option :expand_mounts,      description: 'Commands: list commands of sub-trees provided by another plugin', allowed: Type::BOOLEAN, default: false
+        option :no_default,         description: 'Do not load default configuration for plugin', allowed: Type::NONE, short: 'N', on_set: -> { presets.use_plugin_defaults = false }
+        use_options Wizard
+        # `on_set` callbacks of HTTP options are methods of `http_config`
+        use_options Http, target: -> { http_config }
 
         def initialize(**_)
           super
           @vault_instance = nil
           @sdk_default_location = false
-          @option_cache_tokens = true
-          # :no_default uses a &block callback - must stay imperative
-          options.declare(:no_default, description: 'Do not load default configuration for plugin', allowed: Type::NONE, short: 'N') { presets.use_plugin_defaults = false }
-          # Declare wizard options (Wizard#initialize calls options.declare internally)
           @wizard = Wizard.new(self, context.main_folder)
+          # Values set through `on_set` callbacks are used below (sdk_folder)
           options.parse_options!
           set_sdk_dir
-          # HTTP options: declare metadata (class method), then bind to the instance
-          Http.declare_options(options)
-          context.http_config.bind_options(options)
-          options.parse_options!
         end
 
-        # DSL command declarations - replaces ACTIONS + execute_action
         command :preset, description: 'Manage configuration presets'
         commands_under :preset do
-          command :list,     description: 'List all presets'
-          command :overview, description: 'Display all options from all presets'
+          command :list,     description: 'List all presets', action: ->(**) { Result::ValueList.new(presets.config_presets.keys, name: 'name') }
+          command :overview, description: 'Show all options from all presets'
           command :lookup,   description: 'Find preset matching URL and username'
           command :secure,   description: 'Move secrets to vault',
-            arguments: [{name: :config_name, type: String, mandatory: false}]
-          command :show,       description: 'Display a preset',
+            arguments: [{name: :config_name, mandatory: false}]
+          command :show,       description: 'Show a preset',
             arguments: [{name: :name, type: :identifier}]
           command :delete,     description: 'Delete a preset',
             arguments: [{name: :name, type: :identifier}]
-          command :get,        description: 'Get a single parameter from a preset',
-            arguments: [{name: :name, type: :identifier}, {name: :param_name, type: String}]
+          command :get,        description: 'Show a single parameter of a preset',
+            arguments: [{name: :name, type: :identifier}, {name: :param_name}]
           command :unset,      description: 'Remove a parameter from a preset',
-            arguments: [{name: :name, type: :identifier}, {name: :param_name, type: String}]
+            arguments: [{name: :name, type: :identifier}, {name: :param_name}]
           command :set, description: 'Set a parameter in a preset',
-            arguments: [{name: :name, type: :identifier}, {name: :param_name, type: String},
+            arguments: [{name: :name, type: :identifier}, {name: :param_name},
                         {name: :param_value, type: nil}]
           command :initialize, description: 'Initialize a preset with a value',
-            arguments: [{name: :name, type: :identifier}, {name: :config_value, type: Hash}]
+            arguments: [{name: :name, type: :identifier}, {name: :preset, type: Hash}]
           command :update,     description: 'Update a preset with current option values',
             arguments: [{name: :name, type: :identifier}]
-          command :ask,        description: 'Interactively ask for option values',
+          command :ask,        description: 'Ask for option values interactively',
             arguments: [{name: :name, type: :identifier},
-                        {name: :option_names, type: String, multiple: true, interactive: true}]
+                        {name: :option_names, multiple: true, interactive: true}]
         end
         command(
           :open, description: 'Open the configuration file in the default editor',
-          action: lambda do
+          action: lambda do |**|
             Environment.instance.open_editor(context.presets.config_file.to_s)
             Result::Nothing.new
           end
@@ -148,106 +150,163 @@ module Aspera
         command :documentation, description: 'Open the documentation in the default browser',
           arguments: [
             {name: :location, type: Symbol, mandatory: false, default: :github, allowed: %i[github local toc]},
-            {name: :section,  type: String, mandatory: false}
+            {name: :section, mandatory: false}
           ]
-        command :genkey, description: 'Generate a new RSA private key',
+        command(
+          :genkey, description: 'Generate a new RSA private key',
           arguments: [
-            {name: :private_key_path, type: String},
+            {name: :private_key_path},
             {name: :private_key_length, type: Integer, mandatory: false, default: OAuth::Jwt::DEFAULT_PRIV_KEY_LENGTH}
-          ]
-        command :pubkey, description: 'Display the public key of an RSA private key',
-          arguments: [{name: :private_key_pem, type: String}],
+          ],
+          action: lambda do |private_key_path:, private_key_length: OAuth::Jwt::DEFAULT_PRIV_KEY_LENGTH, **|
+            OAuth::Jwt.generate_rsa_private_key(path: private_key_path, length: private_key_length)
+            Result::Status.new("Generated #{private_key_length} bit RSA key: #{private_key_path}")
+          end
+        )
+        command :pubkey, description: 'Show the public key of an RSA private key',
+          arguments: [{name: :private_key_pem}],
           action: ->(private_key_pem:, **) { Result::Text.new(OpenSSL::PKey::RSA.new(private_key_pem).public_key.to_s) }
         command :remote_certificate, description: 'Retrieve the certificate chain of a remote HTTPS server'
-        command :echo, description: 'Display the value of a given argument',
+        command :echo, description: 'Show the value of a given argument',
           arguments: [{name: :value, type: nil}],
           action: ->(value:, **) { Result.auto(value) }
         command :download, description: 'Download a file from a URL',
           arguments: [
-            {name: :file_url,  type: String},
-            {name: :file_dest, type: String, mandatory: false}
+            {name: :file_url},
+            {name: :file_dest, mandatory: false}
           ]
         command :tokens, description: 'Manage OAuth tokens'
         command :plugins, description: 'Manage CLI plugins'
         command :detect, description: 'Detect the Aspera product from a URL (interactive)',
-          arguments: [{name: :url, type: String}, {name: :plugin_name, mandatory: false, default: nil}]
-        command :wizard, description: 'Run the setup wizard for an Aspera product (interactive)',
-          arguments: [{name: :url, type: String}, {name: :plugin_name, mandatory: false, default: nil},
-                      {name: :preset_name, mandatory: false, default: ''}]
-        command :coffee, description: 'Display a coffee image', action: -> { Result::Image.new(COFFEE_IMAGE_URL) }
-        command :image, description: 'Display an image',
+          arguments: [{name: :url, interactive: true}, {name: :plugin_name, mandatory: false, default: nil}],
+          action: ->(url:, plugin_name: nil, **) { Result::ObjectList.new(@wizard.identify_plugins_for_url(url: url, plugin_name: plugin_name).freeze) }
+        command(
+          :wizard, description: 'Run the setup wizard for an Aspera product (interactive)',
+          arguments: [{name: :url, interactive: true}, {name: :plugin_name, mandatory: false, default: nil},
+                      {name: :preset_name, mandatory: false, default: ''}],
+          action: lambda do |url:, plugin_name: nil, preset_name: '', **|
+            apps = @wizard.identify_plugins_for_url(url: url, plugin_name: plugin_name).freeze
+            # The product wizard prompts for missing mandatory options (username, password, ...)
+            options.with_interactive { @wizard.find(apps, preset_name: preset_name) }
+          end
+        )
+        command :coffee, description: 'Show a coffee image', action: ->(**) { Result::Image.new(COFFEE_IMAGE_URL) }
+        command :image, description: 'Show an image',
           arguments: [{name: :image_uri, type: nil}],
           action: ->(image_uri:, **) { Result::Image.new(image_uri) }
         command :sync, description: 'Manage Aspera Sync operations'
-        command :gem, description: 'Display gem information'
-        command :folder, description: 'Display the configuration folder path', action: -> { Result::Text.new(context.main_folder) }
-        command :file, description: 'Display the configuration file path', action: -> { Result::Text.new(context.presets.config_file) }
+        command :gem, description: 'Show gem information'
+        command :folder, description: 'Show the configuration folder path', action: ->(**) { Result::Text.new(context.main_folder) }
+        command :file, description: 'Show the configuration file path', action: ->(**) { Result::Text.new(context.presets.config_file) }
         command(
           :email_test, description: 'Send a test email',
-          action: lambda do
+          action: lambda do |**|
             context.mailer.send_email_template(email_template_default: EMAIL_TEST_TEMPLATE)
             Result::Nothing.new
           end
         )
-        command :smtp_settings, description: 'Display the current SMTP settings', action: -> { Result::SingleObject.new(context.mailer.email_settings) }
+        command :smtp_settings, description: 'Show the current SMTP settings', action: ->(**) { Result::SingleObject.new(context.mailer.email_settings) }
         command(
           :proxy_check, description: 'Check the proxy returned by the PAC script for a given URL',
-          arguments: [{name: :server_url, type: String}],
+          arguments: [{name: :server_url}],
           action: lambda do |server_url:, **|
             Aspera.assert(!context.pac_executor.nil?, type: Cli::BadArgument) { 'No PAC script configured, use --fpac' }
             Result::ValueList.new(context.pac_executor.get_proxies(server_url), name: 'proxy')
           end
         )
-        command :check_update, description: 'Check if a newer version of the gem is available', action: -> { Result::SingleObject.new(check_gem_version) }
+        command :check_update, description: 'Check if a newer version of the gem is available', action: ->(**) { Result::SingleObject.new(check_gem_version) }
         command :initdemo, description: 'Initialize the demo server preset'
         command :vault, description: 'Manage secrets in the vault'
         commands_under :vault do
-          command :info,     description: 'Display vault information',
+          command :info,     description: 'Show vault information',
             action: ->(**) { Result::SingleObject.new(vault_required.info) }
           command :ids,      description: 'List secret labels in the vault',
             action: ->(**) { Result::ObjectList.new(vault_required.ids) }
           command :list,     description: 'List all secrets with full details',
             action: ->(**) { Result::ObjectList.new(vault_required.all) }
-          command :show,     description: 'Show a secret by label (or id)',
-            arguments: [{name: :label, type: String}, {name: :id, type: String, mandatory: false, default: nil}]
-          command :create,   description: 'Add a new secret to the vault',
-            arguments: [{name: :info, type: Hash, schema: Schema::Registry::VAULT_SECRET}]
-          command :delete,   description: 'Delete a secret by label (or id)',
-            arguments: [{name: :label, type: String}, {name: :id, type: String, mandatory: false, default: nil}]
-          command :password, description: 'Change the vault password',
-            arguments: [{name: :new_password, type: String}]
-          command :import,   description: 'Import secrets from a JSON array (supports --bulk)',
+          command(
+            :show,     description: 'Show a secret by label (or id)',
+            arguments: [{name: :label}, {name: :id, mandatory: false, default: nil}],
+            action: lambda do |label:, id: nil, **|
+              v = vault_required
+              kwargs = id && v.method(:get).parameters.any? { |_t, n| n == :id } ? {id: id} : {}
+              Result::SingleObject.new(v.get(label: label, **kwargs))
+            end
+          )
+          command(
+            :create,   description: 'Add a new secret to the vault',
+            arguments: [{name: :secret, type: Hash, schema: Schema::Registry::VAULT_SECRET}],
+            action: lambda do |secret:, **|
+              vault_required.set(secret.symbolize_keys)
+              Result::Status.new('Secret added')
+            end
+          )
+          command :delete, description: 'Delete a secret by label (or id)',
+            arguments: [{name: :label}, {name: :id, mandatory: false, default: nil}]
+          command(
+            :password, description: 'Change the vault password',
+            arguments: [{name: :new_password}],
+            action: lambda do |new_password:, **|
+              Aspera.assert(vault_required.respond_to?(:change_password), 'Vault does not support password change')
+              vault_required.change_password(new_password)
+              Result::Status.new('Vault password updated')
+            end
+          )
+          command :import, description: 'Import secrets from a JSON array (supports --bulk)',
             arguments: [{name: :secrets, type: Array, schema: {type: 'array', items: {'$ref' => Schema::Registry::VAULT_SECRET}}}]
         end
-        command :commands, description: 'List all available commands across all plugins'
+        command :commands, description: 'List all available commands, of all plugins or only the given one, optionally under a command path',
+          arguments: [{name: :plugin_name, mandatory: false, default: nil},
+                      {name: :command_path, multiple: true, mandatory: false, default: nil}]
         command :options, description: 'List all options available for a plugin',
-          arguments: [{name: :plugin_name, type: String}]
+          arguments: [{name: :plugin_name}]
         command :test, description: 'Internal test commands'
-        command :platform, description: 'Display the current platform/architecture', action: -> { Result::Text.new(Environment.instance.architecture) }
-        command :completion, description: 'Generate shell completion scripts'
+        command :platform, description: 'Show the current platform/architecture', action: ->(**) { Result::Text.new(Environment.instance.architecture) }
+        command :completion, description: 'Shell completion: activation scripts and next words'
 
         # remote_certificate sub-commands
         commands_under :remote_certificate do
-          command :chain, description: 'Display the full certificate chain as PEM',
-            arguments: [{name: :remote_url, type: String}]
-          command :only, description: 'Display only the server certificate as PEM',
-            arguments: [{name: :remote_url, type: String}]
-          command :name, description: 'Display the CN of the server certificate',
-            arguments: [{name: :remote_url, type: String}]
+          command(
+            :chain, description: 'Show the full certificate chain as PEM',
+            arguments: [{name: :remote_url}],
+            action: lambda do |remote_url:, **|
+              remote_chain = Rest.remote_certificate_chain(remote_url, as_string: false)
+              Aspera.assert(remote_chain&.first) { "No certificate found for #{remote_url}" }
+              Result::Text.new(remote_chain.map(&:to_pem).join("\n"))
+            end
+          )
+          command(
+            :only, description: 'Show only the server certificate as PEM',
+            arguments: [{name: :remote_url}],
+            action: lambda do |remote_url:, **|
+              remote_chain = Rest.remote_certificate_chain(remote_url, as_string: false)
+              Aspera.assert(remote_chain&.first) { "No certificate found for #{remote_url}" }
+              Result::Text.new(remote_chain.first.to_pem)
+            end
+          )
+          command(
+            :name, description: 'Show the CN of the server certificate',
+            arguments: [{name: :remote_url}],
+            action: lambda do |remote_url:, **|
+              remote_chain = Rest.remote_certificate_chain(remote_url, as_string: false)
+              Aspera.assert(remote_chain&.first) { "No certificate found for #{remote_url}" }
+              Result::Text.new(remote_chain.first.subject.to_a.find { |name, _, _| name == 'CN' }[1])
+            end
+          )
         end
 
         # tokens sub-commands
         commands_under :tokens do
           command(
             :flush, description: 'Delete all cached OAuth tokens',
-            action: lambda do
+            action: lambda do |**|
               require 'aspera/api/node'
               Result::ValueList.new(OAuth::Factory.instance.flush_tokens, name: 'file')
             end
           )
           command(
             :list, description: 'List all cached OAuth tokens',
-            action: lambda do
+            action: lambda do |**|
               require 'aspera/api/node'
               Result::ObjectList.new(OAuth::Factory.instance.persisted_tokens)
             end
@@ -261,25 +320,33 @@ module Aspera
           command :list, description: 'List all available plugins'
           command :create, description: 'Create a new plugin skeleton file',
             arguments: [
-              {name: :name,   type: String},
-              {name: :folder, type: String, mandatory: false}
+              {name: :name},
+              {name: :folder, mandatory: false}
             ]
         end
 
         # ascp sub-commands
         command :ascp, description: 'Manage FASP/ascp transfer engine'
         commands_under :ascp do
-          command :show,    description: 'Display ascp binary path'
-          command :info,    description: 'Display ascp and transfer spec information'
+          command :show,    description: 'Show ascp binary path', action: ->(**) { Result::Text.new(Ascp::Installation.instance.path(:ascp)) }
+          command :info,    description: 'Show ascp and transfer spec information'
           command :install, description: 'Install the transfer SDK',
-            arguments: [{name: :version, mandatory: false, default: nil}]
-          command :spec,    description: 'Display the transfer spec schema'
-          command :schema,  description: 'Display the transfer spec JSON schema',
-            arguments: [{name: :agent_name, mandatory: false, default: nil}]
-          command :errors,   description: 'Display FASP error codes'
+            arguments: [{name: :version, mandatory: false, default: nil}],
+            action: ->(version: nil, **) { install_transfer_sdk(version: version) }
+          command(
+            :spec, description: 'Show the transfer spec schema',
+            action: lambda do |**|
+              builder = Schema::Documentation.new(TerminalFormatter, Transfer::Spec::SCHEMA, include_option: true, agent_columns: true).build
+              Result::ObjectList.new(builder.rows, fields: builder.columns)
+            end
+          )
+          command :schema, description: 'Show the transfer spec JSON schema',
+            arguments: [{name: :agent_name, allowed: Agent::Factory::ALL.keys, mandatory: false, default: nil}]
+          command :errors,   description: 'Show FASP error codes'
           command :products, description: 'Manage installed Aspera products'
           commands_under :products do
-            command :list, description: 'List installed Aspera products'
+            command :list, description: 'List installed Aspera products',
+              action: ->(**) { Result::ObjectList.new(Ascp::Installation.instance.installed_products, fields: %w[name app_root]) }
           end
         end
 
@@ -296,75 +363,93 @@ module Aspera
         # transfer async management sub-commands
         command :transfer, description: 'Manage asynchronous transfers'
         commands_under :transfer do
-          command :list,    description: 'List all async transfer jobs'
+          command(
+            :list, description: 'List all async transfer jobs',
+            action: lambda do |**|
+              rows = async_transfer_store.list
+              Result::ObjectList.new(rows, fields: %w[job_id agent_type status started_at ended_at bytes_transferred transfer_id])
+            end
+          )
           command :status,  description: 'Show status of an async transfer job',
-            arguments: [{name: :job_id, type: String}]
+            arguments: [{name: :job_id}]
           command :cleanup, description: 'Remove completed/failed/cancelled transfer entries'
         end
 
         # transferd sub-commands
         command :transferd, description: 'Manage the transfer daemon (transferd)'
         commands_under :transferd do
-          command :install, description: 'Install the transfer daemon'
-          command :list,    description: 'List available SDK locations'
+          command :install, description: 'Install the transfer daemon', action: ->(**) { install_transfer_sdk }
+          command(
+            :list, description: 'List available SDK locations',
+            action: lambda do |**|
+              sdk_list = Ascp::Installation.instance.sdk_locations
+              Result::ObjectList.new(sdk_list, fields: sdk_list.first.keys - ['url'])
+            end
+          )
         end
 
         # sync sub-commands
         commands_under :sync do
           command(
-            :spec, description: 'Display the sync configuration schema',
-            action: lambda do
+            :spec, description: 'Show the sync configuration schema',
+            action: lambda do |**|
               builder = Schema::Documentation.new(TerminalFormatter, Sync::Operations::CONF_SCHEMA, include_option: true).build
               Result::ObjectList.new(builder.rows, fields: builder.columns)
             end
           )
-          command :admin, description: 'Manage sync database (admin operations)'
-          SyncActions.register_sync_admin_commands(self, :admin)
+          sync_admin_commands :admin
           command :translate, description: 'Translate async-style arguments to sync config format',
-            arguments: [{name: :async_arguments, type: String, multiple: true}],
+            arguments: [{name: :async_arguments, multiple: true}],
             action: ->(async_arguments:, **) { Result::SingleObject.new(Sync::Operations.args_to_conf(async_arguments)) }
         end
 
         # gem sub-commands
         commands_under :gem do
-          command :path,    description: 'Display the gem source root path',    action: -> { Result::Text.new(self.class.gem_src_root) }
-          command :version, description: 'Display the gem version',             action: -> { Result::Text.new(Cli::VERSION) }
-          command :name,    description: 'Display the gem name',                action: -> { Result::Text.new(Info::GEM_NAME) }
+          command :path,    description: 'Show the gem source root path',    action: ->(**) { Result::Text.new(self.class.gem_src_root) }
+          command :version, description: 'Show the gem version',             action: ->(**) { Result::Text.new(Cli::VERSION) }
+          command :name,    description: 'Show the gem name',                action: ->(**) { Result::Text.new(Info::GEM_NAME) }
         end
 
         # test sub-commands
         commands_under :test do
-          command :throw, description: 'Raise an exception (for testing)',
+          command(
+            :throw, description: 'Raise an exception (for testing)',
             arguments: [
-              {name: :exception_class_name, type: String},
-              {name: :exception_text,       type: String}
-            ]
-          command :web, description: 'Test web browser interaction', action: -> {}
+              {name: :exception_class_name},
+              {name: :exception_text}
+            ],
+            action: lambda do |exception_class_name:, exception_text:, **|
+              type = Object.const_get(exception_class_name)
+              Aspera.assert(type <= Exception) { "#{type} is not an exception: #{type.class}" }
+              raise type, exception_text
+            end
+          )
+          command :web, description: 'Test web browser interaction', action: ->(**) {}
         end
 
         # completion sub-commands
         commands_under :completion do
-          command :bash, description: 'Generate bash completion script',
-            arguments: [{name: :words, type: String, multiple: true, mandatory: false}]
+          command :words, description: 'List words that can follow the given words (used by completion scripts)',
+            arguments: [{name: :words, multiple: true, mandatory: false}]
+          COMPLETION_SHELLS.each do |shell|
+            command shell, description: "Generate #{shell} completion script, to evaluate in shell",
+              action: ->(**) { completion_script(shell) }
+          end
         end
 
-        attr_accessor :option_cache_tokens
-
         attr_reader :gem_url
 
-        def option_plugin_folder=(value)
+        # `on_set` callback of option `plugin_folder`
+        # @param value [String, Array<String>] folder(s) where to find plugins
+        def add_plugin_folders(value)
           value = [value] unless value.is_a?(Array)
           Aspera.assert_array_all(value, String) { 'plugin folder(s)' }
           value.each { |f| Plugins::Factory.instance.add_lookup_folder(f) }
         end
 
-        def option_plugin_folder
-          return Plugins::Factory.instance.lookup_folders
-        end
-
-        def option_preset; 'write-only option'; end
-
-        def option_preset=(value)
+        # `on_set` callback of option `preset`
+        # @param value [String, Hash] preset name, or set of option values
+        def load_preset(value)
           case value
           when Hash
             options.add_option_preset(value, 'set')
@@ -406,34 +491,11 @@ module Aspera
           end
         end
 
-        def action_genkey(private_key_path:, private_key_length: OAuth::Jwt::DEFAULT_PRIV_KEY_LENGTH, **)
-          OAuth::Jwt.generate_rsa_private_key(path: private_key_path, length: private_key_length)
-          Result::Status.new("Generated #{private_key_length} bit RSA key: #{private_key_path}")
-        end
-
-        def action_remote_certificate_chain(remote_url:, **)
-          remote_chain = Rest.remote_certificate_chain(remote_url, as_string: false)
-          Aspera.assert(remote_chain&.first) { "No certificate found for #{remote_url}" }
-          Result::Text.new(remote_chain.map(&:to_pem).join("\n"))
-        end
-
-        def action_remote_certificate_only(remote_url:, **)
-          remote_chain = Rest.remote_certificate_chain(remote_url, as_string: false)
-          Aspera.assert(remote_chain&.first) { "No certificate found for #{remote_url}" }
-          Result::Text.new(remote_chain.first.to_pem)
-        end
-
-        def action_remote_certificate_name(remote_url:, **)
-          remote_chain = Rest.remote_certificate_chain(remote_url, as_string: false)
-          Aspera.assert(remote_chain&.first) { "No certificate found for #{remote_url}" }
-          Result::Text.new(remote_chain.first.subject.to_a.find { |name, _, _| name == 'CN' }[1])
-        end
-
         def action_download(file_url:, file_dest: nil, **)
           file_url = file_url.chomp
-          file_dest = File.join(transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE), file_url.gsub(%r{.*/}, '')) if file_dest.nil?
+          file_dest = File.join(transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE), file_url.rpartition('/').last) if file_dest.nil?
           Log.log.info("Downloading: #{file_url}")
-          Rest.new(base_url: file_url).call(operation: 'GET', save_to: file_dest)
+          Rest::Client.new(base_url: file_url).call(operation: 'GET', save_to: file_dest)
           Result::Status.new("Saved to: #{file_dest}")
         end
 
@@ -444,7 +506,7 @@ module Aspera
           Result::SingleObject.new(data)
         end
 
-        def action_plugins_list
+        def action_plugins_list(**)
           result = Plugins::Factory.instance.plugin_list.map do |name|
             plugin_class = Plugins::Factory.instance.plugin_class(name)
             {
@@ -467,10 +529,7 @@ module Aspera
               module Cli
                 module Plugins
                   class #{plugin_name.snake_to_capital} < Base
-                    command :example, description: 'example command', action: :action_example
-                    def action_example
-                      Result::Status.new('You called plugin #{plugin_name}')
-                    end
+                    command :example, description: 'example command', action: ->(**) { Result::Status.new('You called plugin #{plugin_name}') }
                   end
                 end
               end
@@ -480,19 +539,7 @@ module Aspera
           Result::Status.new("Created #{plugin_file}")
         end
 
-        def action_detect(url:, plugin_name: nil, **)
-          options.ask_missing_mandatory = true
-          apps = @wizard.identify_plugins_for_url(url: url, plugin_name: plugin_name).freeze
-          Result::ObjectList.new(apps)
-        end
-
-        def action_wizard(url:, plugin_name: nil, preset_name: '', **)
-          options.ask_missing_mandatory = true
-          apps = @wizard.identify_plugins_for_url(url: url, plugin_name: plugin_name).freeze
-          @wizard.find(apps, preset_name: preset_name)
-        end
-
-        def action_initdemo
+        def action_initdemo(**)
           cp = presets.config_presets
           if cp.key?(DEMO_PRESET)
             Log.log.warn { "Demo server preset already present: #{DEMO_PRESET}" }
@@ -516,55 +563,79 @@ module Aspera
           Result::Status.new('Done')
         end
 
-        def action_commands
-          commands = Plugins::Factory.instance.plugin_list.flat_map do |name|
-            plugin_class = Plugins::Factory.instance.plugin_class(name)
-            reg = plugin_class.command_registry
-            reg.all_paths.reject { |path| reg.children_of(path).any? }.map do |path|
-              spec = reg[path]
-              # Build syntax by interleaving each path segment with the arguments declared on that node
-              tokens = [name.to_s]
-              path.each_with_index do |seg, i|
-                tokens << seg.to_s
-                node_args = reg[path[0, i + 1]]&.arguments.to_a
-                node_args.each do |a|
-                  token = a.allowed ? a.allowed.join('|') : a.name.to_s
-                  token += '...' if a.multiple
-                  tokens << (a.mandatory ? "<#{token}>" : "[<#{token}>]")
-                end
+        def action_commands(plugin_name: nil, command_path: nil, **)
+          plugin_names = Plugins::Factory.instance.plugin_list
+          unless plugin_name.nil?
+            Aspera.assert_values(plugin_name.to_sym, plugin_names, type: Cli::BadArgument)
+            plugin_names = [plugin_name.to_sym]
+          end
+          words = Array(command_path).map(&:to_sym)
+          Aspera.assert(words.empty? || plugin_names.length.eql?(1), type: Cli::BadArgument) { 'command path requires a plugin name' }
+          expand_mounts = options.get_option(:expand_mounts)
+          commands = plugin_names.flat_map do |name|
+            reg = Plugins::Factory.instance.plugin_class(name).command_registry
+            prefix = listed_command_path(name, reg, words)
+            paths = prefix.empty? || reg.children_of(prefix).any? ? reg.leaf_paths(prefix, expand_mounts: expand_mounts) : [prefix]
+            paths.map do |path|
+              mount = expand_mounts ? nil : reg.mount_at(path)
+              description = reg[path]&.description.to_s
+              if mount
+                target = mount.plugin.name.split('::').last.downcase
+                description = "#{description} (see: #{command_syntax(target, mount.registry, mount.at)})"
               end
-              syntax = tokens.join(' ')
               {
-                syntax:      syntax,
-                description: spec&.description.to_s
+                syntax:      command_syntax(name, reg, path) + (mount ? ' <command...>' : ''),
+                description: description
               }
             end
           end
           Result::ObjectList.new(commands, fields: %w[syntax description])
         end
 
+        # Command path to list, from words that may include positional arguments, as on a command line.
+        # e.g. `faspex5 packages receive ALL` lists `faspex5 packages receive`.
+        # @param name  [Symbol]          plugin name
+        # @param reg   [CommandRegistry] registry of plugin
+        # @param words [Array<Symbol>]   sub-commands (or aliases), possibly mixed with their arguments
+        # @return [Array<Symbol>] command path
+        # @raise [Cli::BadArgument] if a word is neither a sub-command nor an expected argument
+        def listed_command_path(name, reg, words)
+          path, unknown = reg.command_path(words)
+          raise Cli::BadArgument, Parser.multi_choice_assert_msg("no such command: #{[name, *path, unknown].join(' ')}", reg.children_of(path).keys) unless unknown.nil?
+          path
+        end
+
+        # Build syntax by interleaving each path segment with the arguments declared on that node
+        # @param name [String, Symbol]       plugin name
+        # @param reg  [CommandRegistry]      registry of plugin
+        # @param path [Array<Symbol>]        command path
+        # @return [String] e.g. `node access_keys do <access_key_id> ls <path>`
+        def command_syntax(name, reg, path)
+          tokens = [name.to_s]
+          path.each_index do |i|
+            tokens << path[i].to_s
+            reg.arguments_at(path[0, i + 1]).each { |a| tokens << a.syntax }
+          end
+          tokens.join(' ')
+        end
+
         def action_options(plugin_name:, **)
           # Instantiate the plugin so that it registers all its options in context.options
           Plugins::Factory.instance.create(plugin_name.to_sym, context: context)
           rows = context.options.declared_options.map do |sym, opt|
             row = {
-              option:      "--#{sym.to_s.tr('_', '-')}",
-              description: opt.description.to_s
+              'option'      => "--#{sym.to_s.tr('_', '-')}",
+              'description' => opt.description.to_s
             }
-            row[:allowed]    = opt.values.join('|') if opt.values&.any?
-            row[:deprecated] = opt.deprecation      if opt.deprecation
+            row['allowed']     = opt.allowed_info unless opt.allowed_info.nil?
+            row['deprecated']  = opt.deprecation.last if opt.deprecation
+            row['replacement'] = opt.deprecation.message if opt.deprecation
             row
           end
-          Result::ObjectList.new(rows, fields: %w[option description allowed deprecated])
-        end
-
-        def action_test_throw(exception_class_name:, exception_text:, **)
-          type = Object.const_get(exception_class_name)
-          Aspera.assert(type <= Exception) { "#{type} is not an exception: #{type.class}" }
-          raise type, exception_text
+          Result::ObjectList.new(rows, fields: %w[option description allowed deprecated replacement])
         end
 
-        def action_completion_bash(words: nil, **)
+        def action_completion_words(words: nil, **)
           if words.nil? || words.empty?
             # Level 0: propose plugin names
             Plugins::Factory.instance.plugin_list.each { |p| puts p }
@@ -582,6 +653,14 @@ module Aspera
           Process.exit(0)
         end
 
+        # Display the completion script for the given shell.
+        # Raw output, not formatted, so that it can be evaluated by the shell.
+        # @param shell [Symbol] One of `COMPLETION_SHELLS`
+        def completion_script(shell)
+          $stdout.write(File.read(File.join(COMPLETION_FOLDER, "#{Info::CMD_NAME}.#{shell}")))
+          Process.exit(0)
+        end
+
         # Folder in $HOME for application files (~/.aspera)
         ASPERA_HOME_FOLDER_NAME = '.aspera'
         # Default config file name