aspera-cli 4.29.0 → 4.29.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +2 -1
  3. data/CHANGELOG.md +76 -2
  4. data/README.md +20 -1
  5. data/SECURITY.md +14 -0
  6. data/docs/README.md +277 -38
  7. data/lib/aspera/api/node.rb +9 -2
  8. data/lib/aspera/ascp/installation.rb +26 -4
  9. data/lib/aspera/ascp/log_analyzer/lines.rb +2 -2
  10. data/lib/aspera/ascp/log_analyzer.rb +19 -3
  11. data/lib/aspera/ascp/log_locations.rb +163 -0
  12. data/lib/aspera/cli/ascp_logs_actions.rb +12 -0
  13. data/lib/aspera/cli/bootstrapper.rb +1 -0
  14. data/lib/aspera/cli/command_line.rb +39 -2
  15. data/lib/aspera/cli/command_registry.rb +3 -0
  16. data/lib/aspera/cli/command_spec.rb +13 -0
  17. data/lib/aspera/cli/error.rb +3 -0
  18. data/lib/aspera/cli/extended_value.rb +5 -4
  19. data/lib/aspera/cli/formatter.rb +14 -8
  20. data/lib/aspera/cli/http.rb +26 -1
  21. data/lib/aspera/cli/info.rb +1 -1
  22. data/lib/aspera/cli/mcp/tool.rb +5 -3
  23. data/lib/aspera/cli/option_value.rb +14 -8
  24. data/lib/aspera/cli/options.schema.yaml +156 -19
  25. data/lib/aspera/cli/parser.rb +15 -3
  26. data/lib/aspera/cli/plugins/aoc.rb +4 -2
  27. data/lib/aspera/cli/plugins/ats.rb +1 -1
  28. data/lib/aspera/cli/plugins/base.rb +33 -6
  29. data/lib/aspera/cli/plugins/config.rb +12 -1
  30. data/lib/aspera/cli/plugins/faspex5.rb +3 -1
  31. data/lib/aspera/cli/plugins/mcp.rb +14 -0
  32. data/lib/aspera/cli/plugins/node.rb +8 -8
  33. data/lib/aspera/cli/plugins/oauth.rb +18 -5
  34. data/lib/aspera/cli/plugins/orchestrator.rb +28 -24
  35. data/lib/aspera/cli/plugins/preview.rb +3 -1
  36. data/lib/aspera/cli/plugins/server.rb +3 -3
  37. data/lib/aspera/cli/plugins/shares.rb +1 -2
  38. data/lib/aspera/cli/plugins/transferd.rb +7 -2
  39. data/lib/aspera/cli/poll.rb +236 -0
  40. data/lib/aspera/cli/preset_manager.rb +63 -19
  41. data/lib/aspera/cli/prompt.rb +153 -8
  42. data/lib/aspera/cli/runner.rb +25 -7
  43. data/lib/aspera/cli/security.rb +10 -0
  44. data/lib/aspera/cli/sync_actions.rb +2 -0
  45. data/lib/aspera/cli/transfer_agent.rb +14 -0
  46. data/lib/aspera/cli/transfer_progress.rb +6 -5
  47. data/lib/aspera/cli/version.rb +1 -1
  48. data/lib/aspera/environment.rb +3 -1
  49. data/lib/aspera/id_generator.rb +16 -3
  50. data/lib/aspera/inflate.rb +43 -0
  51. data/lib/aspera/oauth/client/base.rb +38 -8
  52. data/lib/aspera/oauth/client/factory.rb +35 -15
  53. data/lib/aspera/oauth/client/json_credentials.rb +3 -2
  54. data/lib/aspera/oauth/client/shares_web.rb +13 -4
  55. data/lib/aspera/oauth/client/url_json.rb +3 -2
  56. data/lib/aspera/oauth/client/web.rb +2 -2
  57. data/lib/aspera/orchestrator_workflow_checker.rb +10 -1
  58. data/lib/aspera/preview/terminal.rb +8 -2
  59. data/lib/aspera/products/desktop.rb +13 -1
  60. data/lib/aspera/rest/client.rb +23 -5
  61. data/lib/aspera/schema/registry.rb +1 -0
  62. data/lib/aspera/sealed_hash.rb +2 -18
  63. data/lib/aspera/secret/hider.rb +13 -1
  64. data/lib/aspera/secret/store/one_password_cli.rb +13 -11
  65. data/lib/aspera/sync/operations.rb +4 -4
  66. data/lib/aspera/transfer/result.rb +20 -0
  67. data/lib/aspera/transfer/spec.rb +2 -2
  68. data/lib/aspera/{transfer/units.rb → units/decimal.rb} +4 -12
  69. data/lib/aspera/units/duration.rb +109 -0
  70. data/lib/aspera/uri_reader.rb +11 -6
  71. data/lib/aspera/web_auth/reply.html.erb +1 -1
  72. data/llms-install.md +88 -0
  73. data/llms.txt +6 -0
  74. data/skills/ascli/SKILL.md +6 -0
  75. data.tar.gz.sig +0 -0
  76. metadata +7 -3
  77. metadata.gz.sig +0 -0
  78. data/lib/aspera/duration.rb +0 -45
@@ -12,6 +12,7 @@ module Aspera
12
12
  # Transfer::Result::Success — all sessions completed successfully
13
13
  # Transfer::Result::Error — at least one session failed
14
14
  # Transfer::Result::Async — transfer submitted to a daemon; not yet complete
15
+ # Transfer::Result::DryRun — transfer not started (option `dry_run`): final transfer spec
15
16
  class Result
16
17
  # All sessions completed successfully.
17
18
  class Success < Result
@@ -58,6 +59,21 @@ module Aspera
58
59
  end
59
60
  end
60
61
 
62
+ # Transfer not started, because of option `dry_run`.
63
+ class DryRun < Result
64
+ # @return [Hash] final transfer spec, as it would be given to the agent
65
+ attr_reader :transfer_spec
66
+
67
+ def initialize(transfer_spec)
68
+ super()
69
+ @transfer_spec = transfer_spec
70
+ end
71
+
72
+ def to_s
73
+ 'dry run'
74
+ end
75
+ end
76
+
61
77
  # Factory helpers
62
78
  class << self
63
79
  def success
@@ -71,6 +87,10 @@ module Aspera
71
87
  def async(job_id:, status: 'running')
72
88
  Async.new(job_id: job_id, status: status)
73
89
  end
90
+
91
+ def dry_run(transfer_spec)
92
+ DryRun.new(transfer_spec)
93
+ end
74
94
  end
75
95
  end
76
96
  end
@@ -6,7 +6,7 @@
6
6
  require_relative '../agent/factory'
7
7
  require_relative '../command_line_builder'
8
8
  require_relative '../assert'
9
- require_relative 'units'
9
+ require_relative '../units/decimal'
10
10
 
11
11
  module Aspera
12
12
  module Transfer
@@ -58,7 +58,7 @@ module Aspera
58
58
  def resolve_target_rate(transfer_spec)
59
59
  return unless transfer_spec.key?('target_rate')
60
60
  rate = transfer_spec.delete('target_rate')
61
- transfer_spec['target_rate_kbps'] = Units.rate_string_to_bps(rate) / 1000 unless rate.nil?
61
+ transfer_spec['target_rate_kbps'] = Units::Decimal.rate_string_to_bps(rate) / 1000 unless rate.nil?
62
62
  end
63
63
 
64
64
  def fix_transferd_resume_policy(transfer_spec)
@@ -6,10 +6,10 @@
6
6
  require_relative '../assert'
7
7
 
8
8
  module Aspera
9
- module Transfer
10
- # Rates, sizes and durations of transfers: parsed from user input and formatted for display.
11
- # Decimal units, like `ascp`. Depends only on `aspera/assert`: usable without the CLI.
12
- module Units
9
+ module Units
10
+ # Rates and sizes in decimal units (prefixes `K`, `M`, `G`... x1000, like `ascp`): parsed from user input and formatted for display.
11
+ # Depends only on `aspera/assert`: usable without the CLI.
12
+ module Decimal
13
13
  # Decimal prefixes: each one is `KILO` times the previous one
14
14
  PREFIX = ['', 'K', 'M', 'G', 'T', 'P'].freeze
15
15
  KILO = 1000
@@ -61,14 +61,6 @@ module Aspera
61
61
  mbps = bytes_per_second * BITS_PER_BYTE / MULTIPLIER.fetch('M')
62
62
  mbps < 10 ? format('%.2f Mbps', mbps) : format('%.0f Mbps', mbps)
63
63
  end
64
-
65
- # @param seconds [Numeric, nil] Duration, `nil` if unknown
66
- # @return [String] Duration as `hh:mm:ss`
67
- def format_duration(seconds)
68
- return '--:--:--' if seconds.nil?
69
- seconds = seconds.round
70
- format('%02d:%02d:%02d', seconds / 3600, (seconds / 60) % 60, seconds % 60)
71
- end
72
64
  end
73
65
  end
74
66
  end
@@ -0,0 +1,109 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../assert'
7
+ require 'strscan'
8
+
9
+ module Aspera
10
+ module Units
11
+ # Duration in the format of Aspera Sync (`async` DURATION): parsed from user input and formatted for display.
12
+ # Immutable, kept as an integer number of microseconds.
13
+ class Duration
14
+ include Comparable
15
+
16
+ # Microseconds per unit
17
+ UNIT_US = {'w' => 604_800_000_000, 'd' => 86_400_000_000, 'h' => 3_600_000_000, 'm' => 60_000_000, 's' => 1_000_000, 'ms' => 1_000, 'us' => 1}.freeze
18
+ private_constant :UNIT_US
19
+
20
+ # @param value [Numeric, String] Number of `unit`, or text parsed (a plain number in text is seconds, whatever `unit`)
21
+ # @param unit [String] Time unit of a `Numeric` value, e.g. `ms`
22
+ # @raise [ParameterError] if the text is invalid
23
+ def initialize(value, unit = 's')
24
+ @microseconds =
25
+ if value.is_a?(Numeric)
26
+ (value * unit_us(unit)).round
27
+ else
28
+ Aspera.assert_type(value, String) { 'duration' }
29
+ parse_us(value)
30
+ end
31
+ freeze
32
+ end
33
+
34
+ # @return [Integer] Duration in microseconds
35
+ attr_reader :microseconds
36
+
37
+ # @param unit [String] Time unit of result, e.g. `ms`
38
+ # @return [Integer] Duration in `unit`, rounded down
39
+ def to_unit(unit)
40
+ @microseconds / unit_us(unit)
41
+ end
42
+
43
+ # @return [String] Duration as `1h02m03s`, `2m03s` or `3s` (seconds rounded), accepted by {#initialize}
44
+ def to_s
45
+ seconds = rounded_seconds
46
+ return "#{seconds}s" if seconds < 60
47
+ hours, rest = seconds.divmod(3600)
48
+ minutes, secs = rest.divmod(60)
49
+ hours.positive? ? format('%dh%02dm%02ds', hours, minutes, secs) : format('%dm%02ds', minutes, secs)
50
+ end
51
+
52
+ # @return [String] Duration as `hh:mm:ss` (seconds rounded)
53
+ def to_hms
54
+ seconds = rounded_seconds
55
+ format('%02d:%02d:%02d', seconds / 3600, (seconds / 60) % 60, seconds % 60)
56
+ end
57
+
58
+ def <=>(other)
59
+ return unless other.is_a?(Duration)
60
+ @microseconds <=> other.microseconds
61
+ end
62
+
63
+ def eql?(other)
64
+ other.is_a?(Duration) && @microseconds.eql?(other.microseconds)
65
+ end
66
+
67
+ def hash
68
+ @microseconds.hash
69
+ end
70
+
71
+ private
72
+
73
+ # @param unit [String] Time unit
74
+ # @return [Integer] Microseconds per unit
75
+ def unit_us(unit)
76
+ Aspera.assert_values(unit, UNIT_US.keys) { 'duration unit' }
77
+ UNIT_US[unit]
78
+ end
79
+
80
+ # @param value [String] `DDd HH:MM:SS.mmm` or `NNw NNd NNh NNm NNs NNms NNus`, leading fields and spaces may be omitted, a plain number is seconds
81
+ # @return [Integer] Duration in microseconds
82
+ # @raise [ParameterError] if the duration is invalid
83
+ def parse_us(value)
84
+ value = value.delete(' ')
85
+ if (m = value.match(/\A(?:(\d+)d)?(?:(?:(\d+):)?(\d+):)?(\d+)(?:\.(\d{1,3}))?\z/))
86
+ days, hours, minutes, seconds, millis = m.captures
87
+ hours = (days.to_i * 24) + hours.to_i
88
+ minutes = (hours * 60) + minutes.to_i
89
+ seconds = (minutes * 60) + seconds.to_i
90
+ return (seconds * UNIT_US['s']) + (millis.to_s.ljust(3, '0').to_i * UNIT_US['ms'])
91
+ end
92
+ # anchored sequential matching (linear time, no backtracking over start positions)
93
+ scanner = StringScanner.new(value)
94
+ units = []
95
+ until scanner.eos?
96
+ Aspera.assert(scanner.scan(/(\d+)(ms|us|[wdhms])/), type: ParameterError) { "Invalid duration: #{value}" } # cspell:disable-line
97
+ units.push([scanner[1], scanner[2]])
98
+ end
99
+ Aspera.assert(!units.empty?, type: ParameterError) { "Invalid duration: #{value}" }
100
+ units.sum { |number, number_unit| number.to_i * UNIT_US[number_unit] }
101
+ end
102
+
103
+ # @return [Integer] Duration in seconds, rounded
104
+ def rounded_seconds
105
+ (@microseconds.to_r / UNIT_US['s']).round
106
+ end
107
+ end
108
+ end
109
+ end
@@ -70,13 +70,16 @@ module Aspera
70
70
  # Bare paths (no scheme) are passed to File.read directly; leading `/~/`, `/./`, `/../`
71
71
  # are expanded via `File.expand_path` after stripping the synthetic leading slash added by
72
72
  # URI.
73
- def read(uri_to_read)
73
+ # @param uri_to_read [String] URI to read
74
+ # @param headers [Hash{String => String}] Additional HTTP request headers (schemes `http` and `https` only)
75
+ # @return [String] content
76
+ def read(uri_to_read, headers: {})
74
77
  # Handle file: URLs directly to honour the file:///relative vs file:////absolute convention.
75
78
  return File.read(file_path(uri_to_read)) if file?(uri_to_read)
76
79
  uri = URI.parse(uri_to_read)
77
80
  case uri.scheme
78
81
  when 'http', 'https'
79
- return Rest::Client.new(base_url: uri_to_read, redirect_max: 5).read(nil, headers: {'Accept' => '*/*'})
82
+ return Rest::Client.new(base_url: uri_to_read, redirect_max: 5).read(nil, headers: {'Accept' => '*/*'}.merge(headers))
80
83
  when 'data'
81
84
  metadata, encoded_data = uri.opaque.split(',', 2)
82
85
  if metadata.end_with?(';base64')
@@ -95,8 +98,9 @@ module Aspera
95
98
 
96
99
  # Read URL with a short timeout and no retry (temporarily changes global HTTP parameters)
97
100
  # @param url [String] URL to read
101
+ # @param read_options [Hash] Options of {read} (e.g. `headers`)
98
102
  # @return [String] content
99
- def read_fail_fast(url)
103
+ def read_fail_fast(url, **read_options)
100
104
  parameters = Rest::Parameters.instance
101
105
  session_cb = parameters.session_cb
102
106
  retry_max = parameters.retry_max
@@ -106,7 +110,7 @@ module Aspera
106
110
  http_session.open_timeout = [http_session.open_timeout, FAIL_FAST_TIMEOUT].compact.min
107
111
  http_session.read_timeout = [http_session.read_timeout, FAIL_FAST_TIMEOUT].compact.min
108
112
  end
109
- read(url)
113
+ read(url, **read_options)
110
114
  ensure
111
115
  parameters.session_cb = session_cb
112
116
  parameters.retry_max = retry_max
@@ -118,17 +122,18 @@ module Aspera
118
122
  # The failure of the last URL is raised.
119
123
  # @param urls [Array<String>] URLs, in order of preference
120
124
  # @param what [String] description of the content, for messages
125
+ # @param read_options [Hash] Options of {read} (e.g. `headers`)
121
126
  # @yield [content] Optional: validates and converts content, shall raise on invalid content
122
127
  # @yieldparam content [String] content read
123
128
  # @yieldreturn [Object] value returned by this method
124
129
  # @return [Object] result of block if given, else content
125
- def read_first(urls, what: 'content')
130
+ def read_first(urls, what: 'content', **read_options)
126
131
  Aspera.assert(!urls.empty?) { "no URL for #{what}" }
127
132
  urls.each_with_index do |url, index|
128
133
  last = index.eql?(urls.length - 1)
129
134
  Log.log.debug { "Retrieving #{what} from #{url}" }
130
135
  begin
131
- content = last ? read(url) : read_fail_fast(url)
136
+ content = last ? read(url, **read_options) : read_fail_fast(url, **read_options)
132
137
  return block_given? ? yield(content) : content
133
138
  rescue StandardError => e
134
139
  raise if last
@@ -70,7 +70,7 @@
70
70
  </div>
71
71
 
72
72
  <h1>Login Complete</h1>
73
- <p>Copy this code, and paste it in the terminal where <b>ascli</b> waits for it. You can then close this window.</p>
73
+ <p>Copy this code, and paste it in the terminal where <b>ascli</b> waits for it. This code is valid for <%= Aspera::SealedHash::PERIOD / 60 %> minutes. You can then close this window.</p>
74
74
 
75
75
  <% unless additional_info.to_s.empty? %>
76
76
  <div class="info-box">
data/llms-install.md ADDED
@@ -0,0 +1,88 @@
1
+ # Install the IBM Aspera CLI MCP server
2
+
3
+ Instructions for an AI agent that installs and configures the MCP server of `ascli` (IBM Aspera CLI) for an MCP client.
4
+ Details: [MCP client configuration](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#mcp-client-configuration) in the manual.
5
+
6
+ ## 1. Check Ruby
7
+
8
+ ```shell
9
+ ruby -v
10
+ ```
11
+
12
+ Ruby 3.3 or later is required.
13
+ If Ruby is missing or older, install it first (macOS: `brew install ruby`, Linux: the distribution package or `rbenv`, Windows: RubyInstaller).
14
+
15
+ ## 2. Install the gems
16
+
17
+ Install the published gem from RubyGems, with the optional gem `mcp` (required for `ascli mcp server`).
18
+ Do not build the gem from the source repository, even if it is cloned locally.
19
+
20
+ ```shell
21
+ gem install aspera-cli mcp
22
+ ```
23
+
24
+ Check:
25
+
26
+ ```shell
27
+ ascli -v
28
+ ```
29
+
30
+ `ascli mcp server` starts the server on standard input and output (`stdio`): it waits for an MCP client and does not return.
31
+ To check it outside a client, stop it after the line `Starting MCP server`.
32
+
33
+ ## 3. Add the server to the MCP client
34
+
35
+ Add the server to the configuration file of the MCP client itself (not to VS Code `settings.json`).
36
+ Server name: `ascli`, command: `ascli`, arguments: `mcp server`.
37
+
38
+ Cline: add to `cline_mcp_settings.json` (Cline: MCP Servers > Configure, or Edit Configuration):
39
+
40
+ ```json
41
+ {
42
+ "mcpServers": {
43
+ "ascli": {
44
+ "command": "ascli",
45
+ "args": ["mcp", "server"]
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ The same `mcpServers` entry applies to Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and IBM Bob (`.bob/mcp.json`).
52
+
53
+ VS Code (GitHub Copilot agent mode): add to `.vscode/mcp.json`:
54
+
55
+ ```json
56
+ {
57
+ "servers": {
58
+ "ascli": {
59
+ "type": "stdio",
60
+ "command": "ascli",
61
+ "args": ["mcp", "server"]
62
+ }
63
+ }
64
+ }
65
+ ```
66
+
67
+ Claude Code:
68
+
69
+ ```shell
70
+ claude mcp add ascli -- ascli mcp server
71
+ ```
72
+
73
+ If `ascli` is not found by the client, use the absolute path given by `which ascli` (Windows: `where ascli`) as `command`.
74
+
75
+ ## 4. Verify
76
+
77
+ The client lists the server `ascli`, connected, with the tool `execute_ascli_command`.
78
+
79
+ ## 5. Optional: try it
80
+
81
+ No account needed, the public Aspera demo server:
82
+
83
+ ```shell
84
+ ascli config initdemo
85
+ ```
86
+
87
+ Then ask the AI: "List the files on the Aspera demo server."
88
+ For your own systems, create presets (`ascli config wizard`) and keep secrets in a vault: the AI never sees them.
data/llms.txt CHANGED
@@ -51,13 +51,18 @@ Before writing or modifying a workflow, read the development guide with `ascli`:
51
51
  Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
52
52
  Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
53
53
  - IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
54
+ Start with the section of each trigger and action used (for example, "Send a package" is action type `package_transfer`, section `package-transfer`),
55
+ then `payload-rules-enforced-by-the-api` and `finding-the-identifiers`.
54
56
 
55
57
  ## Rules
56
58
 
57
59
  - Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
60
+ - Extended values inside JSON (e.g. a vault secret in a parameter file): write `"@vault:<label>.<field>@"` (closing `@`) in the file, and give `@json:@extend:@file:<path>`. Without `@extend:`, or without the closing `@`, the value stays a literal string. Check with `ascli config echo`.
58
61
  - Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
59
62
  - Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
60
63
  - Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
64
+ - Wait for a state (a work order complete, a task created, a package received): repeat a read-only command (`list`, `show`, `status`) with `--poll`, not with `sleep` or a shell loop, e.g. ``--poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'``.
65
+ `until` is a JMESPath expression on the result (`@`: result not empty), the command fails if it is not met after `max` runs (or `timeout`). `"show":"last"` displays only the last result, `"errors":"retry"` runs again after an error. With `--format=json`, each result displayed is one line: usable in a background watcher. See section `polling-option-poll` of the manual.
61
66
  - Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
62
67
  - Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
63
68
  - Show the user the command line that was executed.
@@ -69,6 +74,7 @@ ascli config commands faspex5
69
74
  ascli faspex5 packages send help
70
75
  ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
71
76
  ascli aoc files browse / --format=json
77
+ ascli orchestrator workorders status 1234 --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}' --format=json
72
78
  ascli server upload /path/to/file --to-folder=/Upload
73
79
  ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
74
80
  ```
@@ -58,13 +58,18 @@ Before writing or modifying a workflow, read the development guide with `ascli`:
58
58
  Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
59
59
  Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
60
60
  - IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
61
+ Start with the section of each trigger and action used (for example, "Send a package" is action type `package_transfer`, section `package-transfer`),
62
+ then `payload-rules-enforced-by-the-api` and `finding-the-identifiers`.
61
63
 
62
64
  ## Rules
63
65
 
64
66
  - Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
67
+ - Extended values inside JSON (e.g. a vault secret in a parameter file): write `"@vault:<label>.<field>@"` (closing `@`) in the file, and give `@json:@extend:@file:<path>`. Without `@extend:`, or without the closing `@`, the value stays a literal string. Check with `ascli config echo`.
65
68
  - Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
66
69
  - Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
67
70
  - Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
71
+ - Wait for a state (a work order complete, a task created, a package received): repeat a read-only command (`list`, `show`, `status`) with `--poll`, not with `sleep` or a shell loop, e.g. ``--poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'``.
72
+ `until` is a JMESPath expression on the result (`@`: result not empty), the command fails if it is not met after `max` runs (or `timeout`). `"show":"last"` displays only the last result, `"errors":"retry"` runs again after an error. With `--format=json`, each result displayed is one line: usable in a background watcher. See section `polling-option-poll` of the manual.
68
73
  - Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
69
74
  - Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
70
75
  - Show the user the command line that was executed.
@@ -76,6 +81,7 @@ ascli config commands faspex5
76
81
  ascli faspex5 packages send help
77
82
  ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
78
83
  ascli aoc files browse / --format=json
84
+ ascli orchestrator workorders status 1234 --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}' --format=json
79
85
  ascli server upload /path/to/file --to-folder=/Upload
80
86
  ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
81
87
  ```
data.tar.gz.sig CHANGED
Binary file
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: aspera-cli
3
3
  version: !ruby/object:Gem::Version
4
- version: 4.29.0
4
+ version: 4.29.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Laurent Martin
@@ -388,6 +388,7 @@ files:
388
388
  - lib/aspera/ascp/log_analyzer/records.rb
389
389
  - lib/aspera/ascp/log_analyzer/rules.rb
390
390
  - lib/aspera/ascp/log_analyzer/session.rb
391
+ - lib/aspera/ascp/log_locations.rb
391
392
  - lib/aspera/ascp/management.rb
392
393
  - lib/aspera/ascp/session_errors.rb
393
394
  - lib/aspera/assert.rb
@@ -442,6 +443,7 @@ files:
442
443
  - lib/aspera/cli/plugins/server.rb
443
444
  - lib/aspera/cli/plugins/shares.rb
444
445
  - lib/aspera/cli/plugins/transferd.rb
446
+ - lib/aspera/cli/poll.rb
445
447
  - lib/aspera/cli/preset_actions.rb
446
448
  - lib/aspera/cli/preset_manager.rb
447
449
  - lib/aspera/cli/prompt.rb
@@ -473,7 +475,6 @@ files:
473
475
  - lib/aspera/data/6
474
476
  - lib/aspera/data_repository.rb
475
477
  - lib/aspera/dot_container.rb
476
- - lib/aspera/duration.rb
477
478
  - lib/aspera/environment.rb
478
479
  - lib/aspera/exec_spec.rb
479
480
  - lib/aspera/faspex_gw.rb
@@ -482,6 +483,7 @@ files:
482
483
  - lib/aspera/graphql.rb
483
484
  - lib/aspera/hash_ext.rb
484
485
  - lib/aspera/id_generator.rb
486
+ - lib/aspera/inflate.rb
485
487
  - lib/aspera/json_rpc/client.rb
486
488
  - lib/aspera/json_rpc/version.rb
487
489
  - lib/aspera/line_logger.rb
@@ -574,7 +576,8 @@ files:
574
576
  - lib/aspera/transfer/resumer.rb
575
577
  - lib/aspera/transfer/spec.rb
576
578
  - lib/aspera/transfer/spec.schema.yaml
577
- - lib/aspera/transfer/units.rb
579
+ - lib/aspera/units/decimal.rb
580
+ - lib/aspera/units/duration.rb
578
581
  - lib/aspera/uri_reader.rb
579
582
  - lib/aspera/web_auth/index.html.erb
580
583
  - lib/aspera/web_auth/paste.rb
@@ -588,6 +591,7 @@ files:
588
591
  - lib/aspera/yaml.rb
589
592
  - lib/transferd_pb.rb
590
593
  - lib/transferd_services_pb.rb
594
+ - llms-install.md
591
595
  - llms.txt
592
596
  - skills/ascli/SKILL.md
593
597
  homepage: https://github.com/IBM/aspera-cli
metadata.gz.sig CHANGED
Binary file
@@ -1,45 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- # SPDX-FileCopyrightText: IBM Corp.
4
- # SPDX-License-Identifier: Apache-2.0
5
-
6
- require_relative 'assert'
7
- require 'strscan'
8
-
9
- module Aspera
10
- # Duration in the format of Aspera Sync (`async` DURATION)
11
- module Duration
12
- # Microseconds per unit
13
- UNIT_US = {'w' => 604_800_000_000, 'd' => 86_400_000_000, 'h' => 3_600_000_000, 'm' => 60_000_000, 's' => 1_000_000, 'ms' => 1_000, 'us' => 1}.freeze
14
- private_constant :UNIT_US
15
-
16
- class << self
17
- # Convert a duration to an integer in the given time unit
18
- # @param value [String] `DDd HH:MM:SS.mmm` or `NNw NNd NNh NNm NNs NNms NNus`, leading fields and spaces may be omitted, a plain number is seconds
19
- # @param unit [String] Time unit of result, e.g. `ms`
20
- # @return [Integer] Duration in `unit`, rounded down
21
- def to_unit(value, unit)
22
- Aspera.assert_values(unit, UNIT_US.keys) { 'duration unit' }
23
- value = value.to_s.delete(' ')
24
- if (m = value.match(/\A(?:(\d+)d)?(?:(?:(\d+):)?(\d+):)?(\d+)(?:\.(\d{1,3}))?\z/))
25
- days, hours, minutes, seconds, millis = m.captures
26
- hours = (days.to_i * 24) + hours.to_i
27
- minutes = (hours * 60) + minutes.to_i
28
- seconds = (minutes * 60) + seconds.to_i
29
- microseconds = (seconds * UNIT_US['s']) + (millis.to_s.ljust(3, '0').to_i * UNIT_US['ms'])
30
- else
31
- # anchored sequential matching (linear time, no backtracking over start positions)
32
- scanner = StringScanner.new(value)
33
- units = []
34
- until scanner.eos?
35
- Aspera.assert(scanner.scan(/(\d+)(ms|us|[wdhms])/), type: ParameterError) { "Invalid duration: #{value}" } # cspell:disable-line
36
- units.push([scanner[1], scanner[2]])
37
- end
38
- Aspera.assert(!units.empty?, type: ParameterError) { "Invalid duration: #{value}" }
39
- microseconds = units.sum { |number, number_unit| number.to_i * UNIT_US[number_unit] }
40
- end
41
- microseconds / UNIT_US[unit]
42
- end
43
- end
44
- end
45
- end