aspera-cli 4.26.2 → 4.27.0

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

@@ -46,15 +46,16 @@ module Aspera
           end
         end
 
+        application_name 'HSTS Node API'
+
+        SESSION_TIME_FIELDS = %i[start end].freeze
+        private_constant :SESSION_TIME_FIELDS
+
         class << self
           # directory: node, container: shares
           FOLDER_TYPES = %w[directory container].freeze
           private_constant :FOLDER_TYPES
 
-          def application_name
-            'HSTS Node API'
-          end
-
           # @return [Hash,NilClass]
           def detect(address_or_url)
             urls = if address_or_url.match?(%r{^[a-z]{1,6}://})
@@ -68,7 +69,7 @@ module Aspera
             end
             error = nil
             urls.each do |base_url|
-              next unless base_url.match?('https?://')
+              next unless base_url.match?(%r{^https?://})
               api = Rest.new(base_url: base_url)
               test_endpoint = 'ping'
               http = api.read(test_endpoint, ret: :resp)
@@ -87,20 +88,22 @@ module Aspera
             return
           end
 
+          # Called by non-Node plugins (Ats, Cos, Aoc) to declare Node options on their
+          # own options object. The DSL registry is walked so descriptions stay in one place.
           def declare_options(options)
-            return if @options_declared
-            @options_declared = true
-            @dynamic_key = nil
-            options.declare(:validator, 'Identifier of validator (optional for central)')
-            options.declare(:asperabrowserurl, 'URL for simple aspera web ui', default: 'https://asperabrowser.mybluemix.net')
-            options.declare(
-              :node_api, 'Gen4: standard_ports: Use standard FASP ports (true) or get from node API (false). cache: Set to false to force actual file system read',
-              allowed: Hash,
-              handler: {o: Api::Node, m: :api_options}
-            )
-            options.declare(:root_id, 'Gen4: File id of top folder when using access key (override AK root id)')
-            options.declare(:dynamic_key, 'Private key PEM to use for dynamic key auth', handler: {o: Api::Node, m: :use_dynamic_key})
-            SyncActions.declare_options(options)
+            return if options.option_declared?(:root_id)
+            command_registry.option_specs.each_value do |spec|
+              next if options.option_declared?(spec.name)
+              options.declare(
+                spec.name,
+                description: spec.description,
+                short:       spec.short,
+                allowed:     spec.allowed,
+                default:     spec.default,
+                handler:     spec.handler,
+                schema:      spec.schema
+              )
+            end
             options.parse_options!
           end
 
@@ -110,8 +113,17 @@ module Aspera
           end
         end
 
+        # DSL option declarations - at class level, picked up by Base#initialize via ancestor chain.
+        # Also exposed via Node.declare_options for non-Node plugins (Ats, Cos, Aoc).
+        option :validator,        description: 'Identifier of validator (optional for central)'
+        option :asperabrowserurl, description: 'URL for simple aspera web ui', default: 'https://asperabrowser.mybluemix.net'
+        option :node_api,         description: 'Gen4: standard_ports: Use standard FASP ports (true) or get from node API (false). cache: Set to false to force actual file system read',
+          allowed: Hash, handler: {o: Api::Node, m: :api_options}
+        option :root_id,          description: 'Gen4: File id of top folder when using access key (override AK root id)'
+        option :dynamic_key,      description: 'Private key PEM to use for dynamic key auth', handler: {o: Api::Node, m: :use_dynamic_key}
+
         # @param wizard  [Wizard] The wizard object
-        # @param app_url [Wizard] The wizard object
+        # @param app_url [String] Tested URL
         # @return [Hash] :preset_value, :test_args
         def wizard(wizard, app_url)
           return {
@@ -146,10 +158,7 @@ module Aspera
         # commands for : `execute_simple_common`: actions used commonly when a node is involved
         COMMON_ACTIONS = %i[access_keys].concat(BASE_ACTIONS).concat(SPECIAL_ACTIONS).freeze
 
-        # actions available in v3 in gen4
-        V3_IN_V4_ACTIONS = %i[transfer].concat(COMMON_ACTIONS).freeze
-
-        private_constant :CENTRAL_SOAP_API_TEST, :SEARCH_REMOVE_FIELDS, :BASE_ACTIONS, :SPECIAL_ACTIONS, :V3_IN_V4_ACTIONS, :COMMON_ACTIONS
+        private_constant :CENTRAL_SOAP_API_TEST, :SEARCH_REMOVE_FIELDS, :BASE_ACTIONS, :SPECIAL_ACTIONS, :COMMON_ACTIONS
 
         # used in aoc
         NODE4_READ_ACTIONS = %i[bearer_token_node node_info browse find].freeze
@@ -196,9 +205,9 @@ module Aspera
         end
 
         # Gen3 API
-        def browse_gen3
-          folders_to_process = options.get_next_argument('path', validation: String)
-          folders_to_process = @node_path_prefix.add_to_path(folders_to_process) unless @node_path_prefix.nil?
+        # @param path [String] starting path
+        def browse_gen3(path)
+          folders_to_process = @node_path_prefix.nil? ? path : @node_path_prefix.add_to_path(path)
           folders_to_process = [folders_to_process]
           query = options.get_option(:query) || {}
           # special parameter: max number of entries in result
@@ -211,7 +220,7 @@ module Aspera
           single_call = query.key?('skip')
           # API default is 100, so use 1000 for default
           query['count'] ||= 1000
-          raise Cli::BadArgument, 'options `recursive` and `skip` cannot be used together' if recursive && single_call
+          Aspera.assert(!(recursive && single_call), type: Cli::BadArgument){'options `recursive` and `skip` cannot be used together'}
           all_items = []
           until folders_to_process.empty?
             path = folders_to_process.shift
@@ -252,9 +261,9 @@ module Aspera
         end
 
         # Create async transfer spec request from direction and folders
-        # @param sync_direction one of push pull bidi
-        # @param local_path local folder to sync
-        # @param remote_path remote folder to sync
+        # @param sync_direction [Symbol] one of push pull bidi
+        # @param local_path     [String] local folder to sync
+        # @param remote_path    [String] remote folder to sync
         def sync_spec_request(sync_direction, local_path, remote_path)
           case sync_direction
           when :push then {
@@ -282,382 +291,28 @@ module Aspera
           end
         end
 
-        # Commands based on Gen3 API for file and folder
-        def execute_command_gen3(command)
-          case command
-          when :delete
-            # TODO: add query for recursive
-            paths_to_delete = options.get_next_argument('file list', multiple: true)
-            @node_path_prefix&.add_to_paths!(paths_to_delete)
-            resp = @api_node.create('files/delete', {paths: paths_to_delete.map{ |i| {'path' => i.start_with?('/') ? i : "/#{i}"}}})
-            return cli_result_from_paths_response(resp, 'file deleted')
-          when :search
-            search_root = options.get_next_argument('search root', validation: String)
-            search_root = @node_path_prefix.add_to_path(search_root) unless @node_path_prefix.nil?
-            parameters = {'path' => search_root}
-            other_options = options.get_option(:query)
-            parameters.merge!(other_options) unless other_options.nil?
-            resp = @api_node.create('files/search', parameters)
-            return Result::Empty.new if resp['items'].empty?
-            fields = resp['items'].first.keys.reject{ |i| SEARCH_REMOVE_FIELDS.include?(i)}
-            formatter.display_item_count(resp['item_count'], resp['total_count'])
-            formatter.display_status("params: #{resp['parameters'].keys.map{ |k| "#{k}:#{resp['parameters'][k]}"}.join(',')}")
-            @node_path_prefix&.remove_in_object_list!(resp['items'])
-            return Result::ObjectList.new(resp['items'], fields: fields)
-          when :space
-            path_list = options.get_next_argument('folder path or ext.val. list', multiple: true)
-            @node_path_prefix&.add_to_paths!(path_list)
-            resp = @api_node.create('space', {'paths' => path_list.map{ |i| {path: i}}})
-            @node_path_prefix&.remove_in_object_list!(resp['paths'])
-            return Result::ObjectList.new(resp['paths'])
-          when :mkdir
-            path_list = options.get_next_argument('folder path or ext.val. list', multiple: true)
-            @node_path_prefix&.add_to_paths!(path_list)
-            resp = @api_node.create('files/create', {'paths' => path_list.map{ |i| {type: :directory, path: i}}})
-            return cli_result_from_paths_response(resp, 'folder created')
-          when :mklink
-            target = options.get_next_argument('target', validation: String)
-            target = @node_path_prefix.add_to_path(target) unless @node_path_prefix.nil?
-            one_path = options.get_next_argument('link path', validation: String)
-            one_path = @node_path_prefix.add_to_path(one_path) unless @node_path_prefix.nil?
-            resp = @api_node.create('files/create', {'paths' => [{type: :symbolic_link, path: one_path, target: {path: target}}]})
-            return cli_result_from_paths_response(resp, 'link created')
-          when :mkfile
-            one_path = options.get_next_argument('file path', validation: String)
-            one_path = @node_path_prefix.add_to_path(one_path) unless @node_path_prefix.nil?
-            contents64 = Base64.strict_encode64(options.get_next_argument('contents'))
-            resp = @api_node.create('files/create', {'paths' => [{type: :file, path: one_path, contents: contents64}]})
-            return cli_result_from_paths_response(resp, 'file created')
-          when :rename
-            # TODO: multiple ?
-            path_base = options.get_next_argument('path_base', validation: String)
-            path_base = @node_path_prefix.add_to_path(path_base) unless @node_path_prefix.nil?
-            path_src = options.get_next_argument('path_src', validation: String)
-            path_src = @node_path_prefix.add_to_path(path_src) unless @node_path_prefix.nil?
-            path_dst = options.get_next_argument('path_dst', validation: String)
-            path_dst = @node_path_prefix.add_to_path(path_dst) unless @node_path_prefix.nil?
-            resp = @api_node.create('files/rename', {'paths' => [{'path' => path_base, 'source' => path_src, 'destination' => path_dst}]})
-            return cli_result_from_paths_response(resp, 'entry moved')
-          when :browse
-            return browse_gen3
-          when :sync
-            return execute_sync_action do |sync_direction, local_path, remote_path|
-              # Gen3 API
-              # empty transfer spec for authorization request
-              request_transfer_spec = sync_spec_request(sync_direction, local_path, remote_path)
-              # add fixed parameters if any (for COS)
-              @api_node.add_tspec_info(request_transfer_spec) if @api_node.respond_to?(:add_tspec_info)
-              # prepare payload for single request
-              setup_payload = {transfer_requests: [{transfer_request: request_transfer_spec}]}
-              # only one request, so only one answer
-              transfer_spec = @api_node.create('files/sync_setup', setup_payload)['transfer_specs'].first['transfer_spec']
-              # API returns null tag... but async does not like it
-              transfer_spec.delete_if{ |_k, v| v.nil?}
-              # delete this part, as the returned value contains only destination, and not sources
-              # transfer_spec.delete('paths') if command.eql?(:upload)
-              Log.dump(:ts, transfer_spec)
-              transfer_spec
-            end
-          when :upload, :download
-            # empty transfer spec for authorization request
-            request_transfer_spec = {}
-            # set requested paths depending on direction
-            request_transfer_spec[:paths] = if command.eql?(:download)
-              transfer.ts_source_paths
-            else
-              [{destination: transfer.destination_folder(Transfer::Spec::DIRECTION_SEND)}]
-            end
-            # add fixed parameters if any (for COS)
-            @api_node.add_tspec_info(request_transfer_spec) if @api_node.respond_to?(:add_tspec_info)
-            Api::Node.add_public_key(request_transfer_spec)
-            # prepare payload for single request
-            setup_payload = {transfer_requests: [{transfer_request: request_transfer_spec}]}
-            # only one request, so only one answer
-            transfer_spec = @api_node.create("files/#{command}_setup", setup_payload)['transfer_specs'].first['transfer_spec']
-            Api::Node.add_private_key(transfer_spec)
-            # delete this part, as the returned value contains only destination, and not sources
-            transfer_spec.delete('paths') if command.eql?(:upload)
-            return Runner.result_transfer(transfer.start(transfer_spec))
-          when :cat
-            remote_path = options.get_next_argument('remote path', validation: String)
-            remote_path = @node_path_prefix.add_to_path(remote_path) unless @node_path_prefix.nil?
-            File.basename(remote_path)
-            http = @api_node.read("files/#{URI.encode_www_form_component(remote_path)}/contents", ret: :resp)
-            return Result::Text.new(http.body)
-          when :transport
-            return Result::SingleObject.new(@api_node.transport_params)
-          when :spec
-            return Result::SingleObject.new(@api_node.base_spec, fields: Formatter.all_but(Transfer::Spec::SPECIFIC))
-          end
-          Aspera.error_unreachable_line
-        end
-
-        # common API to node and Shares
-        def execute_simple_common(command)
-          case command
-          when *COMMANDS_GEN3
-            execute_command_gen3(command)
-          when :access_keys
-            ak_command = options.get_next_command(%i[do set_bearer_key].concat(Operations::ALL))
-            case ak_command
-            when *Operations::ALL
-              return entity_execute(
-                api: @api_node,
-                entity: 'access_keys',
-                command: ak_command
-              ) do |field, value|
-                       raise BadArgument, 'only selector: %id:self' unless field.eql?('id') && value.eql?('self')
-                       @api_node.read('access_keys/self')['id']
-                     end
-            when :do
-              access_key_id = options.get_next_argument('access key id')
-              root_file_id = options.get_option(:root_id)
-              if root_file_id.nil?
-                ak_info = @api_node.read("access_keys/#{access_key_id}")
-                ak_secret = config.lookup_secret(url: @api_node.base_url, username: ak_info['id'])
-                # change API credentials if different access key
-                if !access_key_id.eql?('self')
-                  Aspera.assert(ak_secret, type: Cli::MissingArgument){"Please provide secret for #{ak_info['id']} using option: secret or by setting a preset for #{ak_info['id']}@#{@api_node.base_url}."}
-                  @api_node.auth_params[:username] = ak_info['id']
-                  @api_node.auth_params[:password] = ak_secret
-                end
-                root_file_id = ak_info['root_file_id']
-              end
-              command_repo = options.get_next_command(COMMANDS_GEN4)
-              return execute_command_gen4(command_repo, root_file_id)
-            when :set_bearer_key
-              access_key_id = options.get_next_argument('access key id')
-              access_key_id = @api_node.read('access_keys/self')['id'] if access_key_id.eql?('self')
-              bearer_key_pem = options.get_next_argument('public or private RSA key PEM value', validation: String)
-              key = OpenSSL::PKey.read(bearer_key_pem)
-              key = key.public_key if key.private?
-              bearer_key_pem = key.to_pem
-              @api_node.update("access_keys/#{access_key_id}", {token_verification_key: bearer_key_pem})
-              return Result::Status.new('public key updated')
-            end
-          when :health
-            nagios = Nagios.new
-            begin
-              info = @api_node.read('info')
-              nagios.add_ok('node api', 'accessible')
-              nagios.check_time_offset(info['current_time'], 'node api')
-              nagios.check_product_version('node api', 'entsrv', info['version'])
-            rescue StandardError => e
-              nagios.add_critical('node api', e.to_s)
-            end
-            begin
-              @api_node.call(
-                operation:    'POST',
-                subpath:      'services/soap/Transfer-201210',
-                content_type: Mime::TEXT,
-                body:         CENTRAL_SOAP_API_TEST,
-                headers:      {'Content-Type' => 'text/xml;charset=UTF-8', 'SOAPAction' => 'FASPSessionNET-200911#GetSessionInfo'},
-                ret:          :resp
-              ).body
-              nagios.add_ok('central', 'accessible by node')
-            rescue StandardError => e
-              nagios.add_critical('central', e.to_s)
-            end
-            Result::ObjectList.new(nagios.status_list)
-          when :events
-            events = @api_node.read('events', query_read_delete)
-            return Result::ObjectList.new(events, fields: ->(f){!f.start_with?('data')})
-          when :info
-            nd_info = @api_node.read('info')
-            return Result::SingleObject.new(nd_info)
-          when :slash
-            nd_info = @api_node.read('')
-            return Result::SingleObject.new(nd_info)
-          when :license
-            # requires: asnodeadmin -mu <node user> --acl-add=internal --internal
-            return Result::SingleObject.new(@api_node.read('license'))
-          when :api_details
-            return Result::SingleObject.new({base_url: @api_node.base_url}.merge(@api_node.params))
+        # Resolve a NodeFileId from a path argument.
+        # Supports %id:<file_id> syntax (returns NodeFileId for that id) or a plain path.
+        # @param top_file_id [String] root file id for path resolution
+        # @param path        [String] plain path or %id:<file_id> selector
+        def apifid_from_path(top_file_id, path)
+          if (m = Parser.percent_selector(path))
+            Aspera.assert_values(m[:field], ['id'], type: BadArgument){'file id'}
+            val = m[:value]
+            return Api::NodeFileId.new(@api_node, val.nil? || val.empty? ? top_file_id : val)
           end
+          @api_node.resolve_api_fid(top_file_id, path)
         end
 
-        # Allows to specify a file by its path or by its id on the node in command line
-        # @return [NodeFileId] api and main file id for given path or id in next argument
+        # Legacy helper: resolve a NodeFileId by reading path from the CLI argument stream.
+        # Used only by setup_access_key_do_permission and action_access_keys_do_permission
+        # (intermediate nodes whose path cannot yet be injected via execute_leaf).
         def apifid_from_next_arg(top_file_id)
           file_path = options.instance_identifier(description: 'path or %id:<id> or %id:') do |attribute, value|
-            raise BadArgument, 'Only selection "id" is supported (file id)' unless attribute.eql?('id')
-            # Directly return result for method
-            return Api::NodeFileId.new(@api_node, value)
-          end
-          # There was no selector, so it is a path
-          return @api_node.resolve_api_fid(top_file_id, file_path)
-        end
-
-        def execute_command_gen4(command_repo, top_file_id)
-          override_file_id = options.get_option(:root_id)
-          top_file_id = override_file_id unless override_file_id.nil?
-          raise Cli::Error, 'Specify root file id with option root_id' if top_file_id.nil?
-          case command_repo
-          when :v3
-            # NOTE: other common actions are unauthorized with user scope
-            command_legacy = options.get_next_command(V3_IN_V4_ACTIONS)
-            # TODO: shall we support all methods here ? what if there is a link ?
-            apifid = @api_node.resolve_api_fid(top_file_id, '')
-            return Node.new(context: context, api: apifid.node_api).execute_action(command_legacy)
-          when :node_info, :bearer_token_node
-            apifid = apifid_from_next_arg(top_file_id)
-            result = {
-              url:     apifid.node_api.base_url,
-              root_id: apifid.file_id
-            }
-            case apifid.node_api.auth_params[:type]
-            when :basic
-              result[:username] = apifid.node_api.auth_params[:username]
-              result[:password] = apifid.node_api.auth_params[:password]
-            when :oauth2
-              result[:username] = apifid.node_api.params[:headers][Api::Node::HEADER_X_ASPERA_ACCESS_KEY]
-              result[:password] = apifid.node_api.oauth.authorization
-            else Aspera.error_unexpected_value(apifid.node_api.auth_params[:type]){'Node API Auth type'}
-            end
-            return Result::SingleObject.new(result) if command_repo.eql?(:node_info)
-            Log.dump(:result, result)
-            raise BadArgument, "Cannot get bearer token if authenticating with secret (#{apifid.node_api.auth_params[:type]})" unless apifid.node_api.auth_params[:type].eql?(:oauth2)
-            Aspera.assert(OAuth::Factory.bearer_auth?(result[:password]), 'Not using bearer token auth')
-            return Result::Text.new(result[:password])
-          when :browse
-            apifid = apifid_from_next_arg(top_file_id)
-            file_info = apifid.node_api.read("files/#{apifid.file_id}", headers: Api::Node.add_cache_control)
-            # a single file
-            return Result::ObjectList.new([file_info], fields: GEN4_LS_FIELDS) unless file_info['type'].eql?('folder')
-            return Result::ObjectList.new(apifid.node_api.list_files(apifid.file_id, query: query_read_delete), fields: GEN4_LS_FIELDS)
-          when :find
-            apifid = apifid_from_next_arg(top_file_id)
-            find_lambda = Api::Node.file_matcher_from_argument(options)
-            return Result::ObjectList.new(@api_node.find_files(apifid.file_id, find_lambda), fields: ['path'])
-          when :mkdir, :mklink, :mkfile
-            containing_folder_path, new_item = Api::Node.split_folder(options.get_next_argument('path'))
-            apifid = @api_node.resolve_api_fid(top_file_id, containing_folder_path, true)
-            query = options.get_option(:query)
-            check_exists = true
-            payload = {name: new_item}
-            if query
-              check_exists = !query.delete('check').eql?(false)
-              target = query.delete('target')
-              if target
-                target_apifid = @api_node.resolve_api_fid(top_file_id, target, true)
-                payload[:target_id] = target_apifid.file_id
-              end
-              payload.merge!(query.symbolize_keys)
-            end
-            if check_exists
-              folder_content = apifid.node_api.read("files/#{apifid.file_id}/files")
-              link_name = ".#{new_item}.asp-lnk"
-              found = folder_content.find{ |i| i['name'].eql?(new_item) || i['name'].eql?(link_name)}
-              raise "A #{found['type']} already exists with name #{new_item}" if found
-            end
-            case command_repo
-            when :mkdir
-              payload[:type] = :folder
-            when :mklink
-              payload[:type] = :link
-              Aspera.assert(payload[:target_id], 'Missing target_id')
-              Aspera.assert(payload[:target_node_id], 'Missing target_node_id')
-            when :mkfile
-              payload[:type] = :file
-              payload[:contents] = Base64.strict_encode64(options.get_next_argument('contents'))
-            end
-            result = apifid.node_api.create("files/#{apifid.file_id}/files", payload)
-            return Result::SingleObject.new(result)
-          when :rename
-            file_path = options.get_next_argument('source path')
-            apifid = @api_node.resolve_api_fid(top_file_id, file_path)
-            newname = options.get_next_argument('new name')
-            result = apifid.node_api.update("files/#{apifid.file_id}", {name: newname})
-            return Result::Status.new("renamed to #{newname}")
-          when :delete
-            return do_bulk_operation(command: command_repo, descr: 'path', values: String, id_result: 'path') do |l_path|
-              apifid = if (m = Manager.percent_selector(l_path))
-                Aspera.assert_values(m[:field], ['id'], type: BadIdentifier)
-                Api::NodeFileId.new(@api_node, m[:value])
-              else
-                @api_node.resolve_api_fid(top_file_id, l_path)
-              end
-              result = apifid.node_api.delete("files/#{apifid.file_id}")
-              {'path' => l_path}
-            end
-          when :sync
-            return execute_sync_action do |sync_direction, _local_path, remote_path|
-              # Gen4 API
-              Aspera.assert_values(sync_direction, %i[push pull bidi])
-              ts_direction = case sync_direction
-              when :push, :bidi then Transfer::Spec::DIRECTION_SEND
-              when :pull then Transfer::Spec::DIRECTION_RECEIVE
-              else Aspera.error_unreachable_line
-              end
-              # remote is specified by option: `to_folder`
-              apifid = @api_node.resolve_api_fid(top_file_id, remote_path)
-              apifid.node_api.transfer_spec_gen4(apifid.file_id, ts_direction)
-            end
-          when :upload
-            apifid = @api_node.resolve_api_fid(top_file_id, transfer.destination_folder(Transfer::Spec::DIRECTION_SEND), true)
-            return Runner.result_transfer(transfer.start(apifid.node_api.transfer_spec_gen4(apifid.file_id, Transfer::Spec::DIRECTION_SEND)))
-          when :download
-            apifid, source_paths = @api_node.resolve_api_fid_paths(top_file_id, transfer.ts_source_paths)
-            return Runner.result_transfer(transfer.start(apifid.node_api.transfer_spec_gen4(apifid.file_id, Transfer::Spec::DIRECTION_RECEIVE, {'paths'=>source_paths})))
-          when :cat
-            apifid = apifid_from_next_arg(top_file_id)
-            http = apifid.node_api.read("files/#{apifid.file_id}/content", ret: :resp)
-            return Result::Text.new(http.body)
-          when :show
-            apifid = apifid_from_next_arg(top_file_id)
-            items = apifid.node_api.read("files/#{apifid.file_id}")
-            return Result::SingleObject.new(items)
-          when :modify
-            apifid = apifid_from_next_arg(top_file_id)
-            update_param = options.get_next_argument('update data', validation: Hash)
-            apifid.node_api.update("files/#{apifid.file_id}", update_param)
-            return Result::Status.new('Done')
-          when :thumbnail
-            apifid = apifid_from_next_arg(top_file_id)
-            http = apifid.node_api.read("files/#{apifid.file_id}/preview", headers: {'Accept' => 'image/png'}, ret: :resp)
-            return Result::Image.new(http.body)
-          when :permission
-            apifid = apifid_from_next_arg(top_file_id)
-            command_perm = options.get_next_command(%i[list show create delete modify])
-            case command_perm
-            when :modify
-              apifid.node_api.update("permissions/#{options.instance_identifier}", value_create_modify(command: 'permission modify'))
-              return Result::Status.new('Updated')
-            when :list
-              list_query = query_read_delete(default: Rest.php_style({'include' => %w[access_level permission_count]}))
-              # Specify file to get permissions for unless not specified (then, get all permissions)
-              list_query['file_id'] = apifid.file_id unless apifid.file_id.to_s.empty?
-              list_query['inherited'] = false if list_query.key?('file_id') && !list_query.key?('inherited')
-              items = apifid.node_api.read_with_pages('permissions', list_query)
-              return Result::ObjectList.new(items)
-            when :show
-              return Result::SingleObject.new(apifid.node_api.read("permissions/#{options.instance_identifier}"))
-            when :delete
-              return do_bulk_operation(command: command_perm, values: :identifier) do |one_id|
-                apifid.node_api.delete("permissions/#{one_id}")
-                # notify application of deletion
-                the_app = apifid.node_api.app_info
-                the_app&.api&.permissions_send_event(event_data: {}, app_info: the_app, types: ['permission.deleted'])
-                {'id' => one_id}
-              end
-            when :create
-              create_param = options.get_next_argument('creation data', validation: Hash)
-              raise Cli::BadArgument, 'no file_id' if create_param.key?('file_id')
-              create_param['file_id'] = apifid.file_id
-              create_param['access_levels'] = Api::Node::ACCESS_LEVELS unless create_param.key?('access_levels')
-              # add application specific tags (AoC)
-              the_app = apifid.node_api.app_info
-              the_app&.api&.permissions_set_create_params(perm_data: create_param, app_info: the_app)
-              # create permission
-              created_data = apifid.node_api.create('permissions', create_param)
-              # notify application of creation
-              the_app&.api&.permissions_send_event(event_data: created_data, app_info: the_app)
-              return Result::SingleObject.new(created_data)
-            else Aspera.error_unreachable_line
-            end
-          else Aspera.error_unreachable_line
+            Aspera.assert_values(attribute, ['id'], type: BadArgument){'file id'}
+            return Api::NodeFileId.new(@api_node, value.nil? || value.empty? ? top_file_id : value)
           end
-          Aspera.error_unreachable_line
+          @api_node.resolve_api_fid(top_file_id, file_path)
         end
 
         # Search /async by name
@@ -666,7 +321,7 @@ module Aspera
         # @return [Integer] id of the sync
         # @raise [Cli::BadArgument] if no such sync, or not by name
         def async_lookup(field, value)
-          raise Cli::BadArgument, "Only search by name is supported (#{field})" unless field.eql?('name')
+          Aspera.assert_values(field, ['name'], type: Cli::BadArgument){'search field'}
           async_ids = @api_node.read('async/list')['sync_ids']
           summaries = @api_node.create('async/summary', {'syncs' => async_ids})['sync_summaries']
           selected = summaries.find{ |s| s['name'].eql?(value)}
@@ -674,82 +329,13 @@ module Aspera
           return selected['snid']
         end
 
-        # Node API: /async (stats only)
-        def execute_async
-          command = options.get_next_command(%i[list delete files show counters bandwidth])
-          unless command.eql?(:list)
-            async_id = options.instance_identifier{ |field, value| async_lookup(field, value)}
-            if async_id.eql?(SpecialValues::ALL)
-              raise Cli::BadArgument, 'ALL only for show and delete' unless %i[show delete].include?(command)
-              async_ids = @api_node.read('async/list')['sync_ids']
-            else
-              Integer(async_id) # must be integer
-              async_ids = [async_id]
-            end
-            post_data = {'syncs' => async_ids}
-          end
-          case command
-          when :list
-            resp = @api_node.read('async/list')['sync_ids']
-            return Result::ValueList.new(resp)
-          when :show
-            resp = @api_node.create('async/summary', post_data)['sync_summaries']
-            return Result::Empty.new if resp.empty?
-            return Result::ObjectList.new(resp, fields: %w[snid name local_dir remote_dir]) if async_id.eql?(SpecialValues::ALL)
-            return Result::SingleObject.new(resp.first)
-          when :delete
-            resp = @api_node.create('async/delete', post_data)
-            return Result::SingleObject.new(resp)
-          when :bandwidth
-            post_data['seconds'] = 100 # TODO: as parameter with --query
-            resp = @api_node.create('async/bandwidth', post_data)
-            data = resp['bandwidth_data']
-            return Result::Empty.new if data.empty?
-            data = data.first[async_id]['data']
-            return Result::ObjectList.new(data)
-          when :files
-            # count int
-            # filename str
-            # skip int
-            # status int
-            filter = options.get_option(:query)
-            post_data.merge!(filter) unless filter.nil?
-            resp = @api_node.create('async/files', post_data)
-            data = resp['sync_files']
-            data = data.first[async_id] unless data.empty?
-            iteration_data = []
-            skip_ids_persistency = nil
-            if options.get_option(:once_only, mandatory: true)
-              skip_ids_persistency = PersistencyActionOnce.new(
-                manager: persistency,
-                data:    iteration_data,
-                id:      IdGenerator.from_list(
-                  'sync_files',
-                  options.get_option(:url, mandatory: true),
-                  options.get_option(:username, mandatory: true),
-                  async_id
-                )
-              )
-              data.select!{ |l| l['fnid'].to_i > iteration_data.first} unless iteration_data.first.nil?
-              iteration_data[0] = data.last['fnid'].to_i unless data.empty?
-            end
-            return Result::Empty.new if data.empty?
-            skip_ids_persistency&.save
-            return Result::ObjectList.new(data)
-          when :counters
-            resp = @api_node.create('async/counters', post_data)['sync_counters'].first[async_id].last
-            return Result::Empty.new if resp.nil?
-            return Result::SingleObject.new(resp)
-          end
-        end
-
         # Search /asyncs by name
         # @param field [String] name of the field to search
         # @param value [String] value of the field to search
         # @return [Integer] id of the sync
         # @raise [Cli::BadArgument] if no such sync, or not by name
         def ssync_lookup(field, value)
-          raise Cli::BadArgument, "Only search by name is supported (#{field})" unless field.eql?('name')
+          Aspera.assert_values(field, ['name'], type: Cli::BadArgument){'search field'}
           @api_node.read('asyncs')['ids'].each do |id|
             sync_info = @api_node.read("asyncs/#{id}")['configuration']
             # name is unique, so we can return
@@ -758,355 +344,973 @@ module Aspera
           raise Cli::BadIdentifier.new('ssync', value, field: field)
         end
 
-        WATCH_FOLDER_MUL = %i[create list].freeze
-        WATCH_FOLDER_SING = %i[show modify delete state].freeze
-        private_constant :WATCH_FOLDER_MUL, :WATCH_FOLDER_SING
+        # --- DSL command declarations ---
+
+        # Gen3 leaf commands
+        command :search,      description: 'Search for files',
+          arguments: [{name: :search_root, type: String}]
+        command :space,       description: 'Show space information',
+          arguments: [{name: :path_list, multiple: true}]
+        command :mkdir,       description: 'Create a folder (Gen3)',
+          arguments: [{name: :path_list, multiple: true}]
+        command :mklink,      description: 'Create a symbolic link (Gen3)',
+          arguments: [{name: :target, type: String}, {name: :link_path, type: String}]
+        command :mkfile,      description: 'Create a file (Gen3)',
+          arguments: [{name: :file_path, type: String}, {name: :contents, mandatory: false, default: nil}]
+        command :rename,      description: 'Rename a file or folder (Gen3)',
+          arguments: [{name: :path_base, type: String}, {name: :path_src, type: String}, {name: :path_dst, type: String}]
+        command :delete,      description: 'Delete files or folders (Gen3)',
+          arguments: [{name: :paths, multiple: true}]
+        command :browse,      description: 'Browse files (Gen3)',
+          arguments: [{name: :path, type: String}],
+          action: ->(path:, **){browse_gen3(path)}
+        command :upload,      description: 'Upload files (Gen3)',   transfer_paths: :send
+        command :download,    description: 'Download files (Gen3)', transfer_paths: :receive
+        command :cat,         description: 'Show file contents (Gen3)',
+          arguments: [{name: :remote_path, type: String}]
+        command :sync,        description: 'Synchronize folders (Gen3)'
+        commands_under(:sync) do
+          Sync::Operations::DIRECTIONS.each do |dir|
+            command(dir, description: "#{dir.capitalize}-sync (Gen3)", transfer_paths: :send)
+          end
+          command :admin, description: 'Manage sync database (admin operations)'
+          SyncActions.register_sync_admin_commands(self, %i[sync admin])
+        end
+        command :transport,   description: 'Show transport parameters',
+          action: ->{Result::SingleObject.new(@api_node.transport_params)}
+        command :spec,        description: 'Show transfer spec base',
+          action: ->{Result::SingleObject.new(@api_node.base_spec, fields: Formatter.all_but(Transfer::Spec::SPECIFIC))}
+        # Other common leaf commands
+        command :api_details, description: 'Show API details',
+          action: ->{Result::SingleObject.new({base_url: @api_node.base_url}.merge(@api_node.params))}
+        command :health,      description: 'Check node health'
+        command :events,      description: 'List events',
+          action: ->{Result::ObjectList.new(@api_node.read('events', query_read_delete), fields: ->(f){!f.start_with?('data')})}
+        command :info,        description: 'Show node info',
+          action: ->{Result::SingleObject.new(@api_node.read('info'))}
+        command :slash,       description: 'Show root info',
+          action: ->{Result::SingleObject.new(@api_node.read(''))}
+        command :license,     description: 'Show license',
+          action: ->{Result::SingleObject.new(@api_node.read('license'))}
+        # access_keys sub-tree
+        command :access_keys, description: 'Manage access keys'
+        commands_under(:access_keys) do
+          command :do, description: 'Execute Gen4 command via access key',
+            arguments: [{name: :access_key_id, type: :identifier}],
+            setup: :setup_access_key_do
+          command :set_bearer_key, description: 'Set bearer key on access key',
+            arguments: [{name: :access_key_id}, {name: :bearer_key_pem, type: String}]
+          Operations::ALL.each{ |op| command(op, description: "#{op.capitalize} access key(s)")}
+        end
+
+        # Commands requiring a single path argument (Gen4)
+        COMMANDS_GEN4_SINGLE_PATH = %i[mkdir mklink browse cat show find thumbnail bearer_token_node node_info].freeze
+        private_constant :COMMANDS_GEN4_SINGLE_PATH
 
-        def watch_folder_action
-          res_class_path = 'v3/watchfolders'
-          command = options.get_next_command(WATCH_FOLDER_MUL + WATCH_FOLDER_SING)
-          if WATCH_FOLDER_SING.include?(command)
-            one_res_id = options.instance_identifier
-            one_res_path = "#{res_class_path}/#{one_res_id}"
+        commands_under(%i[access_keys do]) do
+          COMMANDS_GEN4.each do |cmd|
+            next if cmd.eql?(:sync) # sync is an intermediate node declared below
+            kwargs = {description: "Gen4 #{cmd} command"}
+            kwargs[:setup] = :setup_access_key_do_permission if cmd.eql?(:permission)
+            kwargs[:arguments] = [{name: :source_path, type: String}, {name: :new_name, type: String}] if cmd.eql?(:rename)
+            kwargs[:arguments] = [{name: :paths, type: String, bulk: true}] if cmd.eql?(:delete)
+            kwargs[:arguments] = [{name: :path, type: String}, {name: :contents, mandatory: false, default: nil}] if cmd.eql?(:mkfile)
+            kwargs[:arguments] = [{name: :path, type: String}, {name: :update_value, type: Hash}] if cmd.eql?(:modify)
+            kwargs[:arguments] = [{name: :path, type: String}] if COMMANDS_GEN4_SINGLE_PATH.include?(cmd)
+            kwargs[:transfer_paths] = :send     if cmd.eql?(:upload)
+            kwargs[:transfer_paths] = :receive  if cmd.eql?(:download)
+            command(cmd, **kwargs)
+          end
+          command :sync, description: 'Synchronize folders (Gen4)'
+          commands_under(%i[access_keys do sync]) do
+            Sync::Operations::DIRECTIONS.each do |dir|
+              command(dir, description: "#{dir.capitalize}-sync (Gen4)", transfer_paths: :send)
+            end
+            command :admin, description: 'Manage sync database (admin operations)'
+            SyncActions.register_sync_admin_commands(self, %i[access_keys do sync admin])
           end
-          # hum, to avoid: Unable to convert 2016_09_14 configuration
+        end
+        commands_under(%i[access_keys do permission]) do
+          command :list,   description: 'List permissions on a file'
+          command :show,   description: 'Show a permission',
+            arguments: [{name: :perm_id, type: :identifier}],
+            action: ->(apifid:, perm_id:, **){Result::SingleObject.new(apifid.node_api.read("permissions/#{perm_id}"))}
+          command :create, description: 'Create a permission',
+            arguments: [{name: :data, type: Hash}]
+          command :modify, description: 'Modify a permission',
+            arguments: [{name: :perm_id, type: :identifier}, {name: :data, type: Hash}]
+          command :delete, description: 'Delete permission(s)',
+            arguments: [{name: :perm_id, bulk: true}]
+        end
+        # async (legacy /async)
+        command :async, description: 'Manage async operations (legacy /async)'
+        commands_under(:async) do
+          command :list,      description: 'List async sync IDs', action: ->{Result::ValueList.new(@api_node.read('async/list')['sync_ids'])}
+          command :show,      description: 'Show async summary',
+            arguments: [{name: :async_id, type: :identifier, lookup: :async_lookup}]
+          command :delete,    description: 'Delete async',
+            arguments: [{name: :async_id, type: :identifier, lookup: :async_lookup}]
+          command :bandwidth, description: 'Show async bandwidth',
+            arguments: [{name: :async_id, type: :identifier, lookup: :async_lookup}]
+          command :files,     description: 'List async files',
+            arguments: [{name: :async_id, type: :identifier, lookup: :async_lookup}]
+          command :counters,  description: 'Show async counters',
+            arguments: [{name: :async_id, type: :identifier, lookup: :async_lookup}]
+        end
+        # ssync (/asyncs)
+        command :ssync, description: 'Manage sync operations (/asyncs)'
+        commands_under(:ssync) do
+          command :create,    description: 'Create ssync',         action: ->{entity_execute(api: @api_node, entity: :asyncs, command: :create, items_key: 'ids'){ |f, v| ssync_lookup(f, v)}}
+          command :list,      description: 'List ssync',           action: ->{entity_execute(api: @api_node, entity: :asyncs, command: :list,   items_key: 'ids'){ |f, v| ssync_lookup(f, v)}}
+          command :show,      description: 'Show ssync',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: ->(ssync_id:, **){Result::SingleObject.new(@api_node.read("asyncs/#{ssync_id}"))}
+          command :delete,    description: 'Delete ssync',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: :action_ssync_delete
+          command :start,     description: 'Start a sync',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: :action_ssync_start
+          command :stop,      description: 'Stop a sync',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: :action_ssync_stop
+          command :bandwidth, description: 'Show sync bandwidth',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: ->(ssync_id:, **){Result::SingleObject.new(@api_node.read("asyncs/#{ssync_id}/bandwidth", options.get_option(:query) || {}))}
+          command :counters,  description: 'Show sync counters',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: ->(ssync_id:, **){Result::SingleObject.new(@api_node.read("asyncs/#{ssync_id}/counters", options.get_option(:query) || {}))}
+          command :files,     description: 'List sync files',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: ->(ssync_id:, **){Result::SingleObject.new(@api_node.read("asyncs/#{ssync_id}/files", options.get_option(:query) || {}))}
+          command :state,     description: 'Show sync state',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: ->(ssync_id:, **){Result::SingleObject.new(@api_node.read("asyncs/#{ssync_id}/state"))}
+          command :summary,   description: 'Show sync summary',
+            arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
+            action: ->(ssync_id:, **){Result::SingleObject.new(@api_node.read("asyncs/#{ssync_id}/summary"))}
+        end
+        # stream
+        command :stream, description: 'Manage stream operations'
+        commands_under(:stream) do
+          command :list,   description: 'List streams', action: ->{Result::ObjectList.new(@api_node.read('ops/transfers', query_read_delete), fields: %w[id status])}
+          command :create, description: 'Create a stream',
+            arguments: [{name: :data, type: Hash}],
+            action: ->(data:, **){Result::SingleObject.new(@api_node.create('streams', data))}
+          command :show,   description: 'Show a stream',
+            arguments: [{name: :transfer_id, type: :identifier}],
+            action: ->(transfer_id:, **){Result::SingleObject.new(@api_node.read("ops/transfers/#{transfer_id}"))}
+          command :modify, description: 'Modify a stream',
+            arguments: [{name: :transfer_id, type: :identifier}, {name: :data, type: Hash}],
+            action: ->(data:, transfer_id:, **){Result::SingleObject.new(@api_node.update("streams/#{transfer_id}", data))}
+          command :cancel, description: 'Cancel a stream',
+            arguments: [{name: :transfer_id, type: :identifier}],
+            action: ->(transfer_id:, **){Result::SingleObject.new(@api_node.cancel("streams/#{transfer_id}"))}
+        end
+        # transfer
+        command :transfer, description: 'Manage transfer operations'
+        commands_under(:transfer) do
+          command :list,              description: 'List transfers'
+          command :cancel,            description: 'Cancel a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :show,              description: 'Show a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}],
+            action: ->(transfer_id:, **){Result::SingleObject.new(@api_node.read("ops/transfers/#{transfer_id}"))}
+          command :modify,            description: 'Modify a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}, {name: :update_value, type: Hash}]
+          command :bandwidth_average, description: 'Show average bandwidth per period'
+          command :sessions,          description: 'List transfer sessions'
+        end
+        # service
+        command :service, description: 'Manage services'
+        commands_under(:service) do
+          command :list,   description: 'List services', action: ->{Result::ObjectList.new(@api_node.read('rund/services')['services'])}
+          command :create, description: 'Create a service',
+            arguments: [{name: :creation_data, type: Hash}]
+          command :delete, description: 'Delete a service',
+            arguments: [{name: :service_id, type: :identifier}]
+        end
+        # watch_folder
+        command :watch_folder, description: 'Manage watch folders', setup: :setup_watch_folder
+        commands_under(:watch_folder) do
+          command :create, description: 'Create a watch folder',
+            arguments: [{name: :data, type: Hash}],
+            action: ->(data:, **){Result::Status.new("#{@api_node.create('v3/watchfolders', data)['id']} created")}
+          command :list,   description: 'List watch folders',
+            action: ->{Result::ValueList.new(@api_node.read('v3/watchfolders', query_read_delete)['ids'])}
+          command :show,   description: 'Show a watch folder',
+            arguments: [{name: :res_id, type: :identifier}],
+            action: ->(res_id:, **){Result::SingleObject.new(@api_node.read("v3/watchfolders/#{res_id}"))}
+          command :modify, description: 'Modify a watch folder',
+            arguments: [{name: :res_id, type: :identifier}, {name: :data, type: Hash}]
+          command :delete, description: 'Delete a watch folder',
+            arguments: [{name: :res_id, type: :identifier}]
+          command :state,  description: 'Show watch folder state',
+            arguments: [{name: :res_id, type: :identifier}],
+            action: ->(res_id:, **){Result::SingleObject.new(@api_node.read("v3/watchfolders/#{res_id}/state"))}
+        end
+        # central
+        command :central, description: 'Query Central service'
+        commands_under(:central) do
+          command :session, description: 'Query sessions'
+          command :file,    description: 'Query files'
+        end
+        commands_under(%i[central session]) do
+          command :list, description: 'List sessions',
+            arguments: [{name: :request_data, type: Hash, mandatory: false, default: nil}]
+        end
+        commands_under(%i[central file]) do
+          command :list,   description: 'List file transfers',
+            arguments: [{name: :request_data, type: Hash, mandatory: false, default: nil}]
+          command :modify, description: 'Modify file transfer validation',
+            arguments: [{name: :request_data, type: Hash, mandatory: false, default: nil}]
+        end
+        # Standalone leaf commands
+        command :asperabrowser, description: 'Open Aspera browser'
+        command :basic_token,   description: 'Generate basic auth token', action: ->{Result::Text.new(Rest.basic_authorization(options.get_option(:username, mandatory: true), options.get_option(:password, mandatory: true)))}
+        command :bearer_token, description: 'Generate bearer token',
+          arguments: [{name: :private_key_pem, type: String}, {name: :user_group_id, type: Hash}]
+        command :simulator,     description: 'Start node simulator',
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
+        command :telemetry,     description: 'Report telemetry to external system',
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
+
+        # --- Handler methods (Gen3) ---
+
+        def action_delete(paths:, **)
+          # TODO: add query for recursive
+          paths_to_delete = Array(paths)
+          @node_path_prefix&.add_to_paths!(paths_to_delete)
+          resp = @api_node.create('files/delete', {paths: paths_to_delete.map{ |i| {'path' => i.start_with?('/') ? i : "/#{i}"}}})
+          cli_result_from_paths_response(resp, 'file deleted')
+        end
+
+        def action_search(search_root:, **)
+          search_root = @node_path_prefix.nil? ? search_root : @node_path_prefix.add_to_path(search_root)
+          parameters = {'path' => search_root}
+          other_options = options.get_option(:query)
+          parameters.merge!(other_options) unless other_options.nil?
+          resp = @api_node.create('files/search', parameters)
+          return Result::Empty.new if resp['items'].empty?
+          fields = resp['items'].first.keys.reject{ |i| SEARCH_REMOVE_FIELDS.include?(i)}
+          formatter.display_item_count(resp['item_count'], resp['total_count'])
+          formatter.display_status("params: #{resp['parameters'].keys.map{ |k| "#{k}:#{resp['parameters'][k]}"}.join(',')}")
+          @node_path_prefix&.remove_in_object_list!(resp['items'])
+          Result::ObjectList.new(resp['items'], fields: fields)
+        end
+
+        def action_space(path_list:, **)
+          path_list = Array(path_list)
+          @node_path_prefix&.add_to_paths!(path_list)
+          resp = @api_node.create('space', {'paths' => path_list.map{ |i| {path: i}}})
+          @node_path_prefix&.remove_in_object_list!(resp['paths'])
+          Result::ObjectList.new(resp['paths'])
+        end
+
+        def action_mkdir(path_list:, **)
+          path_list = Array(path_list)
+          @node_path_prefix&.add_to_paths!(path_list)
+          resp = @api_node.create('files/create', {'paths' => path_list.map{ |i| {type: :directory, path: i}}})
+          cli_result_from_paths_response(resp, 'folder created')
+        end
+
+        def action_mklink(target:, link_path:, **)
+          target    = @node_path_prefix.nil? ? target : @node_path_prefix.add_to_path(target)
+          one_path  = @node_path_prefix.nil? ? link_path : @node_path_prefix.add_to_path(link_path)
+          resp = @api_node.create('files/create', {'paths' => [{type: :symbolic_link, path: one_path, target: {path: target}}]})
+          cli_result_from_paths_response(resp, 'link created')
+        end
+
+        def action_mkfile(file_path:, contents:, **)
+          one_path = @node_path_prefix.nil? ? file_path : @node_path_prefix.add_to_path(file_path)
+          contents64 = contents.nil? ? '' : Base64.strict_encode64(contents)
+          resp = @api_node.create('files/create', {'paths' => [{type: :file, path: one_path, contents: contents64}]})
+          cli_result_from_paths_response(resp, 'file created')
+        end
+
+        def action_rename(path_base:, path_src:, path_dst:, **)
+          # TODO: multiple ?
+          path_base = @node_path_prefix.nil? ? path_base : @node_path_prefix.add_to_path(path_base)
+          path_src  = @node_path_prefix.nil? ? path_src  : @node_path_prefix.add_to_path(path_src)
+          path_dst  = @node_path_prefix.nil? ? path_dst  : @node_path_prefix.add_to_path(path_dst)
+          resp = @api_node.create('files/rename', {'paths' => [{'path' => path_base, 'source' => path_src, 'destination' => path_dst}]})
+          cli_result_from_paths_response(resp, 'entry moved')
+        end
+
+        # Obtains a transfer spec via the Node API for the given direction/folders.
+        def sync_gen3_block
+          lambda do |direction, local_path, remote_path|
+            request_transfer_spec = sync_spec_request(direction, local_path, remote_path)
+            @api_node.add_tspec_info(request_transfer_spec) if @api_node.respond_to?(:add_tspec_info)
+            transfer_spec = @api_node.create(
+              'files/sync_setup',
+              {transfer_requests: [{transfer_request: request_transfer_spec}]}
+            )['transfer_specs'].first['transfer_spec']
+            transfer_spec.delete_if{ |_k, v| v.nil?}
+            Log.dump(:ts, transfer_spec)
+            transfer_spec
+          end
+        end
+
+        Sync::Operations::DIRECTIONS.each do |dir|
+          define_method(:"action_sync_#{dir}"){ |**| run_sync_transfer(dir, &sync_gen3_block)}
+        end
+
+        def action_upload
+          # empty transfer spec for authorization request
+          request_transfer_spec = {}
+          request_transfer_spec[:paths] = [{destination: transfer.destination_folder(Transfer::Spec::DIRECTION_SEND)}]
+          # add fixed parameters if any (for COS)
+          @api_node.add_tspec_info(request_transfer_spec) if @api_node.respond_to?(:add_tspec_info)
+          Api::Node.add_public_key(request_transfer_spec)
+          setup_payload = {transfer_requests: [{transfer_request: request_transfer_spec}]}
+          transfer_spec = @api_node.create('files/upload_setup', setup_payload)['transfer_specs'].first['transfer_spec']
+          Api::Node.add_private_key(transfer_spec)
+          transfer_spec.delete('paths')
+          Runner.result_transfer(transfer.start(transfer_spec))
+        end
+
+        def action_download
+          # empty transfer spec for authorization request
+          request_transfer_spec = {}
+          request_transfer_spec[:paths] = transfer.ts_source_paths
+          # add fixed parameters if any (for COS)
+          @api_node.add_tspec_info(request_transfer_spec) if @api_node.respond_to?(:add_tspec_info)
+          Api::Node.add_public_key(request_transfer_spec)
+          setup_payload = {transfer_requests: [{transfer_request: request_transfer_spec}]}
+          transfer_spec = @api_node.create('files/download_setup', setup_payload)['transfer_specs'].first['transfer_spec']
+          Api::Node.add_private_key(transfer_spec)
+          Runner.result_transfer(transfer.start(transfer_spec))
+        end
+
+        def action_cat(remote_path:, **)
+          remote_path = @node_path_prefix.nil? ? remote_path : @node_path_prefix.add_to_path(remote_path)
+          http = @api_node.read("files/#{URI.encode_www_form_component(remote_path)}/contents", ret: :resp)
+          Result::Text.new(http.body)
+        end
+
+        def action_health
+          nagios = Nagios.new
+          begin
+            info = @api_node.read('info')
+            nagios.add_ok('node api', 'accessible')
+            nagios.check_time_offset(info['current_time'], 'node api')
+            nagios.check_product_version('node api', 'entsrv', info['version'])
+          rescue StandardError => e
+            nagios.add_critical('node api', e.to_s)
+          end
+          begin
+            @api_node.call(
+              operation:    'POST',
+              subpath:      'services/soap/Transfer-201210',
+              content_type: Mime::TEXT,
+              body:         CENTRAL_SOAP_API_TEST,
+              headers:      {'Content-Type' => 'text/xml;charset=UTF-8', 'SOAPAction' => 'FASPSessionNET-200911#GetSessionInfo'},
+              ret:          :resp
+            ).body
+            nagios.add_ok('central', 'accessible by node')
+          rescue StandardError => e
+            nagios.add_critical('central', e.to_s)
+          end
+          Result::ObjectList.new(nagios.status_list)
+        end
+
+        # watch_folder setup: inject required API header (avoids "Unable to convert 2016_09_14 configuration")
+        def setup_watch_folder(**)
           @api_node.params[:headers] ||= {}
           @api_node.params[:headers]['X-aspera-WF-version'] = '2017_10_23'
-          case command
-          when :create
-            resp = @api_node.create(res_class_path, value_create_modify(command: command))
-            return Result::Status.new("#{resp['id']} created")
-          when :list
-            resp = @api_node.read(res_class_path, query_read_delete)
-            return Result::ValueList.new(resp['ids'])
-          when :show
-            return Result::SingleObject.new(@api_node.read(one_res_path))
-          when :modify
-            @api_node.update(one_res_path, value_create_modify(command: 'watch_folder'))
-            return Result::Status.new("#{one_res_id} updated")
-          when :delete
-            @api_node.delete(one_res_path)
-            return Result::Status.new("#{one_res_id} deleted")
-          when :state
-            return Result::SingleObject.new(@api_node.read("#{one_res_path}/state"))
+          {}
+        end
+
+        def action_access_keys_do_permission_modify(data:, apifid:, perm_id:, **)
+          apifid.node_api.update("permissions/#{perm_id}", data)
+          Result::Status.new('Updated')
+        end
+
+        def action_watch_folder_modify(data:, res_id:, **)
+          @api_node.update("v3/watchfolders/#{res_id}", data)
+          Result::Status.new("#{res_id} updated")
+        end
+
+        def action_watch_folder_delete(res_id:, **)
+          @api_node.delete("v3/watchfolders/#{res_id}")
+          Result::Status.new("#{res_id} deleted")
+        end
+
+        # access_keys > CRUD
+        Operations::ALL.each do |op|
+          define_action_method([:access_keys, op]) do
+            entity_execute(api: @api_node, entity: 'access_keys', command: op) do |field, value|
+              Aspera.assert(field.eql?('id') && value.eql?('self'), type: BadArgument){'only selector: %id:self'}
+              @api_node.read('access_keys/self')['id']
+            end
+          end
+        end
+
+        # access_keys > do - setup: resolve access key and root file id
+        # access_key_id is resolved by execute_leaf (via instance_arg in CommandSpec)
+        # @return [Hash] context hash containing :do_root_file_id
+        def setup_access_key_do(access_key_id:, **)
+          @do_root_file_id = options.get_option(:root_id)
+          if @do_root_file_id.nil?
+            ak_info = @api_node.read("access_keys/#{access_key_id}")
+            ak_secret = context.secret_finder.lookup(url: @api_node.base_url, username: ak_info['id'])
+            if !access_key_id.eql?('self')
+              Aspera.assert(ak_secret, type: Cli::MissingArgument){"Please provide secret for #{ak_info['id']} using option: secret or by setting a preset for #{ak_info['id']}@#{@api_node.base_url}."}
+              @api_node.auth_params[:username] = ak_info['id']
+              @api_node.auth_params[:password] = ak_secret
+            end
+            @do_root_file_id = ak_info['root_file_id']
           end
+          {do_root_file_id: @do_root_file_id}
+        end
+
+        # access_keys > do > permission - setup: resolve apifid from CLI path argument
+        # (path is read from CLI here as 'permission' is an intermediate node)
+        # @return [Hash] context hash containing :apifid
+        def setup_access_key_do_permission(**)
+          {apifid: apifid_from_next_arg(@do_root_file_id)}
+        end
+
+        # access_keys > do > browse
+        def action_access_keys_do_browse(path:, do_root_file_id:, **)
+          apifid = apifid_from_path(do_root_file_id, path)
+          file_info = apifid.node_api.read("files/#{apifid.file_id}", headers: Api::Node.add_cache_control)
+          return Result::ObjectList.new([file_info], fields: GEN4_LS_FIELDS) unless file_info['type'].eql?('folder')
+          Result::ObjectList.new(apifid.node_api.list_files(apifid.file_id, query: query_read_delete), fields: GEN4_LS_FIELDS)
+        end
+
+        # access_keys > do > find
+        def action_access_keys_do_find(path:, do_root_file_id:, **)
+          apifid = apifid_from_path(do_root_file_id, path)
+          Result::ObjectList.new(@api_node.find_files(apifid.file_id, Api::Node.file_matcher_from_argument(options)), fields: ['path'])
         end
 
-        ACTIONS = %i[
-          async
-          ssync
-          stream
-          transfer
-          service
-          watch_folder
-          central
-          asperabrowser
-          basic_token
-          bearer_token
-          simulator
-          telemetry
-        ].concat(COMMON_ACTIONS).freeze
-
-        def execute_action(command = nil)
-          command ||= options.get_next_command(ACTIONS)
-          case command
-          when *COMMON_ACTIONS then return execute_simple_common(command)
-          when :async then return execute_async # former API
-          when :ssync
-            # Node API: /asyncs (newer)
-            sync_command = options.get_next_command(%i[start stop bandwidth counters files state summary] + Operations::ALL - %i[modify])
-            case sync_command
-            when *Operations::ALL
-              return entity_execute(
-                api: @api_node,
-                entity: :asyncs,
-                command: sync_command,
-                items_key: 'ids'
-              ){ |field, value| ssync_lookup(field, value)}
+        # access_keys > do > cat
+        def action_access_keys_do_cat(path:, do_root_file_id:, **)
+          apifid = apifid_from_path(do_root_file_id, path)
+          Result::Text.new(apifid.node_api.read("files/#{apifid.file_id}/content", ret: :resp).body)
+        end
+
+        # access_keys > do > show
+        def action_access_keys_do_show(path:, do_root_file_id:, **)
+          apifid = apifid_from_path(do_root_file_id, path)
+          Result::SingleObject.new(apifid.node_api.read("files/#{apifid.file_id}"))
+        end
+
+        # access_keys > do > modify
+        def action_access_keys_do_modify(path:, update_value:, do_root_file_id:, **)
+          apifid = apifid_from_path(do_root_file_id, path)
+          apifid.node_api.update("files/#{apifid.file_id}", update_value)
+          Result::Status.new('Done')
+        end
+
+        # access_keys > do > thumbnail
+        def action_access_keys_do_thumbnail(path:, do_root_file_id:, **)
+          apifid = apifid_from_path(do_root_file_id, path)
+          Result::Image.new(apifid.node_api.read("files/#{apifid.file_id}/preview", headers: {'Accept' => 'image/png'}, ret: :resp).body)
+        end
+
+        # access_keys > do > rename
+        def action_access_keys_do_rename(source_path:, new_name:, do_root_file_id:, **)
+          apifid = @api_node.resolve_api_fid(do_root_file_id, source_path)
+          apifid.node_api.update("files/#{apifid.file_id}", {name: new_name})
+          Result::Status.new("renamed to #{new_name}")
+        end
+
+        # access_keys > do > delete
+        def action_access_keys_do_delete(paths:, do_root_file_id:, **)
+          is_bulk = options.get_option(:bulk)
+          Result.bulk(paths, is_bulk: is_bulk, command: :delete, id_result: 'path', bfail: options.get_option(:bfail)) do |l_path|
+            apifid = if (m = Parser.percent_selector(l_path))
+              Aspera.assert_values(m[:field], ['id'], type: BadIdentifier)
+              Api::NodeFileId.new(@api_node, m[:value])
             else
-              asyncs_id = options.instance_identifier{ |field, value| ssync_lookup(field, value)}
-              if %i[start stop].include?(sync_command)
-                @api_node.call(
-                  operation:    'POST',
-                  subpath:      "asyncs/#{asyncs_id}/#{sync_command}",
-                  content_type: Mime::TEXT,
-                  body:         '',
-                  ret:          :resp
-                ).body
-                return Result::Status.new('Done')
-              end
-              parameters = options.get_option(:query) || {} if %i[bandwidth counters files].include?(sync_command)
-              return Result::SingleObject.new(@api_node.read("asyncs/#{asyncs_id}/#{sync_command}", parameters))
+              @api_node.resolve_api_fid(do_root_file_id, l_path)
+            end
+            apifid.node_api.delete("files/#{apifid.file_id}")
+            {'path' => l_path}
+          end
+        end
+
+        # Shared Gen4 sync block: obtains a transfer spec via the Gen4 API for the given direction/remote_path.
+        def sync_gen4_block(do_root_file_id)
+          lambda do |direction, _local_path, remote_path|
+            ts_direction = direction.eql?(:pull) ? Transfer::Spec::DIRECTION_RECEIVE : Transfer::Spec::DIRECTION_SEND
+            apifid = @api_node.resolve_api_fid(do_root_file_id, remote_path)
+            apifid.node_api.transfer_spec_gen4(apifid.file_id, ts_direction)
+          end
+        end
+
+        Sync::Operations::DIRECTIONS.each do |dir|
+          define_method(:"action_access_keys_do_sync_#{dir}") do |do_root_file_id:, **|
+            run_sync_transfer(dir, &sync_gen4_block(do_root_file_id))
+          end
+        end
+
+        # access_keys > do > upload
+        def action_access_keys_do_upload(do_root_file_id:, **)
+          apifid = @api_node.resolve_api_fid(do_root_file_id, transfer.destination_folder(Transfer::Spec::DIRECTION_SEND), true)
+          Runner.result_transfer(transfer.start(apifid.node_api.transfer_spec_gen4(apifid.file_id, Transfer::Spec::DIRECTION_SEND)))
+        end
+
+        # access_keys > do > download
+        def action_access_keys_do_download(do_root_file_id:, **)
+          apifid, source_paths = @api_node.resolve_api_fid_paths(do_root_file_id, transfer.ts_source_paths)
+          Runner.result_transfer(transfer.start(apifid.node_api.transfer_spec_gen4(apifid.file_id, Transfer::Spec::DIRECTION_RECEIVE, {'paths'=>source_paths})))
+        end
+
+        # access_keys > do > permission (intermediate node: re-enter DSL at permission sub-tree)
+        def action_access_keys_do_permission(do_root_file_id:, **)
+          apifid = apifid_from_next_arg(do_root_file_id)
+          dispatch_from_registry(%i[access_keys do permission], {apifid: apifid}, skip_setup: true)
+        end
+
+        # access_keys > do > v3
+        def action_access_keys_do_v3(do_root_file_id:, **)
+          # Build a fresh Node for the v3 root, then let the DSL dispatcher consume the next command.
+          v3_node = Node.new(context: context, api: @api_node.resolve_api_fid(do_root_file_id, '').node_api)
+          v3_node.execute_action
+        end
+
+        # access_keys > do > node_info / bearer_token_node — shared helper builds the result hash
+        def gen4_apifid_info(do_root_file_id, path)
+          apifid = apifid_from_path(do_root_file_id, path)
+          result = {url: apifid.node_api.base_url, root_id: apifid.file_id}
+          case apifid.node_api.auth_params[:type]
+          when :basic
+            result[:username] = apifid.node_api.auth_params[:username]
+            result[:password] = apifid.node_api.auth_params[:password]
+          when :oauth2
+            result[:username] = apifid.node_api.params[:headers][Api::Node::HEADER_X_ASPERA_ACCESS_KEY]
+            result[:password] = apifid.node_api.oauth.authorization
+          else Aspera.error_unexpected_value(apifid.node_api.auth_params[:type]){'Node API Auth type'}
+          end
+          [apifid, result]
+        end
+
+        def action_access_keys_do_node_info(path:, do_root_file_id:, **)
+          _apifid, result = gen4_apifid_info(do_root_file_id, path)
+          Result::SingleObject.new(result)
+        end
+
+        def action_access_keys_do_bearer_token_node(path:, do_root_file_id:, **)
+          apifid, result = gen4_apifid_info(do_root_file_id, path)
+          Log.dump(:result, result)
+          Aspera.assert(apifid.node_api.auth_params[:type].eql?(:oauth2), type: BadArgument){"Cannot get bearer token if authenticating with secret (#{apifid.node_api.auth_params[:type]})"}
+          Aspera.assert(OAuth::Factory.bearer_auth?(result[:password]), 'Not using bearer token auth')
+          Result::Text.new(result[:password])
+        end
+
+        # access_keys > do > mkdir / mklink / mkfile — shared helper: resolve parent folder,
+        # build payload from query option, optionally check for name collision.
+        # @return [Array(NodeFileId, Hash)] parent apifid and payload with :name set
+        # @param path [String] full path (folder/name)
+        def gen4_mk_resolve(top_file_id, path)
+          containing_folder_path, new_item = Api::Node.split_folder(path)
+          apifid = @api_node.resolve_api_fid(top_file_id, containing_folder_path, true)
+          query = options.get_option(:query)
+          check_exists = true
+          payload = {name: new_item}
+          if query
+            check_exists = !query.delete('check').eql?(false)
+            target = query.delete('target')
+            if target
+              target_apifid = @api_node.resolve_api_fid(top_file_id, target, true)
+              payload[:target_id] = target_apifid.file_id
             end
-          when :stream
-            command = options.get_next_command(%i[list create show modify cancel])
-            case command
-            when :list
-              resp = @api_node.read('ops/transfers', query_read_delete)
-              return Result::ObjectList.new(resp, fields: %w[id status]) # TODO: useful?
-            when :create
-              resp = @api_node.create('streams', value_create_modify(command: command))
-              return Result::SingleObject.new(resp)
-            when :show
-              resp = @api_node.read("ops/transfers/#{options.get_next_argument('transfer id')}")
-              return Result::SingleObject.new(resp)
-            when :modify
-              resp = @api_node.update("streams/#{options.get_next_argument('transfer id')}", value_create_modify(command: command))
-              return Result::SingleObject.new(resp)
-            when :cancel
-              resp = @api_node.cancel("streams/#{options.get_next_argument('transfer id')}")
-              return Result::SingleObject.new(resp)
-            else Aspera.error_unexpected_value(command)
+            payload.merge!(query.symbolize_keys)
+          end
+          if check_exists
+            folder_content = apifid.node_api.read("files/#{apifid.file_id}/files")
+            link_name = ".#{new_item}.asp-lnk"
+            found = folder_content.find{ |i| i['name'].eql?(new_item) || i['name'].eql?(link_name)}
+            Aspera.assert(!found, type: Cli::Error){"A #{found['type']} already exists with name #{new_item}"}
+          end
+          [apifid, payload]
+        end
+
+        def action_access_keys_do_mkdir(path:, do_root_file_id:, **)
+          apifid, payload = gen4_mk_resolve(do_root_file_id, path)
+          payload[:type] = :folder
+          Result::SingleObject.new(apifid.node_api.create("files/#{apifid.file_id}/files", payload))
+        end
+
+        def action_access_keys_do_mklink(path:, do_root_file_id:, **)
+          apifid, payload = gen4_mk_resolve(do_root_file_id, path)
+          payload[:type] = :link
+          Aspera.assert(payload[:target_id], 'Missing target_id')
+          Aspera.assert(payload[:target_node_id], 'Missing target_node_id')
+          Result::SingleObject.new(apifid.node_api.create("files/#{apifid.file_id}/files", payload))
+        end
+
+        def action_access_keys_do_mkfile(path:, contents:, do_root_file_id:, **)
+          apifid, payload = gen4_mk_resolve(do_root_file_id, path)
+          payload[:type] = :file
+          payload[:contents] = contents.nil? ? '' : Base64.strict_encode64(contents)
+          Result::SingleObject.new(apifid.node_api.create("files/#{apifid.file_id}/files", payload))
+        end
+
+        # access_keys > do > permission > list/show/create/modify/delete
+        def action_access_keys_do_permission_list(apifid:, **)
+          list_query = query_read_delete(default: Rest.php_style({'include' => %w[access_level permission_count]}))
+          # Specify file to get permissions for unless not specified (then, get all permissions)
+          list_query['file_id'] = apifid.file_id unless apifid.file_id.to_s.empty?
+          list_query['inherited'] = false if list_query.key?('file_id') && !list_query.key?('inherited')
+          Result::ObjectList.new(apifid.node_api.read_with_pages('permissions', list_query))
+        end
+
+        def action_access_keys_do_permission_delete(perm_id:, apifid:, **)
+          is_bulk = options.get_option(:bulk)
+          items = perm_id.is_a?(Array) ? perm_id : [perm_id]
+          Result.bulk(items, is_bulk: is_bulk, command: :delete, bfail: options.get_option(:bfail)) do |one_id|
+            apifid.node_api.delete("permissions/#{one_id}")
+            the_app = apifid.node_api.app_info
+            the_app&.api&.permissions_send_event(event_data: {}, app_info: the_app, types: ['permission.deleted'])
+            {'id' => one_id}
+          end
+        end
+
+        def action_access_keys_do_permission_create(data:, apifid:, **)
+          create_param = data
+          Aspera.assert(!create_param.key?('file_id'), type: Cli::BadArgument){'no file_id'}
+          create_param['file_id'] = apifid.file_id
+          create_param['access_levels'] = Api::Node::ACCESS_LEVELS unless create_param.key?('access_levels')
+          the_app = apifid.node_api.app_info
+          the_app&.api&.permissions_set_create_params(perm_data: create_param, app_info: the_app)
+          created_data = apifid.node_api.create('permissions', create_param)
+          the_app&.api&.permissions_send_event(event_data: created_data, app_info: the_app)
+          Result::SingleObject.new(created_data)
+        end
+
+        # access_keys > set_bearer_key
+        def action_access_keys_set_bearer_key(access_key_id:, bearer_key_pem:, **)
+          access_key_id = @api_node.read('access_keys/self')['id'] if access_key_id.eql?('self')
+          key = OpenSSL::PKey.read(bearer_key_pem)
+          key = key.public_key if key.private?
+          @api_node.update("access_keys/#{access_key_id}", {token_verification_key: key.to_pem})
+          Result::Status.new('public key updated')
+        end
+
+        # async sub-commands: individual handlers
+        def action_async_show(async_id:, **)
+          async_ids = @api_node.read('async/list')['sync_ids']
+          if async_id.eql?(SpecialValues::ALL)
+            resp = @api_node.create('async/summary', {'syncs' => async_ids})['sync_summaries']
+            return Result::Empty.new if resp.empty?
+            return Result::ObjectList.new(resp, fields: %w[snid name local_dir remote_dir])
+          end
+          Integer(async_id)
+          resp = @api_node.create('async/summary', {'syncs' => [async_id]})['sync_summaries']
+          return Result::Empty.new if resp.empty?
+          Result::SingleObject.new(resp.first)
+        end
+
+        def action_async_delete(async_id:, **)
+          async_ids = async_id.eql?(SpecialValues::ALL) ? @api_node.read('async/list')['sync_ids'] : [async_id]
+          Result::SingleObject.new(@api_node.create('async/delete', {'syncs' => async_ids}))
+        end
+
+        def action_async_bandwidth(async_id:, **)
+          Integer(async_id)
+          post_data = {'syncs' => [async_id], 'seconds' => 100}
+          resp = @api_node.create('async/bandwidth', post_data)
+          data = resp['bandwidth_data']
+          return Result::Empty.new if data.empty?
+          Result::ObjectList.new(data.first[async_id]['data'])
+        end
+
+        def action_async_files(async_id:, **)
+          Integer(async_id)
+          post_data = {'syncs' => [async_id]}
+          filter = options.get_option(:query)
+          post_data.merge!(filter) unless filter.nil?
+          resp = @api_node.create('async/files', post_data)
+          data = resp['sync_files']
+          data = data.first[async_id] unless data.empty?
+          iteration_data = []
+          skip_ids_persistency = nil
+          if options.get_option(:once_only, mandatory: true)
+            skip_ids_persistency = PersistencyActionOnce.new(
+              manager: persistency,
+              data:    iteration_data,
+              id:      IdGenerator.from_list('sync_files', options.get_option(:url, mandatory: true), options.get_option(:username, mandatory: true), async_id)
+            )
+            data.select!{ |l| l['fnid'].to_i > iteration_data.first} unless iteration_data.first.nil?
+            iteration_data[0] = data.last['fnid'].to_i unless data.empty?
+          end
+          return Result::Empty.new if data.empty?
+          skip_ids_persistency&.save
+          Result::ObjectList.new(data)
+        end
+
+        def action_async_counters(async_id:, **)
+          Integer(async_id)
+          resp = @api_node.create('async/counters', {'syncs' => [async_id]})['sync_counters'].first[async_id].last
+          return Result::Empty.new if resp.nil?
+          Result::SingleObject.new(resp)
+        end
+
+        def action_ssync_delete(ssync_id:, **)
+          is_bulk = options.get_option(:bulk)
+          items = ssync_id.is_a?(Array) ? ssync_id : [ssync_id]
+          Result.bulk(items, is_bulk: is_bulk, command: :delete, bfail: options.get_option(:bfail)) do |one_id|
+            @api_node.delete("asyncs/#{one_id}", query_read_delete)
+            {'id' => one_id}
+          end
+        end
+
+        def action_ssync_start(ssync_id:, **)
+          @api_node.call(operation: 'POST', subpath: "asyncs/#{ssync_id}/start", content_type: Mime::TEXT, body: '', ret: :resp).body
+          Result::Status.new('Done')
+        end
+
+        def action_ssync_stop(ssync_id:, **)
+          @api_node.call(operation: 'POST', subpath: "asyncs/#{ssync_id}/stop", content_type: Mime::TEXT, body: '', ret: :resp).body
+          Result::Status.new('Done')
+        end
+
+        # transfer sub-commands
+        def action_transfer_list
+          transfer_filter = query_read_delete(default: {})
+          iteration_persistency = nil
+          if options.get_option(:once_only, mandatory: true)
+            iteration_persistency = PersistencyActionOnce.new(
+              manager: persistency,
+              data:    [],
+              id:      IdGenerator.from_list('node_transfers', options.get_option(:url, mandatory: true), options.get_option(:username, mandatory: true))
+            )
+            if transfer_filter.delete('reset')
+              iteration_persistency.data.clear
+              iteration_persistency.save
+              return Result::Status.new('Persistency reset')
             end
-          when :transfer
-            command = options.get_next_command(%i[list cancel show modify bandwidth_average sessions])
-            case command
-            when :list
-              transfer_filter = query_read_delete(default: {})
-              iteration_persistency = nil
-              if options.get_option(:once_only, mandatory: true)
-                iteration_persistency = PersistencyActionOnce.new(
-                  manager: persistency,
-                  data:    [],
-                  id:      IdGenerator.from_list(
-                    'node_transfers',
-                    options.get_option(:url, mandatory: true),
-                    options.get_option(:username, mandatory: true)
-                  )
-                )
-                if transfer_filter.delete('reset')
-                  iteration_persistency.data.clear
-                  iteration_persistency.save
-                  return Result::Status.new('Persistency reset')
-                end
-              else
-                Aspera.assert(!transfer_filter.key?('reset'), 'reset only with once_only', type: Cli::BadArgument)
-              end
-              transfers_data = @api_node.read_with_paging('ops/transfers', transfer_filter, iteration: iteration_persistency&.data)
-              iteration_persistency&.save
-              return Result::ObjectList.new(transfers_data, fields: %w[id status start_spec.direction start_spec.remote_user start_spec.remote_host start_spec.destination_path])
-            when :sessions
-              transfers_data = @api_node.read('ops/transfers', query_read_delete)
-              sessions = transfers_data.flat_map{ |t| t['sessions']}
-              start_end = %i[start end].freeze
-              sessions.each do |session|
-                start_end.each do |what|
-                  session["#{what}_time"] = session["#{what}_time_usec"] ? Time.at(session["#{what}_time_usec"] / 1_000_000.0).utc.iso8601(0) : nil
-                end
-              end
-              return Result::ObjectList.new(sessions, fields: %w[id status start_time end_time target_rate_kbps])
-            when :cancel
-              @api_node.cancel("ops/transfers/#{options.instance_identifier}")
-              return Result::Status.new('Cancelled')
-            when :show
-              resp = @api_node.read("ops/transfers/#{options.instance_identifier}")
-              return Result::SingleObject.new(resp)
-            when :modify
-              @api_node.update("ops/transfers/#{options.instance_identifier}", options.get_next_argument('update value', validation: Hash))
-              return Result::Status.new('Modified')
-            when :bandwidth_average
-              transfers_data = @api_node.read('ops/transfers', query_read_delete)
-              # collect all key dates
-              bandwidth_period = {}
-              dir_info = %i[avg_kbps sessions].freeze
-              transfers_data.each do |transfer|
-                session = transfer
-                # transfer['sessions'].each do |session|
-                next if session['avg_rate_kbps'].zero?
-                bandwidth_period[session['start_time_usec']] = 0
-                bandwidth_period[session['end_time_usec']] = 0
-                # end
-              end
-              result = []
-              # all dates sorted numerically
-              all_dates = bandwidth_period.keys.sort
-              all_dates.each_with_index do |start_date, index|
-                end_date = all_dates[index + 1]
-                # do not process last one
-                break if end_date.nil?
-                # init data for this period
-                period_bandwidth = Transfer::Spec::DIRECTION_ENUM_VALUES.map(&:to_sym).to_h do |direction|
-                  [direction, dir_info.to_h{ |k2| [k2, 0]}]
-                end
-                # find all transfers that were active at this time
-                transfers_data.each do |transfer|
-                  session = transfer
-                  # transfer['sessions'].each do |session|
-                  # skip if not information for this period
-                  next if session['avg_rate_kbps'].zero?
-                  # skip if not in this period
-                  next if session['start_time_usec'] >= end_date || session['end_time_usec'] <= start_date
-                  info = period_bandwidth[transfer['start_spec']['direction'].to_sym]
-                  info[:avg_kbps] += session['avg_rate_kbps']
-                  info[:sessions] += 1
-                  # end
-                end
-                next if Transfer::Spec::DIRECTION_ENUM_VALUES.map(&:to_sym).all? do |dir|
-                  period_bandwidth[dir][:sessions].zero?
-                end
-                result.push({start: Time.at(start_date / 1_000_000), end: Time.at(end_date / 1_000_000)}.merge(period_bandwidth))
-              end
-              return Result::ObjectList.new(result)
-            else Aspera.error_unexpected_value(command)
+          else
+            Aspera.assert(!transfer_filter.key?('reset'), 'reset only with once_only', type: Cli::BadArgument)
+          end
+          transfers_data = @api_node.read_with_paging('ops/transfers', transfer_filter, iteration: iteration_persistency&.data)
+          iteration_persistency&.save
+          Result::ObjectList.new(transfers_data, fields: %w[id status start_spec.direction start_spec.remote_user start_spec.remote_host start_spec.destination_path])
+        end
+
+        def action_transfer_sessions
+          transfers_data = @api_node.read('ops/transfers', query_read_delete)
+          sessions = transfers_data.flat_map{ |t| t['sessions']}
+          sessions.each do |session|
+            SESSION_TIME_FIELDS.each do |what|
+              session["#{what}_time"] = session["#{what}_time_usec"] ? Time.at(session["#{what}_time_usec"] / 1_000_000.0).utc.iso8601(0) : nil
             end
-          when :service
-            command = options.get_next_command(%i[list create delete])
-            service_id = options.instance_identifier if [:delete].include?(command)
-            case command
-            when :list
-              resp = @api_node.read('rund/services')
-              return Result::ObjectList.new(resp['services'])
-            when :create
-              # @json:'{"type":"WATCHFOLDERD","run_as":{"user":"user1"}}'
-              params = options.get_next_argument('creation data', validation: Hash)
-              resp = @api_node.create('rund/services', params)
-              return Result::Status.new("#{resp['id']} created")
-            when :delete
-              @api_node.delete("rund/services/#{service_id}")
-              return Result::Status.new("#{service_id} deleted")
+          end
+          Result::ObjectList.new(sessions, fields: %w[id status start_time end_time target_rate_kbps])
+        end
+
+        def action_transfer_cancel(transfer_id:, **)
+          @api_node.cancel("ops/transfers/#{transfer_id}")
+          Result::Status.new('Cancelled')
+        end
+
+        def action_transfer_modify(update_value:, transfer_id:, **)
+          @api_node.update("ops/transfers/#{transfer_id}", update_value)
+          Result::Status.new('Modified')
+        end
+
+        def action_transfer_bandwidth_average
+          transfers_data = @api_node.read('ops/transfers', query_read_delete)
+          bandwidth_period = {}
+          dir_info = %i[avg_kbps sessions].freeze
+          transfers_data.each do |t|
+            next if t['avg_rate_kbps'].zero?
+            bandwidth_period[t['start_time_usec']] = 0
+            bandwidth_period[t['end_time_usec']] = 0
+          end
+          result = []
+          all_dates = bandwidth_period.keys.sort
+          all_dates.each_with_index do |start_date, index|
+            end_date = all_dates[index + 1]
+            break if end_date.nil?
+            period_bandwidth = Transfer::Spec::DIRECTION_ENUM_VALUES.map(&:to_sym).to_h do |dir|
+              [dir, dir_info.to_h{ |k2| [k2, 0]}]
             end
-          when :watch_folder
-            return watch_folder_action
-          when :central
-            command = options.get_next_command(%i[session file])
-            validator_id = options.get_option(:validator)
-            validation = {'validator_id' => validator_id} unless validator_id.nil?
-            request_data = options.get_option(:query) || {}
-            case command
-            when :session
-              command = options.get_next_command([:list])
-              case command
-              when :list
-                request_data = options.get_next_argument('request data', mandatory: false, validation: Hash, default: {})
-                request_data.deep_merge!({'validation' => validation}) unless validation.nil?
-                resp = @api_node.create('services/rest/transfers/v1/sessions', request_data)
-                return Result::ObjectList.new(resp['session_info_result']['session_info'], fields: %w[session_uuid status transport direction bytes_transferred])
-              end
-            when :file
-              command = options.get_next_command(%i[list modify])
-              case command
-              when :list
-                request_data = options.get_next_argument('request data', mandatory: false, validation: Hash, default: {})
-                request_data.deep_merge!({'validation' => validation}) unless validation.nil?
-                resp = @api_node.create('services/rest/transfers/v1/files', request_data)
-                resp = JSON.parse(resp) if resp.is_a?(String)
-                Log.dump(:resp, resp)
-                return Result::ObjectList.new(resp['file_transfer_info_result']['file_transfer_info'], fields: %w[session_uuid file_id status path])
-              when :modify
-                request_data = options.get_next_argument('request data', mandatory: false, validation: Hash, default: {})
-                request_data.deep_merge!(validation) unless validation.nil?
-                @api_node.update('services/rest/transfers/v1/files', request_data)
-                return Result::Status.new('updated')
-              end
+            transfers_data.each do |t|
+              next if t['avg_rate_kbps'].zero?
+              next if t['start_time_usec'] >= end_date || t['end_time_usec'] <= start_date
+              info = period_bandwidth[t['start_spec']['direction'].to_sym]
+              info[:avg_kbps] += t['avg_rate_kbps']
+              info[:sessions] += 1
             end
-          when :asperabrowser
-            browse_params = {
-              'nodeUser' => options.get_option(:username, mandatory: true),
-              'nodePW'   => options.get_option(:password, mandatory: true),
-              'nodeURL'  => options.get_option(:url, mandatory: true)
+            next if Transfer::Spec::DIRECTION_ENUM_VALUES.map(&:to_sym).all?{ |dir| period_bandwidth[dir][:sessions].zero?}
+            result.push({start: Time.at(start_date / 1_000_000), end: Time.at(end_date / 1_000_000)}.merge(period_bandwidth))
+          end
+          Result::ObjectList.new(result)
+        end
+
+        # service sub-commands
+        def action_service_create(creation_data:, **)
+          resp = @api_node.create('rund/services', creation_data)
+          Result::Status.new("#{resp['id']} created")
+        end
+
+        def action_service_delete(service_id:, **)
+          @api_node.delete("rund/services/#{service_id}")
+          Result::Status.new("#{service_id} deleted")
+        end
+
+        # central: shared helper
+        def central_validation
+          validator_id = options.get_option(:validator)
+          validator_id ? {'validator_id' => validator_id} : nil
+        end
+
+        # central > session > list
+        def action_central_session_list(request_data:, **)
+          request_data ||= {}
+          validation = central_validation
+          request_data.deep_merge!({'validation' => validation}) unless validation.nil?
+          resp = @api_node.create('services/rest/transfers/v1/sessions', request_data)
+          Result::ObjectList.new(resp['session_info_result']['session_info'], fields: %w[session_uuid status transport direction bytes_transferred])
+        end
+
+        # central > file > list
+        def action_central_file_list(request_data:, **)
+          request_data ||= {}
+          validation = central_validation
+          request_data.deep_merge!({'validation' => validation}) unless validation.nil?
+          resp = @api_node.create('services/rest/transfers/v1/files', request_data)
+          resp = JSON.parse(resp) if resp.is_a?(String)
+          Log.dump(:resp, resp)
+          Result::ObjectList.new(resp['file_transfer_info_result']['file_transfer_info'], fields: %w[session_uuid file_id status path])
+        end
+
+        # central > file > modify
+        def action_central_file_modify(request_data:, **)
+          request_data ||= {}
+          validation = central_validation
+          request_data.deep_merge!(validation) unless validation.nil?
+          @api_node.update('services/rest/transfers/v1/files', request_data)
+          Result::Status.new('updated')
+        end
+
+        def action_asperabrowser
+          browse_params = {
+            'nodeUser' => options.get_option(:username, mandatory: true),
+            'nodePW'   => options.get_option(:password, mandatory: true),
+            'nodeURL'  => options.get_option(:url, mandatory: true)
+          }
+          # encode parameters so that it looks good in url
+          encoded_params = Base64.strict_encode64(Zlib::Deflate.deflate(JSON.generate(browse_params))).gsub(/=+$/, '').tr('+/', '-_').reverse
+          Environment.instance.open_uri("#{options.get_option(:asperabrowserurl)}?goto=#{encoded_params}")
+          return Result::Status.new('done')
+        end
+
+        def action_bearer_token(private_key_pem:, user_group_id:, **)
+          private_key = OpenSSL::PKey::RSA.new(private_key_pem)
+          access_key  = options.get_option(:username, mandatory: true)
+          Result::Text.new(Api::Node.bearer_token(payload: user_group_id, access_key: access_key, private_key: private_key))
+        end
+
+        def action_simulator(parameters: {}, **)
+          require 'aspera/node_simulator'
+          parameters = parameters.symbolize_keys
+          uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
+          server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
+          server.mount(uri.path, NodeSimulatorServlet, parameters.except(*WebServerSimple::PARAMS), NodeSimulator.new)
+          server.start
+          return Result::Status.new('Simulator terminated')
+        end
+
+        def action_telemetry(parameters: {}, **)
+          parameters = parameters.symbolize_keys
+          %i[url key].each do |psym|
+            Aspera.assert(parameters.key?(psym), type: Cli::BadArgument){"Missing parameter: #{psym}"}
+          end
+          require 'socket'
+          parameters[:interval] = 10 unless parameters.key?(:interval)
+          parameters[:hostname] = Socket.gethostname unless parameters.key?(:hostname)
+          interval = parameters[:interval].to_f
+          Aspera.assert(interval > 0, type: Cli::BadArgument){'Interval must be a positive number in seconds'}
+          otel_api = Rest.new(
+            base_url: "#{parameters[:url]}/v1",
+            headers: {
+              # 'Authorization'  => "apiToken #{parameters[:key]}",
+              'x-instana-key'  => parameters[:key],
+              'x-instana-host' => parameters[:hostname]
             }
-            # encode parameters so that it looks good in url
-            encoded_params = Base64.strict_encode64(Zlib::Deflate.deflate(JSON.generate(browse_params))).gsub(/=+$/, '').tr('+/', '-_').reverse
-            Environment.instance.open_uri("#{options.get_option(:asperabrowserurl)}?goto=#{encoded_params}")
-            return Result::Status.new('done')
-          when :basic_token
-            return Result::Text.new(Rest.basic_authorization(options.get_option(:username, mandatory: true), options.get_option(:password, mandatory: true)))
-          when :bearer_token
-            private_key = OpenSSL::PKey::RSA.new(options.get_next_argument('private RSA key PEM value', validation: String))
-            token_info = options.get_next_argument('user and group identification', validation: Hash)
-            access_key = options.get_option(:username, mandatory: true)
-            return Result::Text.new(Api::Node.bearer_token(payload: token_info, access_key: access_key, private_key: private_key))
-          when :simulator
-            require 'aspera/node_simulator'
-            parameters = value_create_modify(command: command, default: {}).symbolize_keys
-            uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
-            server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-            server.mount(uri.path, NodeSimulatorServlet, parameters.except(*WebServerSimple::PARAMS), NodeSimulator.new)
-            server.start
-            return Result::Status.new('Simulator terminated')
-          when :telemetry
-            parameters = value_create_modify(command: command, default: {}).symbolize_keys
-            %i[url key].each do |psym|
-              raise Cli::BadArgument, "Missing parameter: #{psym}" unless parameters.key?(psym)
-            end
-            require 'socket'
-            parameters[:interval] = 10 unless parameters.key?(:interval)
-            parameters[:hostname] = Socket.gethostname unless parameters.key?(:hostname)
-            interval = parameters[:interval].to_f
-            raise Cli::BadArgument, 'Interval must be a positive number in seconds' if interval <= 0
-            otel_api = Rest.new(
-              base_url: "#{parameters[:url]}/v1",
-              headers: {
-                # 'Authorization'  => "apiToken #{parameters[:key]}",
-                'x-instana-key'  => parameters[:key],
-                'x-instana-host' => parameters[:hostname]
-              }
-            )
-            datapoint = {
-              attributes:   [
-                {
-                  key:   'server.name',
-                  value: {
-                    stringValue: 'HSTS1'
-                  }
+          )
+          datapoint = {
+            attributes:   [
+              {
+                key:   'server.name',
+                value: {
+                  stringValue: 'HSTS1'
                 }
-              ],
-              asInt:        nil,
-              timeUnixNano: nil
-            }
-            # https://opentelemetry.io/docs/specs/otel/metrics/data-model/#gauge
-            metrics = {
-              resourceMetrics: [
-                {
-                  resource:     {
-                    attributes: [
+              }
+            ],
+            asInt:        nil,
+            timeUnixNano: nil
+          }
+          # https://opentelemetry.io/docs/specs/otel/metrics/data-model/#gauge
+          metrics = {
+            resourceMetrics: [
+              {
+                resource:     {
+                  attributes: [
+                    {
+                      key:   'service.name',
+                      value: {
+                        stringValue: 'IBMAspera'
+                      }
+                    }
+                  ]
+                },
+                scopeMetrics: [
+                  {
+                    metrics: [
                       {
-                        key:   'service.name',
-                        value: {
-                          stringValue: 'IBMAspera'
+                        name:        'active.transfers',
+                        description: 'Number of active transfers',
+                        unit:        '1',
+                        gauge:       {
+                          dataPoints: [
+                            datapoint
+                          ]
                         }
                       }
                     ]
-                  },
-                  scopeMetrics: [
-                    {
-                      metrics: [
-                        {
-                          name:        'active.transfers',
-                          description: 'Number of active transfers',
-                          unit:        '1',
-                          gauge:       {
-                            dataPoints: [
-                              datapoint
-                            ]
-                          }
-                        }
-                      ]
-                    }
-                  ]
-                }
-              ]
-            }
-            loop do
-              timestamp = Time.now
-              transfers_data = @api_node.read_with_paging('ops/transfers', {active_only: true})
-              datapoint[:asInt] = transfers_data.length
-              datapoint[:timeUnixNano] = timestamp.to_i * 1_000_000_000 + timestamp.nsec
-              Log.log.info("#{datapoint[:asInt]} active transfers")
-              # https://www.ibm.com/docs/en/instana-observability/current?topic=instana-backend
-              otel_api.create('metrics', metrics)
-              break if interval.eql?(0.0)
-              sleep([0.0, interval - (Time.now - timestamp)].max)
-            end
+                  }
+                ]
+              }
+            ]
+          }
+          loop do
+            timestamp = Time.now
+            transfers_data = @api_node.read_with_paging('ops/transfers', {active_only: true})
+            datapoint[:asInt] = transfers_data.length
+            datapoint[:timeUnixNano] = timestamp.to_i * 1_000_000_000 + timestamp.nsec
+            Log.log.info("#{datapoint[:asInt]} active transfers")
+            # https://www.ibm.com/docs/en/instana-observability/current?topic=instana-backend
+            otel_api.create('metrics', metrics)
+            break if interval.eql?(0.0)
+            sleep([0.0, interval - (Time.now - timestamp)].max)
           end
-          Aspera.error_unreachable_line
+        end
+
+        # Dispatch a command that has already been read from the argument stream.
+        # Used when a new Node instance is created and the command was already consumed
+        # (e.g., :v3 delegation, shares, cos, faspex).
+        # Re-enters the DSL registry for all commands so Proc handlers and sub-trees
+        # are resolved normally.
+        # @param command [Symbol] command already consumed from the argument stream
+        # @return [Object] CLI result
+        def dispatch_v3_command(command)
+          Aspera.assert_values(command, COMMANDS_GEN3 + %i[health events info slash license api_details access_keys transfer]){'v3 command'}
+          dispatch_from_registry([command], {})
         end
 
         private
 
         # Response has key `paths`.
         # From those, check if there is an error
-        # @return [Array] of Hash with 2 keys: `path` and `result`
+        # @return [Array<Hash>] list of hashes with 2 keys: `path` and `result`
         def response_to_result(response, success_msg)
           errors = []
           obj_list = []