aspera-cli 4.27.3 → 4.27.5

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

@@ -8,6 +8,7 @@ require 'aspera/cli/extended_value'
 require 'aspera/cli/special_values'
 require 'aspera/cli/version'
 require 'aspera/cli/formatter'
+require 'aspera/cli/http'
 require 'aspera/cli/info'
 require 'aspera/cli/wizard'
 require 'aspera/cli/sync_actions'
@@ -99,16 +100,15 @@ module Aspera
         option :cache_tokens,       description: 'Save and reuse OAuth tokens', allowed: Type::BOOLEAN, default: true
         option :expand_mounts,      description: 'Commands: list commands of sub-trees provided by another plugin', allowed: Type::BOOLEAN, default: false
         option :no_default,         description: 'Do not load default configuration for plugin', allowed: Type::NONE, short: 'N', on_set: -> { presets.use_plugin_defaults = false }
+        use_options Wizard
+        # `on_set` callbacks of HTTP options are methods of `http_config`
+        use_options Http, target: -> { http_config }
 
         def initialize(**_)
           super
           @vault_instance = nil
           @sdk_default_location = false
-          # Declare wizard options (Wizard#initialize calls options.declare internally)
           @wizard = Wizard.new(self, context.main_folder)
-          # HTTP options: declare metadata (class method), then bind to the instance
-          Http.declare_options(options)
-          context.http_config.bind_options(options)
           # Values set through `on_set` callbacks are used below (sdk_folder)
           options.parse_options!
           set_sdk_dir
@@ -186,7 +186,8 @@ module Aspera
                       {name: :preset_name, mandatory: false, default: ''}],
           action: lambda do |url:, plugin_name: nil, preset_name: '', **|
             apps = @wizard.identify_plugins_for_url(url: url, plugin_name: plugin_name).freeze
-            @wizard.find(apps, preset_name: preset_name)
+            # The product wizard prompts for missing mandatory options (username, password, ...)
+            options.with_interactive { @wizard.find(apps, preset_name: preset_name) }
           end
         )
         command :coffee, description: 'Show a coffee image', action: ->(**) { Result::Image.new(COFFEE_IMAGE_URL) }
@@ -396,8 +397,7 @@ module Aspera
               Result::ObjectList.new(builder.rows, fields: builder.columns)
             end
           )
-          command :admin, description: 'Manage sync database (admin operations)'
-          SyncActions.register_sync_admin_commands(self, :admin)
+          sync_admin_commands :admin
           command :translate, description: 'Translate async-style arguments to sync config format',
             arguments: [{name: :async_arguments, multiple: true}],
             action: ->(async_arguments:, **) { Result::SingleObject.new(Sync::Operations.args_to_conf(async_arguments)) }
@@ -493,7 +493,7 @@ module Aspera
 
         def action_download(file_url:, file_dest: nil, **)
           file_url = file_url.chomp
-          file_dest = File.join(transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE), file_url.gsub(%r{.*/}, '')) if file_dest.nil?
+          file_dest = File.join(transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE), file_url.rpartition('/').last) if file_dest.nil?
           Log.log.info("Downloading: #{file_url}")
           Rest::Client.new(base_url: file_url).call(operation: 'GET', save_to: file_dest)
           Result::Status.new("Saved to: #{file_dest}")
@@ -569,12 +569,12 @@ module Aspera
             Aspera.assert_values(plugin_name.to_sym, plugin_names, type: Cli::BadArgument)
             plugin_names = [plugin_name.to_sym]
           end
-          prefix = Array(command_path).map(&:to_sym)
-          Aspera.assert(prefix.empty? || plugin_names.length.eql?(1), type: Cli::BadArgument) { 'command path requires a plugin name' }
+          words = Array(command_path).map(&:to_sym)
+          Aspera.assert(words.empty? || plugin_names.length.eql?(1), type: Cli::BadArgument) { 'command path requires a plugin name' }
           expand_mounts = options.get_option(:expand_mounts)
           commands = plugin_names.flat_map do |name|
             reg = Plugins::Factory.instance.plugin_class(name).command_registry
-            Aspera.assert(prefix.empty? || reg[prefix], type: Cli::BadArgument) { "no such command: #{name} #{prefix.join(' ')}" }
+            prefix = listed_command_path(name, reg, words)
             paths = prefix.empty? || reg.children_of(prefix).any? ? reg.leaf_paths(prefix, expand_mounts: expand_mounts) : [prefix]
             paths.map do |path|
               mount = expand_mounts ? nil : reg.mount_at(path)
@@ -592,6 +592,19 @@ module Aspera
           Result::ObjectList.new(commands, fields: %w[syntax description])
         end
 
+        # Command path to list, from words that may include positional arguments, as on a command line.
+        # e.g. `faspex5 packages receive ALL` lists `faspex5 packages receive`.
+        # @param name  [Symbol]          plugin name
+        # @param reg   [CommandRegistry] registry of plugin
+        # @param words [Array<Symbol>]   sub-commands (or aliases), possibly mixed with their arguments
+        # @return [Array<Symbol>] command path
+        # @raise [Cli::BadArgument] if a word is neither a sub-command nor an expected argument
+        def listed_command_path(name, reg, words)
+          path, unknown = reg.command_path(words)
+          raise Cli::BadArgument, Parser.multi_choice_assert_msg("no such command: #{[name, *path, unknown].join(' ')}", reg.children_of(path).keys) unless unknown.nil?
+          path
+        end
+
         # Build syntax by interleaving each path segment with the arguments declared on that node
         # @param name [String, Symbol]       plugin name
         # @param reg  [CommandRegistry]      registry of plugin

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

@@ -63,7 +63,7 @@ module Aspera
               username: options.get_option(:username, mandatory: true),
               password: options.get_option(:password, mandatory: true)
             },
-            test_args:    'transfer list'
+            test_args:    'transfer current list'
           }
         end
 

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

@@ -16,6 +16,8 @@ require 'aspera/nagios'
 require 'aspera/environment'
 require 'aspera/assert'
 require 'securerandom'
+require 'digest'
+require 'json'
 require 'aspera/rainbow'
 using Rainbow
 
@@ -143,7 +145,7 @@ module Aspera
             end
             if status_list.include?(status['upload_status'])
               progress_bar&.event(:session_end, session_id: id)
-              progress_bar&.event(:end)
+              progress_bar&.event(:end, info: !status['upload_status'].eql?('failed'))
               return status
             end
             sleep(1.0)
@@ -195,13 +197,25 @@ module Aspera
         # Build query to get package recipients based on package info in case of shared inbox or workgroup recipient
         # @param package_id [String] the package id to get info from
         def recipient_query(package_id)
+          # With a public link, the recipient context is already encoded in the auth token: no extra query params needed
+          return {} if api_v5.pub_link_context
           package_info = api_v5.read("packages/#{package_id}")
           base_query = {}
-          base_query['recipient_workgroup_id'] = package_info['recipients'].first['id'] if WORKGROUP_TYPES.include?(package_info['recipients'].first['recipient_type'])
-          base_query['recipient_user_id'] = package_info['recipients'].first['id'] if package_info['recipients'].first['recipient_type'].eql?('user')
+          first_recipient = package_info['recipients']&.first
+          if first_recipient
+            base_query['recipient_workgroup_id'] = first_recipient['id'] if WORKGROUP_TYPES.include?(first_recipient['recipient_type'])
+            base_query['recipient_user_id'] = first_recipient['id'] if first_recipient['recipient_type'].eql?('user')
+          end
           base_query
         end
 
+        # @return [String] user part of the persistency id of received packages:
+        #   the username, or for a public link (no username), a digest of the link context (unique per link)
+        def persistency_user_id
+          return options.get_option(:username, mandatory: true) if api_v5.pub_link_context.nil?
+          Digest::SHA256.hexdigest(JSON.generate(api_v5.pub_link_context))[0, 16]
+        end
+
         def package_receive(package_ids)
           # prepare persistency if needed
           skip_ids_persistency = nil
@@ -213,7 +227,7 @@ module Aspera
               id:      IdGenerator.from_list(
                 'faspex_recv',
                 options.get_option(:url, mandatory: true),
-                options.get_option(:username, mandatory: true),
+                persistency_user_id,
                 options.get_option(:box, mandatory: true)
               )
             )
@@ -229,7 +243,7 @@ module Aspera
             # TODO: if packages have same name, they will overwrite ?
             packages, max_items = list_packages_with_filter(query: {'status' => 'completed'}) # no filter: all completed packages
             Log.dump(:package_ids, level: :trace1) { packages.map { |p| p['id'] } }
-            Log.dump(:skip_ids, skip_ids_persistency.data, level: :trace1)
+            Log.dump(:skip_ids, skip_ids_persistency&.data, level: :trace1)
             packages.reject! { |p| skip_ids_persistency.data.include?(p['id']) } if skip_ids_persistency
             # Apply `max` after once_only filtering so we get the N first not-yet-downloaded packages
             packages = packages[0, max_items] if max_items
@@ -240,11 +254,13 @@ module Aspera
             Aspera.assert_array_all(package_ids, String) { 'Package id(s)' }
             # packages = package_ids.map{|pkg_id|api_v5.read("packages/#{pkg_id}")}
             packages = package_ids.map { |pkg_id| {'id'=>pkg_id} }
+            # The package of a public link is received only once, like with `ALL`
+            packages.reject! { |p| skip_ids_persistency.data.include?(p['id']) } if skip_ids_persistency && api_v5.pub_link_context
           end
           result_transfer = []
           param_file_list = {}
           begin
-            param_file_list['paths'] = transfer.ts_source_paths
+            param_file_list['paths'] = transfer.ts_source_paths.map { |p| {'path' => p['source']} }
           rescue Cli::MissingArgument
             # paths is optional
           end
@@ -305,7 +321,8 @@ module Aspera
             )
             # well, we asked a TS for connect, but we actually want a generic one
             transfer_spec.delete('authentication')
-            return Runner.result_transfer(transfer.start(transfer_spec))
+            Runner.result_transfer(transfer.start(transfer_spec))
+            return Result::SingleObject.new(package)
           else
             # send from remote shared folder
             if (m = Parser.percent_selector(shared_folder))
@@ -493,7 +510,7 @@ module Aspera
             arguments: [{name: :package, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::FASPEX, 'packages.post')}],
             action: ->(package:, **) { package_send(package) }
           command :show,   description: 'Show a package', setup: :setup_package_id, arguments: PACKAGE_ID_ARG,
-            action: ->(package_id:, **) { Result::SingleObject.new(api_v5.read("packages/#{package_id}")) }
+            action: ->(package_id:, **) { Result::SingleObject.new(api_v5.read("packages/#{package_id}", query_read_delete)) }
           command :browse, description: 'Browse package files', setup: :setup_package_id,
             arguments: PACKAGE_ID_ARG + [{name: :folder_path, mandatory: false, default: '/'}],
             action: ->(folder_path:, package_id:, **) { browse_folder("packages/#{package_id}/files/#{Api::Faspex.box_type(options.get_option(:box))}", recipient_query(package_id), folder_path: folder_path) }
@@ -833,9 +850,11 @@ module Aspera
             res_path = "#{res_instance_path}/members"
             api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
           end
-          define_method(:"lookup_#{res}_saml_groups_id") do |field, value, res_instance_path:, **|
-            res_path = "#{res_instance_path}/saml_groups"
-            api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
+          # Like members (`user_id`), a SAML group of the resource is identified by `group_id`; its name is `group_name`
+          define_method(:"lookup_#{res}_saml_groups_id") do |field, value, saml_groups_path:, **|
+            field = 'group_name' if field.eql?('name')
+            query = field.eql?('group_name') ? {'q' => value} : {}
+            api_v5.lookup_entity_by_field(entity: saml_groups_path, field: field, value: value, items_key: 'groups', query: query)['group_id']
           end
         end
 

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

@@ -33,7 +33,7 @@ module Aspera
             preset_value: {
               url: app_url
             },
-            test_args:    'info'
+            test_args:    'bridges list'
           }
         end
 

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

@@ -11,7 +11,6 @@ require 'aspera/hash_ext'
 require 'aspera/id_generator'
 require 'aspera/api/node'
 require 'aspera/oauth'
-require 'aspera/node_simulator'
 require 'aspera/rest/list'
 require 'aspera/assert'
 require 'base64'
@@ -356,8 +355,7 @@ module Aspera
           Sync::Operations::DIRECTIONS.each do |dir|
             command dir, description: "#{dir.capitalize}-sync (Gen3)", transfer_paths: :send, arguments: SyncActions::PATH_AND_INFO_ARGS
           end
-          command :admin, description: 'Manage sync database (admin operations)'
-          SyncActions.register_sync_admin_commands(self, :admin)
+          sync_admin_commands :admin
         end
         # access_keys sub-tree
         command :access_keys, description: 'Manage access keys'
@@ -387,8 +385,7 @@ module Aspera
             Sync::Operations::DIRECTIONS.each do |dir|
               command dir, description: "#{dir.capitalize}-sync", transfer_paths: :send, arguments: SyncActions::PATH_AND_INFO_ARGS
             end
-            command :admin, description: 'Manage sync database (admin operations)'
-            SyncActions.register_sync_admin_commands(self, :admin)
+            sync_admin_commands :admin
           end
         end
         commands_under %i[access_keys do permission] do
@@ -591,8 +588,9 @@ module Aspera
             Result::Text.new(Api::Node.bearer_token(payload: token, access_key: access_key, private_key: private_key))
           end
         )
-        command :simulator,     description: 'Start node simulator',
-          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}, schema: 'opts:components.schemas.NodeSimulatorOptions'}]
+        command :emulator,      description: 'Start node emulator',
+          aliases: [:simulator],
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}, schema: Schema::Registry::NODE_EMULATOR_OPTIONS}]
         command :telemetry,     description: 'Report telemetry to external system',
           arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}, schema: 'opts:components.schemas.NodeTelemetryOptions'}]
 
@@ -655,7 +653,7 @@ module Aspera
             transfer_spec = api_node.create(
               'files/sync_setup',
               {transfer_requests: [{transfer_request: request_transfer_spec}]}
-            )['transfer_specs'].first['transfer_spec']
+            )['transfer_specs'].first&.fetch('transfer_spec')
             transfer_spec.delete_if { |_k, v| v.nil? }
             Log.dump(:ts, transfer_spec)
             transfer_spec
@@ -663,7 +661,7 @@ module Aspera
         end
 
         Sync::Operations::DIRECTIONS.each do |dir|
-          define_method(:"action_sync_#{dir}") { |path:, sync_info: {}, **| run_sync_transfer(dir, path: path, sync_info: sync_info, &sync_gen3_block) }
+          define_action_method([:sync, dir]) { |path:, sync_info: {}, **| run_sync_transfer(dir, path: path, sync_info: sync_info, &sync_gen3_block) }
         end
 
         def action_upload(**)
@@ -674,7 +672,7 @@ module Aspera
           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']
+          transfer_spec = api_node.create('files/upload_setup', setup_payload)['transfer_specs'].first&.fetch('transfer_spec')
           Api::Node.add_private_key(transfer_spec)
           transfer_spec.delete('paths')
           Runner.result_transfer(transfer.start(transfer_spec))
@@ -688,7 +686,7 @@ module Aspera
           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']
+          transfer_spec = api_node.create('files/download_setup', setup_payload)['transfer_specs'].first&.fetch('transfer_spec')
           Api::Node.add_private_key(transfer_spec)
           Runner.result_transfer(transfer.start(transfer_spec))
         end
@@ -824,7 +822,7 @@ module Aspera
         end
 
         Sync::Operations::DIRECTIONS.each do |dir|
-          define_method(:"action_access_keys_do_sync_#{dir}") do |path:, sync_info: {}, do_root_file_id:, **|
+          define_action_method([:access_keys, :do, :sync, dir]) do |path:, sync_info: {}, do_root_file_id:, **|
             run_sync_transfer(dir, path: path, sync_info: sync_info, &sync_gen4_block(do_root_file_id))
           end
         end
@@ -1015,7 +1013,7 @@ module Aspera
 
         def action_async_counters(async_id:, **)
           Integer(async_id)
-          resp = api_node.create('async/counters', {'syncs' => [async_id]})['sync_counters'].first[async_id].last
+          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
@@ -1131,14 +1129,23 @@ module Aspera
           return Result::Status.new('done')
         end
 
-        def action_simulator(parameters: {}, **)
-          require 'aspera/node_simulator'
-          parameters = parameters.symbolize_keys
-          uri = URI.parse(parameters.delete(:url) { WebServerSimple::DEFAULT_URL })
+        def action_emulator(parameters: {}, **)
+          require 'aspera/node_emulator'
+          # missing parameters take the default of the schema
+          defaults = Schema::Registry.instance.reader(Schema::Registry::NODE_EMULATOR_OPTIONS).current['properties'].each_with_object({}) do |(name, property), result|
+            result[name.to_sym] = property['default'] if property.key?('default')
+          end
+          parameters = defaults.merge(parameters.symbolize_keys)
+          uri = URI.parse(parameters.delete(:url))
+          config = parameters.except(*WebServerSimple::PARAMS)
+          docroot = config.delete(:docroot)
+          retention_sec = config.delete(:retention_sec)
+          Aspera.assert(config[:username].nil? == config[:password].nil?, type: Cli::BadArgument) { 'Parameters username and password must be set together' }
+          Log.log.warn('No username and password: emulator accepts requests without authentication') if config[:username].nil?
           server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-          server.mount(uri.path, NodeSimulatorServlet, parameters.except(*WebServerSimple::PARAMS), NodeSimulator.new)
+          server.mount(uri.path, NodeEmulatorServlet, config, NodeEmulator.new(docroot: docroot, retention_sec: retention_sec))
           server.start
-          return Result::Status.new('Simulator terminated')
+          return Result::Status.new('Emulator terminated')
         end
 
         def action_telemetry(parameters: {}, **)

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

@@ -52,36 +52,37 @@ module Aspera
               username: options.get_option(:username, mandatory: true),
               password: options.get_option(:password, mandatory: true)
             },
-            test_args:    'workflow list'
+            test_args:    'workflows list'
           }
         end
 
+        option :apikey,      description: 'API key (exclusive with username/password)'
+        option :auth_style,  description: 'Authentication style', allowed: %i[basic query token], default: :token
+        option :ret_style,   description: 'Method to specify the expected response format ("Accept")', allowed: %i[header query path], default: :query
         option :result,      description: "Specify result value as: 'work_step:parameter'", deprecation: {last: '4.27.2', message: 'use keys `step` and `variable` of argument `execution` of `workflows start`'}
         option :synchronous, description: 'Wait for completion', allowed: Type::BOOLEAN, deprecation: {last: '4.27.2', message: 'use key `synchronous` of argument `execution` of `workflows start`'}
-        option :ret_style,   description: 'How return type is requested in api', allowed: %i[header arg ext], default: :arg
-        option :auth_style,  description: 'Authentication type', allowed: %i[arg_pass head_basic apikey], default: :head_basic
 
-        # Call orchestrator API, it's a bit special
+        # Call orchestrator API (handles ret_style negotiation and XML parsing)
         # @param endpoint   [String]  the endpoint to call
-        # @param ret_style  [Symbol]  the return style, :header, :arg, :ext(extension)
+        # @param body       [Hash]    the body to pass (JSON); also implies POST
         # @param format     [String]  the format to request, 'json', 'xml', nil
-        # @param args       [Hash]    the arguments to pass
+        # @param query      [Hash]    the arguments to pass as query parameters
         # @param xml_arrays [Boolean] if true, force arrays in xml parsing
         # @param http       [Boolean] if true, returns the HttpResponse, else
-        def call_ao(endpoint, ret_style: nil, format: 'json', args: nil, xml_arrays: true, http: false)
-          # calls are all GET
-          call_args = {operation: 'GET', subpath: "api/#{endpoint}", ret: :both, query: {}}
-          ret_style = options.get_option(:ret_style, mandatory: true) if ret_style.nil?
-          call_args[:query].merge!(args) unless args.nil?
+        def call_ao(endpoint, body: nil, format: 'json', query: nil, xml_arrays: true, http: false)
+          call_args = {operation: body.nil? ? 'GET' : 'POST', subpath: "api/#{endpoint}", ret: :both, query: {}}
+          call_args.merge!(body: body, content_type: Mime::JSON) unless body.nil? # rubocop:disable Performance/RedundantMerge
+          ret_style = options.get_option(:ret_style, mandatory: true)
+          call_args[:query].merge!(query) unless query.nil?
           unless format.nil?
             case ret_style
             when :header
               call_args[:headers] = {'Accept' => "application/#{format}"}
-            when :arg
+            when :query
               call_args[:query][:format] = format
-            when :ext
+            when :path
               call_args[:subpath] = "#{call_args[:subpath]}.#{format}"
-            else Aspera.error_unexpected_value(ret_style)
+            else Aspera.error_unexpected_value(ret_style) { 'ret_style' }
             end
           end
           add_query = query_read_delete
@@ -99,13 +100,18 @@ module Aspera
 
         command :health,     description: 'Check Orchestrator API health'
         command :info,       description: 'Check that Orchestrator responds (ping)', action: ->(**) { Result::SingleObject.new(call_ao('remote_node_ping', format: 'xml', xml_arrays: false)) }
-        command :processes,  description: 'Show Orchestrator background process status', action: ->(**) { Result::ObjectList.new(call_ao('processes_status', format: 'xml')['process']) }
+        command :processes,  description: 'Show Orchestrator background process status', action: ->(**) { Result::ObjectList.new(call_ao('processes_status', format: 'xml')['node'].flat_map { |n| n['process'] }) }
         command :monitors,   description: 'Show Orchestrator monitor snapshot', action: ->(**) { Result::SingleObject.new(call_ao('monitor_snapshot')['monitor']) }
-        command :plugins,    description: 'Show Orchestrator plugin versions', action: ->(**) { Result::ObjectList.new(call_ao('plugin_version')['Plugin']) }
-        command :workflows,  description: 'Manage workflows'
         command :workorders, description: 'Manage work orders'
         command :workstep,   description: 'Manage work steps'
 
+        commands_under :plugins do
+          command :list,       description: 'Show Orchestrator plugin versions', action: ->(**) { Result::ObjectList.new(call_ao('plugin_version')['Plugin']) }
+          command :reload_set, description: 'Reload a set of plugins',
+            arguments: [{name: :plugin_set, type: Hash, schema: 'opts:components.schemas.OrchestratorReloadPluginSet'}],
+            action: ->(plugin_set:, **) { Result::SingleObject.new(call_ao('reload_plugin_set', body: plugin_set.transform_keys(&:to_sym))) }
+        end
+
         commands_under :workflows do
           command :list, description: 'List all workflows'
           command :status,     description: 'Show running status of a workflow',
@@ -120,9 +126,18 @@ module Aspera
           command :start,      description: 'Start a workflow: create a work order (sync or async)',
             arguments: [
               {name: :workflow_id, type: :identifier},
-              {name: :parameters, type: Hash, mandatory: false, default: {}},
+              {name: :parameters, type: Hash, mandatory: false, default: {}, schema: 'opts:components.schemas.OrchestratorInitiateParameters'},
               {name: :execution, type: Hash, mandatory: false, default: {}, schema: 'opts:components.schemas.OrchestratorWorkflowStart'}
             ]
+          command :import,     description: 'Import a workflow',
+            arguments: [{name: :workflow, type: Hash, schema: 'opts:components.schemas.OrchestratorImportWorkflow'}],
+            action: ->(workflow:, **) { Result::SingleObject.new(call_ao('import_workflow', body: workflow.transform_keys(&:to_sym))) }
+          command :publish,    description: 'Publish a workflow',
+            arguments: [{name: :workflow_id, type: :identifier}],
+            action: ->(workflow_id:, **) { Result::SingleObject.new(call_ao('publish_workflow', body: {workflow_id: workflow_id.to_i})) }
+          command :import_with_constraints, description: 'Import a workflow with constraint resolution',
+            arguments: [{name: :payload, type: Hash, schema: 'opts:components.schemas.OrchestratorImportWithConstraints'}],
+            action: ->(payload:, **) { Result::SingleObject.new(call_ao('import_with_constraints', body: payload.transform_keys(&:to_sym))) }
           command :export,     description: 'Export a workflow',
             arguments: [{name: :workflow_id, type: :identifier}],
             action: ->(workflow_id:, **) { Result::Text.new(call_ao("export_workflow/#{workflow_id}", format: nil, http: true).body) }
@@ -164,28 +179,43 @@ module Aspera
         # @return [Rest::Client]
         def api_orch
           return @api_orch if @api_orch
+          base_url = options.get_option(:url, mandatory: true)
+          style = options.get_option(:auth_style, mandatory: true)
+          apikey = options.get_option(:apikey)
+          username = options.get_option(:username)
+          password = options.get_option(:password)
+          Aspera.assert(apikey.nil? || (username.nil? && password.nil?), type: Cli::BadArgument) { 'apikey and username/password are mutually exclusive' }
+          Aspera.assert(!apikey.nil? || (!username.nil? && !password.nil?), type: Cli::BadArgument) { 'provide either apikey or username and password' }
+
           auth_params =
-            case options.get_option(:auth_style, mandatory: true)
-            when :arg_pass
+            case style
+            when :basic
+              Aspera.assert(apikey.nil?, type: Cli::BadArgument) { 'basic auth style cannot be used with apikey, use token or query' }
               {
-                type:      :url,
-                url_query: {
-                  'login'    => options.get_option(:username, mandatory: true),
-                  'password' => options.get_option(:password, mandatory: true)
-                }
+                type:     :basic,
+                username: username,
+                password: password
               }
-            when :head_basic
+            when :query
+              if apikey
+                {type: :url, url_query: {'apikey' => apikey}}
+              else
+                {type: :url, url_query: {'login' => username, 'password' => password}}
+              end
+            when :token
               {
-                type:     :basic,
-                username: options.get_option(:username, mandatory: true),
-                password: options.get_option(:password, mandatory: true)
+                type:         :oauth2,
+                grant_method: :json_credentials,
+                base_url:     base_url,
+                path_token:   'api/login',
+                token_field:  'token',
+                json:         apikey ? {apikey: apikey} : {username: username, password: password}
               }
-            when :apikey
-              Aspera.error_not_implemented
+            else Aspera.error_unexpected_value(style)
             end
           @api_orch = Rest::Client.new(
-            base_url: options.get_option(:url, mandatory: true),
-            auth: auth_params
+            base_url: base_url,
+            auth:     auth_params
           )
         end
 
@@ -225,23 +255,22 @@ module Aspera
             Aspera.assert(fields.length == 2, type: Cli::BadArgument) { "Expects: work_step:result_name : #{result_location}" }
             execution['step'], execution['variable'] = fields
           end
-          call_params = {format: :json}
-          # get external parameters if any
-          parameters.each do |name, value|
-            call_params["external_parameters[#{name}]"] = value
-          end
+          # POST /api/initiate with JSON body {workflow_id:, external_parameters:}
+          json_body = {workflow_id: workflow_id.to_i, external_parameters: parameters}
+          # control params passed as query string (not part of the spec requestBody)
+          query_params = {}
           Aspera.assert_type(execution['synchronous'], NilClass, *BoolValue::TYPES, type: Cli::BadArgument) { 'synchronous' }
-          call_params['synchronous'] = true if execution['synchronous'].eql?(true)
+          query_params[:synchronous] = true if execution['synchronous'].eql?(true)
           # expected result for synchro call ?
           if execution.key?('step') || execution.key?('variable')
             Aspera.assert(execution['step'].is_a?(String) && execution['variable'].is_a?(String), type: Cli::BadArgument) { 'Both step and variable are required' }
-            call_params['explicit_output_step'] = execution['step']
-            call_params['explicit_output_variable'] = execution['variable']
+            query_params[:explicit_output_step] = execution['step']
+            query_params[:explicit_output_variable] = execution['variable']
             # implicitly, call is synchronous
-            call_params['synchronous'] = true
+            query_params[:synchronous] = true
           end
-          result_data = call_ao("initiate/#{workflow_id}", args: call_params)
-          call_params['synchronous'] ? Result::Text.new(result_data) : Result::SingleObject.new(result_data)
+          result_data = call_ao('initiate', body: json_body, query: query_params.empty? ? nil : query_params)
+          query_params[:synchronous] ? Result::Text.new(result_data) : Result::SingleObject.new(result_data)
         end
       end
     end

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

@@ -3,11 +3,11 @@
 # cspell:ignore trevents
 require 'aspera/cli/plugins/basic_auth'
 require 'aspera/preview/generator'
-require 'aspera/preview/options'
 require 'aspera/preview/utils'
 require 'aspera/preview/file_types'
 require 'aspera/preview/terminal'
 require 'aspera/transfer/spec'
+require 'aspera/schema/registry'
 require 'aspera/persistency_action_once'
 require 'aspera/temp_file_manager'
 require 'aspera/api/node'
@@ -60,29 +60,30 @@ module Aspera
         option :detect_mime,        description: 'Detect Mime type by analyzing file', allowed: Type::BOOLEAN, default: false
         option :overwrite,          description: 'When to overwrite result file', allowed: %i[always never mtime], default: :mtime
         option :root_url,           description: "How to read and write files on storage (#{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})", default: REMOTE_ACCESS
-        # Generator-specific options (bound to @gen_options in initialize)
-        Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
-          values = if opt.key?(:values)
-            opt[:values]
-          elsif BoolValue.symbol?(opt[:default])
-            BoolValue::TYPES
-          end
-          option(opt[:name], description: opt[:description].capitalize, allowed: values, default: opt[:default])
+        # Generator options, defined in schema: values set in @gen_options
+        Schema::Registry.instance.reader(Schema::Registry::PREVIEW_OPTIONS).current['properties'].each do |name, property|
+          key = name.to_sym
+          option(
+            key,
+            description: property['description'].lines.first.strip.delete_suffix('.'),
+            allowed:     property.key?('enum') ? property['enum'].map(&:to_sym) : {'integer' => Type::INTEGER, 'number' => Type::FLOAT, 'boolean' => Type::BOOLEAN}[property['type']],
+            default:     property['default'],
+            # `Hash` value: validated with schema
+            schema:      ("#{Schema::Registry::PREVIEW_OPTIONS}:properties.#{name}" if property['type'].eql?('object')),
+            on_set:      ->(value) { @gen_options[key] = value }
+          )
         end
 
         def initialize(**_)
+          # Generator options, see `options.schema.yaml`
+          # Created before `super`, which declares options: values are set through `on_set`.
+          @gen_options = Aspera::Preview::Generator::Options.new
           super
-          # Generator configuration populated from CLI options.
-          @gen_options = Aspera::Preview::Options.new
           # Used to rate-limit periodic progress logging and checkpoint persistence.
           @periodic = TimerLimiter.new(LOG_LIMITER_SEC)
           # Optional callback used to filter entries before generation.
           @filter_block = nil
           @access_remote = true
-          # Bind generator-specific options to @gen_options
-          Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
-            options.on_set(opt[:name], @gen_options.method(:"#{opt[:name]}="))
-          end
           # Values set through `on_set` callbacks are used below
           options.parse_options!
           @option_skip_types = options.get_option(:skip_types)
@@ -98,9 +99,8 @@ module Aspera
           @preview_formats_to_generate = Aspera::Preview::Generator::PREVIEW_FORMATS.clone
           skip = options.get_option(:skip_format)
           @preview_formats_to_generate.delete(skip) if skip
+          # Created by `tools_cleanup`, only for commands that use it
           @tmp_folder = File.join(TempFileManager.instance.global_temp, "#{TMP_DIR_PREFIX}.#{SecureRandom.uuid}")
-          FileUtils.mkdir_p(@tmp_folder)
-          Log.log.debug { "tmpdir: #{@tmp_folder}" }
         end
 
         # Process legacy transfer events and trigger preview generation for completed downloads.
@@ -438,7 +438,7 @@ module Aspera
           Log.log.debug { "root: #{node_info['docroot']}" }
           # Default storage url to local file if not provided
           option_root_url = options.get_option(:root_url, mandatory: true)
-          option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.eql?(REMOTE_ACCESS) && @access_key_self['storage']['type'].eql?('local')
+          option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.eql?(REMOTE_ACCESS) && @access_key_self['storage']&.fetch('type').eql?('local')
           @access_remote = !UriReader.file?(option_root_url)
           Log.log.debug { "remote: #{@access_remote}" }
           # TODO: can the `previews` folder parameter be read from Node API ?
@@ -506,10 +506,12 @@ module Aspera
         private
 
         # Check tools and set option flag.
-        # Clean up the temporary folder after each command.
+        # Create the temporary folder for the command, and clean it up after.
         def tools_cleanup
           Aspera::Preview::FileTypes.instance.detect_mime = options.get_option(:detect_mime, mandatory: true)
           Aspera::Preview::Utils.check_tools(@option_skip_types)
+          FileUtils.mkdir_p(@tmp_folder)
+          Log.log.debug { "tmpdir: #{@tmp_folder}" }
           yield
         ensure
           Log.log.debug { "cleaning up temp folder #{@tmp_folder}" }