aspera-cli 4.0.0 → 4.1.0

data/docs/test_env.conf

@@ -19,7 +19,6 @@ default:
 cli_default:
   interactive: your value here
   smtp: your value here
-  ascp_path: your value here
 local_user:
   ssh_keys: your value here
 smtp_config:
@@ -50,6 +49,7 @@ tst_node_faspex:
   password: your value here
 tst_faspex5:
   url: your value here
+  auth: your value here
   username: your value here
   password: your value here
 tst_shares:
@@ -94,6 +94,7 @@ tst_ak_preview:
   url: your value here
   username: your value here
   password: your value here
+  mimemagic: your value here
 tst_node_preview:
   url: your value here
   username: your value here
@@ -122,6 +123,7 @@ misc:
   aoc_publink_recv_from_aocuser: your value here
   aoc_publink_send_shd_inbox: your value here
   aoc_publink_send_aoc_user: your value here
+  aoc_publink_send_use_pass: your value here
   aoc_publink_folder: your value here
   aoc_shbx_ws: your value here
   aoc_shbx_name: your value here
@@ -138,3 +140,4 @@ misc:
   email_external: your value here
   aoc_org: your value here
   aoc_user: your value here
+  http_gw_fqdn_port: your value here

data/docs/transfer_spec.html

@@ -28,7 +28,7 @@ arg: related ascp argument or env var suffix (PASS for ASPERA_SCP_PASS)
 </p>
 <p>
 UNDER CONSTRUCTION<br/>
-<a href="https://developer.ibm.com/api/view/aspera-prod:ibm-aspera:title-IBM_Aspera#id90944">Documentation&rarr;Node API&rarr;/opt/transfers</a><br/>
+<a href="https://developer.ibm.com/apis/catalog/?search=aspera">Aspera API Documentation</a>&rarr;Node API&rarr;/opt/transfers<br/>
 </p>
 
 <table>

data/lib/aspera/aoc.rb

@@ -121,7 +121,7 @@ module Aspera
       raise RuntimeError,'too many redirections'
     end
 
-    # @param :link,:url,:auth,:client_id,:client_secret,:scope,:redirect_uri,:private_key,:username,:subpath
+    # @param :link,:url,:auth,:client_id,:client_secret,:scope,:redirect_uri,:private_key,:username,:subpath,:password (for pub link)
     def initialize(opt)
       # access key secrets are provided out of band to get node api access
       # key: access key
@@ -185,6 +185,7 @@ module Aspera
         aoc_auth_p[:jwt_subject]         = opt[:username]
         aoc_auth_p[:jwt_private_key_obj] = OpenSSL::PKey::RSA.new(private_key_PEM_string)
       when :url_token
+        aoc_auth_p[:password]=opt[:password] unless opt[:password].nil?
         # nothing more
       else raise "ERROR: unsupported auth method: #{aoc_auth_p[:grant]}"
       end
@@ -293,6 +294,7 @@ module Aspera
     # no scope: requires secret
     # if secret provided beforehand: use it
     def get_node_api(node_info,node_scope=nil)
+      # X-Aspera-AccessKey required for bearer token only
       node_rest_params={
         :base_url => node_info['url'],
         :headers  => {'X-Aspera-AccessKey'=>node_info['access_key']},
@@ -312,7 +314,7 @@ module Aspera
         node_rest_params[:auth]=self.params[:auth].clone
         node_rest_params[:auth][:scope]=self.class.node_scope(node_info['access_key'],node_scope)
       end
-      return Rest.new(node_rest_params)
+      return Node.new(node_rest_params)
     end
 
     # check that parameter has necessary types
@@ -328,102 +330,82 @@ module Aspera
       return node_info,file_id
     end
 
-    # returns node api and folder_id from soft link
-    def read_asplnk(current_file_info)
-      new_node_api=get_node_api(self.read("nodes/#{current_file_info['target_node_id']}")[:data],SCOPE_NODE_USER)
-      return {:node_api=>new_node_api,:folder_id=>current_file_info['target_id']}
+    # add entry to list if test block is success
+    def process_find_files(entry,path)
+      begin
+        # add to result if match filter
+        @find_state[:found].push(entry.merge({'path'=>path})) if @find_state[:test_block].call(entry)
+        # process link
+        if entry[:type].eql?('link')
+          sub_node_info=self.read("nodes/#{entry['target_node_id']}")[:data]
+          sub_opt={method: process_find_files, top_file_id: entry['target_id'], top_file_path: path}
+          get_node_api(sub_node_info,SCOPE_NODE_USER).crawl(self,sub_opt)
+        end
+      rescue => e
+        Log.log.error("#{path}: #{e.message}")
+      end
+      # process all folders
+      return true
     end
 
-    # @returns list of file paths that match given regex
     def find_files( top_node_file, test_block )
       top_node_info,top_file_id=check_get_node_file(top_node_file)
       Log.log.debug("find_files: node_info=#{top_node_info}, fileid=#{top_file_id}")
-      result=[]
-      top_node_api=get_node_api(top_node_info,SCOPE_NODE_USER)
-      # initialize loop elements : list of folders to scan
-      # Note: top file id is necessarily a folder
-      items_to_explore=[{:node_api=>top_node_api,:folder_id=>top_file_id,:path=>''}]
-
-      while !items_to_explore.empty? do
-        current_item = items_to_explore.shift
-        Log.log.debug("searching #{current_item[:path]}".bg_green)
-        # get folder content
-        begin
-          folder_contents = current_item[:node_api].read("files/#{current_item[:folder_id]}/files")[:data]
-        rescue => e
-          Log.log.warn("#{current_item[:path]}: #{e.message}")
-          folder_contents=[]
+      @find_state={found: [], test_block: test_block}
+      get_node_api(top_node_info,SCOPE_NODE_USER).crawl(self,{method: :process_find_files, top_file_id: top_file_id})
+      result=@find_state[:found]
+      @find_state=nil
+      return result
+    end
+
+    def process_resolve_node_file(entry,path)
+      # stop digging here if not in right path
+      return false unless entry['name'].eql?(@resolve_state[:path].first)
+      # ok it matches, so we remove the match
+      @resolve_state[:path].shift
+      case entry['type']
+      when 'file'
+        # file must be terminal
+        raise "#{entry['name']} is a file, expecting folder to find: #{@resolve_state[:path]}" unless @resolve_state[:path].empty?
+        @resolve_state[:result][:file_id]=entry['id']
+      when 'link'
+        @resolve_state[:result][:node_info]=self.read("nodes/#{entry['target_node_id']}")[:data]
+        if @resolve_state[:path].empty?
+          @resolve_state[:result][:file_id]=entry['target_id']
+        else
+          get_node_api(@resolve_state[:result][:node_info],SCOPE_NODE_USER).crawl(self,{method: :process_resolve_node_file, top_file_id: entry['target_id']})
         end
-        # TODO: check if this is a folder or file ?
-        Log.dump(:folder_contents,folder_contents)
-        folder_contents.each do |current_file_info|
-          item_path=File.join(current_item[:path],current_file_info['name'])
-          Log.log.debug("looking #{item_path}".bg_green)
-          begin
-            # does item match ?
-            result.push(current_file_info.merge({'path'=>item_path})) if test_block.call(current_file_info)
-            # does it need further processing ?
-            case current_file_info['type']
-            when 'file'
-              Log.log.debug("testing : #{current_file_info['name']}")
-            when 'folder'
-              items_to_explore.push({:node_api=>current_item[:node_api],:folder_id=>current_file_info['id'],:path=>item_path})
-            when 'link' # .*.asp-lnk
-              items_to_explore.push(read_asplnk(current_file_info).merge({:path=>item_path}))
-            else
-              Log.log.error("unknown folder item type: #{current_file_info['type']}")
-            end
-          rescue => e
-            Log.log.error("#{item_path}: #{e.message}")
-          end
+      when 'folder'
+        if @resolve_state[:path].empty?
+          # found: store
+          @resolve_state[:result][:file_id]=entry['id']
+          return false
         end
+      else
+        Log.log.warn("unknown element type: #{entry['type']}")
       end
-      return result
+      # continue to dig folder
+      return true
     end
 
-    # @return node information (returned by API) and file id, from a "/" based path
+    # @return Array(node_info,file_id)   for the given path
+    # @param top_node_file       Array    [root node,file id]
+    # @param element_path_string String   path of element
     # supports links to secondary nodes
-    # input: Array(root node,file id), String path
-    # output: Array(node_info,file_id)   for the given path
-    def resolve_node_file( top_node_file, element_path_string='' )
-      Log.log.debug("resolve_node_file: top_node_file=#{top_node_file}, path=#{element_path_string}")
-      # initialize loop invariants
-      current_node_info,current_file_id=check_get_node_file(top_node_file)
-      items_to_explore=element_path_string.split(PATH_SEPARATOR).select{|i| !i.empty?}
-
-      while !items_to_explore.empty? do
-        current_item = items_to_explore.shift
-        Log.log.debug "searching #{current_item}".bg_green
-        # get API if changed
-        current_node_api=get_node_api(current_node_info,SCOPE_NODE_USER) if current_node_api.nil?
-        # get folder content
-        folder_contents = current_node_api.read("files/#{current_file_id}/files")
-        Log.dump(:folder_contents,folder_contents)
-        matching_folders = folder_contents[:data].select { |i| i['name'].eql?(current_item)}
-        #Log.log.debug "matching_folders: #{matching_folders}"
-        raise "no such folder: #{current_item} in #{folder_contents[:data].map { |i| i['name']}}" if matching_folders.empty?
-        current_file_info = matching_folders.first
-        # process type of file
-        case current_file_info['type']
-        when 'file'
-          current_file_id=current_file_info['id']
-          # a file shall be terminal
-          if !items_to_explore.empty? then
-            raise "#{current_item} is a file, expecting folder to find: #{items_to_explore}"
-          end
-        when 'link'
-          current_node_info=self.read("nodes/#{current_file_info['target_node_id']}")[:data]
-          current_file_id=current_file_info['target_id']
-          # need to switch node
-          current_node_api=nil
-        when 'folder'
-          current_file_id=current_file_info['id']
-        else
-          Log.log.warn("unknown element type: #{current_file_info['type']}")
-        end
+    def resolve_node_file( top_node_file, element_path_string )
+      top_node_info,top_file_id=check_get_node_file(top_node_file)
+      path_elements=element_path_string.split(PATH_SEPARATOR).select{|i| !i.empty?}
+      result={node_info: top_node_info, file_id: nil}
+      if path_elements.empty?
+        result[:file_id]=top_file_id
+      else
+        @resolve_state={path: path_elements, result: result}
+        get_node_api(top_node_info,SCOPE_NODE_USER).crawl(self,{method: :process_resolve_node_file, top_file_id: top_file_id})
+        not_found=@resolve_state[:path]
+        @resolve_state=nil
+        raise "entry not found: #{not_found}" if result[:file_id].nil?
       end
-      Log.log.info("resolve_node_file(#{element_path_string}): file_id=#{current_file_id},node_info=#{current_node_info}")
-      return {node_info: current_node_info, file_id: current_file_id}
+      return result
     end
 
   end # AoC

data/lib/aspera/cli/formater.rb

@@ -151,6 +151,8 @@ module Aspera
             else
               if user_asked_fields_list_str.start_with?('+')
                 result_default_fields(results,table_rows_hash_val).push(*user_asked_fields_list_str.gsub(/^\+/,'').split(','))
+              elsif user_asked_fields_list_str.start_with?('-')
+                result_default_fields(results,table_rows_hash_val).select{|i| ! user_asked_fields_list_str.gsub(/^\-/,'').split(',').include?(i)}
               else
                 user_asked_fields_list_str.split(',')
               end

data/lib/aspera/cli/main.rb

@@ -53,13 +53,20 @@ module Aspera
         @help_url='http://www.rubydoc.info/gems/'+GEM_NAME
         @gem_url='https://rubygems.org/gems/'+GEM_NAME
         # give command line arguments to option manager (no parsing)
-        @plugin_env[:options]=@opt_mgr=Manager.new(self.program_name,argv,app_banner())
+        app_main_folder=ENV[conf_dir_env_var]
+        # if env var undefined or empty
+        if app_main_folder.nil? or app_main_folder.empty?
+          user_home_folder=Dir.home
+          raise CliError,"Home folder does not exist: #{user_home_folder}. Check your user environment or use #{conf_dir_env_var}." unless Dir.exist?(user_home_folder)
+          app_main_folder=File.join(user_home_folder,Plugins::Config::ASPERA_HOME_FOLDER_NAME,PROGRAM_NAME)
+        end
+        @plugin_env[:options]=@opt_mgr=Manager.new(PROGRAM_NAME,argv,app_banner())
         @plugin_env[:formater]=Formater.new(@plugin_env[:options])
-        Rest.user_agent=self.program_name
+        Rest.user_agent=PROGRAM_NAME
         # must override help methods before parser called (in other constructors)
         init_global_options()
         # the Config plugin adds the @preset parser
-        @plugin_env[:config]=Plugins::Config.new(@plugin_env,self.program_name,@help_url,Aspera::Cli::VERSION)
+        @plugin_env[:config]=Plugins::Config.new(@plugin_env,PROGRAM_NAME,@help_url,Aspera::Cli::VERSION,app_main_folder)
         # the TransferAgent plugin may use the @preset parser
         @plugin_env[:transfer]=TransferAgent.new(@plugin_env)
         Log.log.debug('created plugin env'.red)
@@ -73,21 +80,21 @@ module Aspera
       end
 
       def app_banner
-        banner = "NAME\n\t#{self.program_name} -- a command line tool for Aspera Applications (v#{Aspera::Cli::VERSION})\n\n"
+        banner = "NAME\n\t#{PROGRAM_NAME} -- a command line tool for Aspera Applications (v#{Aspera::Cli::VERSION})\n\n"
         banner << "SYNOPSIS\n"
-        banner << "\t#{self.program_name} COMMANDS [OPTIONS] [ARGS]\n"
-        banner << "\n"
-        banner << "DESCRIPTION\n"
+        banner << "\t#{PROGRAM_NAME} COMMANDS [OPTIONS] [ARGS]\n"
+        banner << "\nDESCRIPTION\n"
         banner << "\tUse Aspera application to perform operations on command line.\n"
         banner << "\tDocumentation and examples: #{@gem_url}\n"
-        banner << "\texecute: #{self.program_name} conf doc\n"
+        banner << "\texecute: #{PROGRAM_NAME} conf doc\n"
         banner << "\tor visit: #{@help_url}\n"
-        banner << "\n"
-        banner << "COMMANDS\n"
-        banner << "\tTo list first level commands, execute: #{self.program_name}\n"
+        banner << "\nENVIRONMENT VARIABLES\n"
+        banner << "\t#{conf_dir_env_var}  config folder, default: $HOME/#{Plugins::Config::ASPERA_HOME_FOLDER_NAME}/#{PROGRAM_NAME}\n"
+        banner << "\t#any option can be set as an environment variable, refer to the manual\n"
+        banner << "\nCOMMANDS\n"
+        banner << "\tTo list first level commands, execute: #{PROGRAM_NAME}\n"
         banner << "\tNote that commands can be written shortened (provided it is unique).\n"
-        banner << "\n"
-        banner << "OPTIONS\n"
+        banner << "\nOPTIONS\n"
         banner << "\tOptions begin with a '-' (minus), and value is provided on command line.\n"
         banner << "\tSpecial values are supported beginning with special prefix, like: #{ExtendedValue.instance.modifiers.map{|m|"@#{m}:"}.join(' ')}.\n"
         banner << "\tDates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'\n\n"
@@ -167,7 +174,7 @@ module Aspera
             # override main option parser with a brand new, to avoid having global options
             plugin_env=@plugin_env.clone
             plugin_env[:man_only]=true
-            plugin_env[:options]=Manager.new(self.program_name,[],'')
+            plugin_env[:options]=Manager.new(PROGRAM_NAME,[],'')
             get_plugin_instance_with_options(plugin_name_sym,plugin_env)
             # display generated help for plugin options
             @plugin_env[:formater].display_message(:error,plugin_env[:options].parser.to_s)
@@ -178,10 +185,14 @@ module Aspera
 
       protected
 
+      def conf_dir_env_var
+        return "#{PROGRAM_NAME}_home".upcase
+      end
+
       # early debug for parser
       # Note: does not accept shortcuts
       def early_debug_setup(argv)
-        Log.instance.program_name=self.program_name
+        Log.instance.program_name=PROGRAM_NAME
         argv.each do |arg|
           case arg
           when '--'
@@ -205,10 +216,6 @@ module Aspera
         return Main.result_nothing
       end
 
-      def options;@opt_mgr;end
-
-      def program_name;PROGRAM_NAME;end
-
       # this is the main function called by initial script just after constructor
       def process_command_line
         Log.log.debug('process_command_line')
@@ -232,6 +239,7 @@ module Aspera
               raise CliError,"Another instance is already running (lock port=#{lock_port})."
             end
           end
+          @plugin_env[:config].periodic_check_newer_gem_version
           if @option_show_config and @opt_mgr.command_or_arg_empty?
             command_sym=Plugins::Config::CONF_PLUGIN_SYM
           else

data/lib/aspera/cli/plugin.rb

@@ -67,7 +67,10 @@ module Aspera
         when :delete
           rest_api.delete(one_res_path)
           return Main.result_status("deleted")
+        else
+          raise "unknown action: #{command}"
         end
+        raise "internal error should not reach here"
       end
 
       # implement generic rest operations on given resource path
@@ -77,13 +80,15 @@ module Aspera
         return entity_command(command,rest_api,res_class_path,display_fields,id_symb,id_default,subkey)
       end
 
-      def options;@agents[:options];end
+      def options; return @agents[:options];end
 
-      def transfer;@agents[:transfer];end
+      def transfer; return @agents[:transfer];end
 
-      def config;return @agents[:config];end
+      def config; return @agents[:config];end
 
-      def format;return @agents[:formater];end
+      def format; return @agents[:formater];end
+
+      def persistency; return @agents[:persistency];end
 
     end # Plugin
   end # Cli

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

@@ -12,7 +12,7 @@ module Aspera
           command=self.options.get_next_command(ACTIONS)
           case command
           when :entitlement
-            entitlement_id = self.options.get_option(:username,:mandatory),
+            entitlement_id = self.options.get_option(:username,:mandatory)
             customer_id = self.options.get_option(:password,:mandatory)
             api_metering=AoC.metering_api(entitlement_id,customer_id)
             return {:type=>:single_object, :data=>api_metering.read('entitlement')[:data]}

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

@@ -3,6 +3,7 @@ require 'aspera/cli/plugins/ats'
 require 'aspera/cli/basic_auth_plugin'
 require 'aspera/cli/transfer_agent'
 require 'aspera/aoc'
+require 'aspera/node'
 require 'aspera/persistency_action_once'
 require 'securerandom'
 require 'resolv'
@@ -12,8 +13,8 @@ module Aspera
   module Cli
     module Plugins
       class Aoc < BasicAuthPlugin
+        # special value for package id
         VAL_ALL='ALL'
-        private_constant :VAL_ALL
         attr_reader :api_aoc
         def initialize(env)
           super(env)
@@ -25,23 +26,22 @@ module Aspera
           @api_aoc=nil
           @url_token_data=nil
           @user_info=nil
-          @ats=Ats.new(@agents)
-          self.options.add_opt_list(:auth,Oauth.auth_types,"type of Oauth authentication")
-          self.options.add_opt_list(:operation,[:push,:pull],"client operation for transfers")
-          self.options.add_opt_simple(:client_id,"API client identifier in application")
-          self.options.add_opt_simple(:client_secret,"API client passcode")
-          self.options.add_opt_simple(:redirect_uri,"API client redirect URI")
-          self.options.add_opt_simple(:private_key,"RSA private key PEM value for JWT (prefix file path with @val:@file:)")
-          self.options.add_opt_simple(:workspace,"name of workspace")
-          self.options.add_opt_simple(:eid,"identifier") # used ?
-          self.options.add_opt_simple(:name,"resource name")
-          self.options.add_opt_simple(:link,"public link to shared resource")
-          self.options.add_opt_simple(:new_user_option,"new user creation option")
-          self.options.add_opt_simple(:from_folder,"share to share source folder")
-          self.options.add_opt_simple(:scope,"scope for AoC API calls")
-          self.options.add_opt_simple(:notify,"notify users that file was received")
-          self.options.add_opt_boolean(:bulk,"bulk operation")
-          self.options.add_opt_boolean(:default_ports,"use standard FASP ports or get from node api")
+          self.options.add_opt_list(:auth,Oauth.auth_types,'type of Oauth authentication')
+          self.options.add_opt_list(:operation,[:push,:pull],'client operation for transfers')
+          self.options.add_opt_simple(:client_id,'API client identifier in application')
+          self.options.add_opt_simple(:client_secret,'API client passcode')
+          self.options.add_opt_simple(:redirect_uri,'API client redirect URI')
+          self.options.add_opt_simple(:private_key,'RSA private key PEM value for JWT (prefix file path with @val:@file:)')
+          self.options.add_opt_simple(:workspace,'name of workspace')
+          self.options.add_opt_simple(:name,'resource name')
+          self.options.add_opt_simple(:path,'file or folder path')
+          self.options.add_opt_simple(:link,'public link to shared resource')
+          self.options.add_opt_simple(:new_user_option,'new user creation option')
+          self.options.add_opt_simple(:from_folder,'share to share source folder')
+          self.options.add_opt_simple(:scope,'scope for AoC API calls')
+          self.options.add_opt_simple(:notify,'notify users that file was received')
+          self.options.add_opt_boolean(:bulk,'bulk operation')
+          self.options.add_opt_boolean(:default_ports,'use standard FASP ports or get from node api')
           self.options.set_option(:bulk,:no)
           self.options.set_option(:default_ports,:yes)
           self.options.set_option(:new_user_option,{'package_contact'=>true})
@@ -52,7 +52,9 @@ module Aspera
           self.options.parse_options!
           AoC.set_use_default_ports(self.options.get_option(:default_ports))
           return if env[:man_only]
-          update_aoc_api
+          @api_aoc=AoC.new(aoc_params('api/v1'))
+          # add access key secrets
+          @api_aoc.add_secrets(self.config.get_secrets)
         end
 
         # call this to populate single AK secret in AoC API object, from options
@@ -65,7 +67,8 @@ module Aspera
           raise CliBadArgument,"Please provide option secret or entry in option secrets for: #{ak}" unless @api_aoc.has_secret(ak) or !mandatory
         end
 
-        def user_info
+        # cached user information
+        def c_user_info
           if @user_info.nil?
             # get our user's default information
             # self?embed[]=default_workspace&embed[]=organization
@@ -80,16 +83,11 @@ module Aspera
         # starts transfer using transfer agent
         def transfer_start(app,direction,node_file,ts_add)
           ts_add.deep_merge!(AoC.analytics_ts(app,direction,@workspace_id,@workspace_name))
-          ts_add.deep_merge!(AoC.console_ts(app,user_info['name'],user_info['email']))
+          ts_add.deep_merge!(AoC.console_ts(app,c_user_info['name'],c_user_info['email']))
           return self.transfer.start(*@api_aoc.tr_spec(app,direction,node_file,ts_add))
         end
 
-        NODE4_COMMANDS=[ :browse, :find, :mkdir, :rename, :delete, :upload, :download, :transfer, :http_node_download, :v3, :file, :bearer_token_node, :permissions  ]
-
-        def node_gen4_execute_action(top_node_file)
-          command_repo=self.options.get_next_command(NODE4_COMMANDS)
-          return execute_node_gen4_command(command_repo,top_node_file)
-        end
+        NODE4_COMMANDS=[ :browse, :find, :mkdir, :rename, :delete, :upload, :download, :transfer, :http_node_download, :v3, :file, :bearer_token_node ]
 
         def execute_node_gen4_command(command_repo,top_node_file)
           case command_repo
@@ -213,69 +211,79 @@ module Aspera
             node_api=@api_aoc.get_node_api(top_node_file[:node_info],AoC::SCOPE_NODE_USER)
             return Node.new(@agents.merge(skip_basic_auth_options: true, node_api: node_api)).execute_action(command_legacy)
           when :file
-            fileid=self.options.get_next_argument('file id')
-            node_file = @api_aoc.resolve_node_file(top_node_file)
-            node_api=@api_aoc.get_node_api(node_file[:node_info],AoC::SCOPE_NODE_USER)
-            items=node_api.read("files/#{fileid}")[:data]
-            return {:type=>:single_object,:data=>items}
-          when :permissions
-            fileid=self.options.get_next_argument('file id')
-            node_file = @api_aoc.resolve_node_file(top_node_file)
+            file_path=self.options.get_option(:path,:optional)
+            node_file = if !file_path.nil?
+              @api_aoc.resolve_node_file(top_node_file,file_path) # TODO: allow follow link ?
+            else
+              {node_info: top_node_file[:node_info],file_id: self.options.get_option(:id,:mandatory)}
+            end
             node_api=@api_aoc.get_node_api(node_file[:node_info],AoC::SCOPE_NODE_USER)
-            command_perms=self.options.get_next_command([:show,:create])
-            case command_perms
+            command_node_file=self.options.get_next_command([:show,:permission,:modify])
+            case command_node_file
             when :show
-              items=node_api.read('permissions',{'include'=>['[]','access_level','permission_count'],'file_id'=>fileid,'inherited'=>false})[:data]
-              return {:type=>:object_list,:data=>items}
-            when :create
-              #value=self.options.get_next_argument('creation value')
-              set_workspace_info
-              access_id="ASPERA_ACCESS_KEY_ADMIN_WS_#{@workspace_id}"
-              node_file[:node_info]
-              params={
-                "file_id"=>fileid,
-                "access_type"=>"user",
-                "access_id"=>access_id,
-                "access_levels"=>["list","read","write","delete","mkdir","rename","preview"],
-                "tags"=>{
-                "aspera"=>{
-                "files"=>{
-                "workspace"=>{
-                "id"=>@workspace_id,
-                "workspace_name"=>@workspace_name,
-                "user_name"=>user_info['name'],
-                "shared_by_user_id"=>user_info['id'],
-                "shared_by_name"=>user_info['name'],
-                "shared_by_email"=>user_info['email'],
-                "shared_with_name"=>access_id,
-                "access_key"=>node_file[:node_info]['access_key'],
-                "node"=>node_file[:node_info]['name']}}}}}
-              item=node_api.create('permissions',params)[:data]
-              return {:type=>:single_object,:data=>item}
-            else raise "error"
+              items=node_api.read("files/#{node_file[:file_id]}")[:data]
+              return {:type=>:single_object,:data=>items}
+            when :modify
+              update_param=self.options.get_next_argument("update data (Hash)")
+              res=node_api.update("files/#{node_file[:file_id]}",update_param)[:data]
+              return {:type=>:single_object,:data=>res}
+            when :permission
+              command_perm=self.options.get_next_command([:list,:create])
+              case command_perm
+              when :list
+                # generic options : TODO: as arg ?
+                list_options||={'include'=>['[]','access_level','permission_count']}
+                # special value: ALL will show all permissions
+                if !VAL_ALL.eql?(node_file[:file_id])
+                  # add which one to get
+                  list_options['file_id']=node_file[:file_id]
+                  list_options['inherited']||=false
+                end
+                #option_url_query
+                items=node_api.read('permissions',list_options)[:data]
+                return {:type=>:object_list,:data=>items}
+              when :create
+                #create_param=self.options.get_next_argument("creation data (Hash)")
+                set_workspace_info
+                access_id="ASPERA_ACCESS_KEY_ADMIN_WS_#{@workspace_id}"
+                node_file[:node_info]
+                params={
+                  'file_id'      =>node_file[:file_id], # mandatory
+                  'access_type'  =>'user', # mandatory: user or group
+                  'access_id'    =>access_id, # id of user or group
+                  'access_levels'=>Aspera::Node::ACCESS_LEVELS,
+                  'tags'         =>{'aspera'=>{'files'=>{'workspace'=>{
+                  'id'               =>@workspace_id,
+                  'workspace_name'   =>@workspace_name,
+                  'user_name'        =>c_user_info['name'],
+                  'shared_by_user_id'=>c_user_info['id'],
+                  'shared_by_name'   =>c_user_info['name'],
+                  'shared_by_email'  =>c_user_info['email'],
+                  'shared_with_name' =>access_id,
+                  'access_key'       =>node_file[:node_info]['access_key'],
+                  'node'             =>node_file[:node_info]['name']}}}}}
+                item=node_api.create('permissions',params)[:data]
+                return {:type=>:single_object,:data=>item}
+              else raise "internal error:shall not reach here (#{command_perm})"
+              end
+              raise "internal error:shall not reach here"
+            else raise "internal error:shall not reach here (#{command_node_file})"
             end
+            raise "internal error:shall not reach here"
+          when :permissions
+
           end # command_repo
-          throw "ERR"
+          raise "ERR"
         end # execute_node_gen4_command
 
         # build constructor option list for AoC based on options of CLI
         def aoc_params(subpath)
           # copy command line options to args
-          opt=[:link,:url,:auth,:client_id,:client_secret,:scope,:redirect_uri,:private_key,:username].inject({}){|m,i|m[i]=self.options.get_option(i,:optional);m}
+          opt=[:link,:url,:auth,:client_id,:client_secret,:scope,:redirect_uri,:private_key,:username,:password].inject({}){|m,i|m[i]=self.options.get_option(i,:optional);m}
           opt[:subpath]=subpath
           return opt
         end
 
-        # Create a new AoC API REST object and set @api_aoc.
-        # Parameters based on command line options
-        # @return nil
-        def update_aoc_api
-          @api_aoc=AoC.new(aoc_params('api/v1'))
-          # add access key secrets
-          @api_aoc.add_secrets(self.config.get_secrets)
-          return nil
-        end
-
         # initialize apis and authentication
         # set:
         # @default_workspace_id
@@ -290,8 +298,8 @@ module Aspera
             @default_workspace_id=@url_token_data['data']['workspace_id']
             @persist_ids=[] # TODO : @url_token_data['id'] ?
           else
-            @default_workspace_id=user_info['default_workspace_id']
-            @persist_ids=[user_info['id']]
+            @default_workspace_id=c_user_info['default_workspace_id']
+            @persist_ids=[c_user_info['id']]
           end
 
           ws_name=self.options.get_option(:workspace,:optional)
@@ -401,7 +409,8 @@ module Aspera
           package_creation[recipient_list_field]=resolved_list
         end
 
-        def url_query(default)
+        # private
+        def option_url_query(default)
           query=self.options.get_option(:query,:optional)||default
           Log.log.debug("Query=#{query}".bg_red)
           begin
@@ -420,8 +429,7 @@ module Aspera
         end
 
         def execute_admin_action
-          self.options.set_option(:scope,AoC::SCOPE_FILES_ADMIN)
-          update_aoc_api
+          @api_aoc.oauth.params[:scope]=AoC::SCOPE_FILES_ADMIN
           command_admin=self.options.get_next_command([ :ats, :resource, :usage_reports, :analytics, :subscription, :auth_providers ])
           case command_admin
           when :auth_providers
@@ -490,20 +498,7 @@ module Aspera
               :base_url => @api_aoc.params[:base_url]+'/admin/ats/pub/v1',
               :auth     => {:scope => AoC::SCOPE_FILES_ADMIN_USER}
             }))
-            return @ats.execute_action_gen(ats_api)
-            #          when :search_nodes
-            #            query=self.options.get_option(:query,:optional) || '*'
-            #            nodes=@api_aoc.read("search_nodes",{'q'=>query})[:data]
-            #            # simplify output
-            #            nodes=nodes.map do |i|
-            #              item=i['_source']
-            #              item['score']=i['_score']
-            #              nodedata=item['access_key_recursive_counts'].first
-            #              item.delete('access_key_recursive_counts')
-            #              item['node']=nodedata
-            #              item
-            #            end
-            #            return {:type=>:object_list,:data=>nodes,:fields=>['host_name','node_status.cluster_id','node_status.node_id']}
+            return Ats.new(@agents).execute_action_gen(ats_api)
           when :analytics
             analytics_api = Rest.new(@api_aoc.params.deep_merge({
               :base_url => @api_aoc.params[:base_url].gsub('/api/v1','')+'/analytics/v2',
@@ -513,19 +508,20 @@ module Aspera
             case command_analytics
             when :application_events
               event_type=command_analytics.to_s
-              events=analytics_api.read("organizations/#{user_info['organization_id']}/#{event_type}")[:data][event_type]
+              events=analytics_api.read("organizations/#{c_user_info['organization_id']}/#{event_type}")[:data][event_type]
               return {:type=>:object_list,:data=>events}
             when :transfers
               event_type=command_analytics.to_s
               filter_resource=self.options.get_option(:name,:optional) || 'organizations'
               filter_id=self.options.get_option(:id,:optional) || case filter_resource
-              when 'organizations'; user_info['organization_id']
-              when 'users'; user_info['id']
-              when 'nodes'; user_info['id']
+              when 'organizations'; c_user_info['organization_id']
+              when 'users'; c_user_info['id']
+              when 'nodes'; c_user_info['id']
               else raise "organizations or users for option --name"
               end
               #
               filter=self.options.get_option(:query,:optional) || {}
+              raise "query must be Hash" unless filter.is_a?(Hash)
               filter['limit']||=100
               if self.options.get_option(:once_only,:mandatory)
                 saved_date=[]
@@ -542,7 +538,7 @@ module Aspera
                 filter['stop_time'] = stop_datetime
               end
               notification=self.options.get_option(:notify,:optional)
-              events=analytics_api.read("#{filter_resource}/#{filter_id}/#{event_type}",url_query(filter))[:data][event_type]
+              events=analytics_api.read("#{filter_resource}/#{filter_id}/#{event_type}",option_url_query(filter))[:data][event_type]
               startdate_persistency.save unless startdate_persistency.nil?
               if !notification.nil?
                 require 'erb'
@@ -581,7 +577,7 @@ module Aspera
             supported_operations.push(:delete,*global_operations) unless singleton_object
             supported_operations.push(:v4,:v3) if resource_type.eql?(:node)
             supported_operations.push(:set_pub_key) if resource_type.eql?(:client)
-            supported_operations.push(:shared_folders) if [:node,:workspace].include?(resource_type)
+            supported_operations.push(:shared_folders,:shared_create) if [:node,:workspace].include?(resource_type)
             command=self.options.get_next_command(supported_operations)
             # require identifier for non global commands
             if !singleton_object and !global_operations.include?(command)
@@ -624,8 +620,10 @@ module Aspera
               when :apps_new; list_query={:organization_apps=>true};default_fields=['app_type','available']
               when :client_registration_token; default_fields=['id','value','data.client_subject_scopes','created_at']
               end
-              result=@api_aoc.read(resource_class_path,url_query(list_query))
-              self.format.display_status("Items: #{result[:data].length}/#{result[:http]['X-Total-Count']}")
+              result=@api_aoc.read(resource_class_path,option_url_query(list_query))
+              count_msg="Items: #{result[:data].length}/#{result[:http]['X-Total-Count']}"
+              count_msg=count_msg.bg_red unless result[:data].length.eql?(result[:http]['X-Total-Count'].to_i)
+              self.format.display_status(count_msg)
               return {:type=>:object_list,:data=>result[:data],:fields=>default_fields}
             when :show
               object=@api_aoc.read(resource_instance_path)[:data]
@@ -652,7 +650,8 @@ module Aspera
               api_node=@api_aoc.get_node_api(res_data)
               return Node.new(@agents.merge(skip_basic_auth_options: true, node_api: api_node)).execute_action if command.eql?(:v3)
               ak_data=api_node.call({:operation=>'GET',:subpath=>"access_keys/#{res_data['access_key']}",:headers=>{'Accept'=>'application/json'}})[:data]
-              return node_gen4_execute_action({node_info: res_data, file_id: ak_data['root_file_id']})
+              command_repo=self.options.get_next_command(NODE4_COMMANDS)
+              return execute_node_gen4_command(command_repo,{node_info: res_data, file_id: ak_data['root_file_id']})
             when :shared_folders
               read_params = case resource_type
               when :workspace;{'access_id'=>"ASPERA_ACCESS_KEY_ADMIN_WS_#{res_id}",'access_type'=>'user'}
@@ -663,16 +662,48 @@ module Aspera
               fields=case resource_type
               when :node;['id','file_id','file.path','access_type']
               when :workspace;['id','node_id','file_id','node_name','file.path','tags.aspera.files.workspace.share_as']
-              else raise "error"
+              else raise "unexpected resource type #{resource_type}"
               end
               return { :type=>:object_list, :data =>res_data , :fields=>fields}
-            else raise :ERROR
+            when :shared_create
+              # TODO
+              folder_path=self.options.get_next_argument('folder path in node')
+              user_create_data=self.options.get_next_argument('creation data (Hash)')
+              res_data=@api_aoc.read(resource_instance_path)[:data]
+              node_file = @api_aoc.resolve_node_file({node_info: res_data, file_id: ak_data['root_file_id']},folder_path)
+
+              #node_api=@api_aoc.get_node_api(node_file[:node_info],AoC::SCOPE_NODE_USER)
+              #file_info = node_api.read("files/#{node_file[:file_id]}")[:data]
+
+              access_id="ASPERA_ACCESS_KEY_ADMIN_WS_#{@workspace_id}"
+              create_data={
+                'file_id'      =>node_file[:file_id],
+                'access_type'  =>'user',
+                'access_id'    =>access_id,
+                'access_levels'=>['list','read','write','delete','mkdir','rename','preview'],
+                'tags'         =>{'aspera'=>{'files'=>{'workspace'=>{
+                'id'               =>@workspace_id,
+                'workspace_name'   =>@workspace_name,
+                'share_as'         =>File.basename(folder_path),
+                'user_name'        =>c_user_info['name'],
+                'shared_by_user_id'=>c_user_info['id'],
+                'shared_by_name'   =>c_user_info['name'],
+                'shared_by_email'  =>c_user_info['email'],
+                'shared_with_name' =>access_id,
+                'access_key'       =>node_file[:node_info]['access_key'],
+                'node'             =>node_file[:node_info]['name']}
+                }}}}
+              create_data.deep_merge!(user_create_data)
+              Log.dump(:data,create_data)
+              raise :ERROR
+            else raise "unknown command"
             end
           when :usage_reports
-            return {:type=>:object_list,:data=>@api_aoc.read("usage_reports",{:workspace_id=>@workspace_id})[:data]}
+            return {:type=>:object_list,:data=>@api_aoc.read('usage_reports',{:workspace_id=>@workspace_id})[:data]}
           end
         end
 
+        # must be public
         ACTIONS=[ :apiinfo, :bearer_token, :organization, :tier_restrictions, :user, :workspace, :packages, :files, :gateway, :admin, :automation, :servers]
 
         def execute_action
@@ -693,23 +724,23 @@ module Aspera
             command=self.options.get_next_command([ :workspaces,:info,:shared_inboxes ])
             case command
             when :workspaces
-              return {:type=>:object_list,:data=>@api_aoc.read("workspaces")[:data],:fields=>['id','name']}
+              return {:type=>:object_list,:data=>@api_aoc.read('workspaces')[:data],:fields=>['id','name']}
               #              when :settings
               #                return {:type=>:object_list,:data=>@api_aoc.read("client_settings/")[:data]}
             when :shared_inboxes
-              query=url_query(nil)
+              query=option_url_query(nil)
               if query.nil?
                 set_workspace_info
                 query={'embed[]'=>'dropbox','workspace_id'=>@workspace_id,'aggregate_permissions_by_dropbox'=>true,'sort'=>'dropbox_name'}
               end
-              return {:type=>:object_list,:data=>@api_aoc.read("dropbox_memberships",query)[:data],:fields=>['dropbox_id','dropbox.name']}
+              return {:type=>:object_list,:data=>@api_aoc.read('dropbox_memberships',query)[:data],:fields=>['dropbox_id','dropbox.name']}
             when :info
               command=self.options.get_next_command([ :show,:modify ])
               case command
               when :show
-                return { :type=>:single_object, :data =>user_info }
+                return { :type=>:single_object, :data =>c_user_info }
               when :modify
-                @api_aoc.update("users/#{user_info['id']}",self.options.get_next_argument('modified parameters (hash)'))
+                @api_aoc.update("users/#{c_user_info['id']}",self.options.get_next_argument('modified parameters (hash)'))
                 return Main.result_status('modified')
               end
             end
@@ -722,7 +753,7 @@ module Aspera
             case command_pkg
             when :send
               package_creation=self.options.get_option(:value,:mandatory)
-              raise CliBadArgument,"value must be hash, refer to doc" unless package_creation.is_a?(Hash)
+              raise CliBadArgument,'value must be hash, refer to doc' unless package_creation.is_a?(Hash)
 
               if !@url_token_data.nil?
                 assert_public_link_types(['send_package_to_user','send_package_to_dropbox'])
@@ -803,12 +834,12 @@ module Aspera
               return { :type=>:single_object, :data =>package_info }
             when :list
               # list all packages ('page'=>1,'per_page'=>10,)'sort'=>'-sent_at',
-              packages=@api_aoc.read("packages",{'archived'=>false,'exclude_dropbox_packages'=>true,'has_content'=>true,'received'=>true,'workspace_id'=>@workspace_id})[:data]
+              packages=@api_aoc.read('packages',{'archived'=>false,'exclude_dropbox_packages'=>true,'has_content'=>true,'received'=>true,'workspace_id'=>@workspace_id})[:data]
               return {:type=>:object_list,:data=>packages,:fields=>['id','name','bytes_transferred']}
             when :delete
               list_or_one=self.options.get_option(:id,:mandatory)
               return do_bulk_operation(list_or_one,'deleted')do|id|
-                raise "expecting String identifier" unless id.is_a?(String) or id.is_a?(Integer)
+                raise 'expecting String identifier' unless id.is_a?(String) or id.is_a?(Integer)
                 @api_aoc.delete("packages/#{id}")[:data]
               end
             end
@@ -829,7 +860,7 @@ module Aspera
               when 'private'
                 value_option={'purpose'=>'shared_folder_auth_link'}
               when NilClass,Hash
-              else raise "value must be either: public, private, Hash or nil"
+              else raise 'value must be either: public, private, Hash or nil'
               end
               create_params=nil
               node_file=nil
@@ -857,30 +888,33 @@ module Aspera
                   }
                   value_option['user_selected_name']=nil
                 else
-                  raise "purpose must be one of: token_auth_redirection or shared_folder_auth_link"
+                  raise 'purpose must be one of: token_auth_redirection or shared_folder_auth_link'
                 end
                 self.options.set_option(:value,value_option)
               end
               result=self.entity_action(@api_aoc,'short_links',nil,:id,'self')
               if result[:data].is_a?(Hash) and result[:data].has_key?('created_at') and result[:data]['resource_type'].eql?('UrlToken')
                 node_api=@api_aoc.get_node_api(node_file[:node_info],AoC::SCOPE_NODE_USER)
+                # TODO: access level as arg
+                access_levels=Aspera::Node::ACCESS_LEVELS #['delete','list','mkdir','preview','read','rename','write']
                 perm_data={
-                  "file_id"      =>node_file[:file_id],
-                  "access_type"  =>"user",
-                  "access_id"    =>result[:data]['resource_id'],
-                  "access_levels"=>["delete","list","mkdir","preview","read","rename","write"],
-                  "tags"         =>{
-                  "url_token"       =>true,
-                  "workspace_id"    =>@workspace_id,
-                  "workspace_name"  =>@workspace_name,
-                  "folder_name"     =>"my folder",
-                  "created_by_name" =>user_info['name'],
-                  "created_by_email"=>user_info['email'],
-                  "access_key"      =>node_file[:node_info]['access_key'],
-                  "node"            =>node_file[:node_info]['host']
+                  'file_id'      =>node_file[:file_id],
+                  'access_type'  =>'user',
+                  'access_id'    =>result[:data]['resource_id'],
+                  'access_levels'=>access_levels,
+                  'tags'         =>{
+                  'url_token'       =>true,
+                  'workspace_id'    =>@workspace_id,
+                  'workspace_name'  =>@workspace_name,
+                  'folder_name'     =>'my folder',
+                  'created_by_name' =>c_user_info['name'],
+                  'created_by_email'=>c_user_info['email'],
+                  'access_key'      =>node_file[:node_info]['access_key'],
+                  'node'            =>node_file[:node_info]['host']
                   }
                 }
                 node_api.create("permissions?file_id=#{node_file[:file_id]}",perm_data)
+                # TODO: event ?
               end
               return result
             end # files command
@@ -923,17 +957,20 @@ module Aspera
           when :admin
             return execute_admin_action
           when :servers
-            self.format.display_status("Beta feature")
-            server_api=Rest.new(base_url: 'https://eudemo.asperademo.com')
-            require 'json'
-            servers=JSON.parse(server_api.read('servers')[:data])
+            self.format.display_status("Beta feature: #{@api_aoc.params[:base_url]}")
+            server_api=Rest.new(base_url: @api_aoc.params[:base_url])
+            servers=server_api.read('servers')[:data]
             return {:type=>:object_list,:data=>servers}
           else
             raise "internal error: #{command}"
           end # action
           raise RuntimeError, "internal error: command shall return"
         end
-      end # Aspera
+
+        private :find_ak_secret,:c_user_info,:aoc_params,:set_workspace_info,:set_home_node_file,:do_bulk_operation,:resolve_package_recipients,:option_url_query,:assert_public_link_types,:execute_admin_action
+        private_constant :VAL_ALL,:NODE4_COMMANDS
+
+      end # AoC
     end # Plugins
   end # Cli
 end # Aspera