aspera-cli 4.28.0 → 4.29.0

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 (237) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +143 -2
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +135 -56
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1633 -609
  14. data/docs/test-mcp-with-ai.md +8 -8
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +20 -19
  19. data/lib/aspera/agent/factory.rb +6 -3
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +7 -4
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +20 -20
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +71 -65
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +354 -0
  41. data/lib/aspera/ascp/management.rb +16 -8
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +12 -19
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -33
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +6 -1
  50. data/lib/aspera/cli/command_spec.rb +34 -7
  51. data/lib/aspera/cli/completion/ascli.bash +19 -5
  52. data/lib/aspera/cli/completion/ascli.fish +13 -2
  53. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  54. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  55. data/lib/aspera/cli/completion_actions.rb +303 -69
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +3 -0
  59. data/lib/aspera/cli/extended_value.rb +61 -27
  60. data/lib/aspera/cli/formatter.rb +29 -22
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -10
  63. data/lib/aspera/cli/http.rb +12 -9
  64. data/lib/aspera/cli/info.rb +12 -7
  65. data/lib/aspera/cli/mailer.rb +6 -3
  66. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  67. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  68. data/lib/aspera/cli/mcp/tool.rb +15 -14
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +65 -12
  73. data/lib/aspera/cli/options.schema.yaml +487 -63
  74. data/lib/aspera/cli/parser.rb +56 -32
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +244 -35
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +17 -12
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +198 -103
  81. data/lib/aspera/cli/plugins/console.rb +6 -3
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +21 -7
  84. data/lib/aspera/cli/plugins/faspex5.rb +28 -25
  85. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  86. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +28 -22
  88. data/lib/aspera/cli/plugins/node.rb +31 -30
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +272 -72
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +63 -11
  93. data/lib/aspera/cli/plugins/shares.rb +86 -16
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +144 -30
  96. data/lib/aspera/cli/preset_manager.rb +52 -18
  97. data/lib/aspera/cli/prompt.rb +4 -1
  98. data/lib/aspera/cli/result.rb +12 -8
  99. data/lib/aspera/cli/runner.rb +69 -46
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +79 -9
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +3 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +29 -20
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +188 -42
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.rb +12 -10
  113. data/lib/aspera/cli/wizard.rb +42 -39
  114. data/lib/aspera/command_line_builder.rb +9 -5
  115. data/lib/aspera/command_line_converter.rb +4 -1
  116. data/lib/aspera/coverage.rb +103 -33
  117. data/lib/aspera/data_repository.rb +4 -1
  118. data/lib/aspera/dot_container.rb +4 -1
  119. data/lib/aspera/duration.rb +5 -2
  120. data/lib/aspera/environment.rb +21 -12
  121. data/lib/aspera/exec_spec.rb +3 -0
  122. data/lib/aspera/faspex_gw.rb +13 -9
  123. data/lib/aspera/faspex_postproc.rb +15 -12
  124. data/lib/aspera/formatter_interface.rb +4 -1
  125. data/lib/aspera/graphql.rb +5 -1
  126. data/lib/aspera/hash_ext.rb +3 -0
  127. data/lib/aspera/id_generator.rb +4 -2
  128. data/lib/aspera/json_rpc/client.rb +6 -5
  129. data/lib/aspera/json_rpc/version.rb +3 -0
  130. data/lib/aspera/line_logger.rb +4 -1
  131. data/lib/aspera/link_header.rb +4 -1
  132. data/lib/aspera/log.rb +18 -5
  133. data/lib/aspera/markdown.rb +5 -2
  134. data/lib/aspera/mime.rb +3 -0
  135. data/lib/aspera/nagios.rb +6 -4
  136. data/lib/aspera/node_emulator.rb +15 -13
  137. data/lib/aspera/oauth/client/base.rb +91 -70
  138. data/lib/aspera/oauth/client/boot.rb +7 -4
  139. data/lib/aspera/oauth/client/factory.rb +6 -3
  140. data/lib/aspera/oauth/client/generic.rb +5 -1
  141. data/lib/aspera/oauth/client/json_credentials.rb +4 -1
  142. data/lib/aspera/oauth/client/jwt.rb +6 -3
  143. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  144. data/lib/aspera/oauth/client/url_json.rb +4 -1
  145. data/lib/aspera/oauth/client/web.rb +39 -12
  146. data/lib/aspera/oauth/server/pkce.rb +6 -5
  147. data/lib/aspera/orchestrator_workflow_checker.rb +119 -1
  148. data/lib/aspera/persistency_action_once.rb +5 -3
  149. data/lib/aspera/persistency_folder.rb +6 -3
  150. data/lib/aspera/preview/file_types.rb +6 -3
  151. data/lib/aspera/preview/generator.rb +9 -5
  152. data/lib/aspera/preview/options.schema.yaml +3 -3
  153. data/lib/aspera/preview/terminal.rb +8 -4
  154. data/lib/aspera/preview/utils.rb +6 -4
  155. data/lib/aspera/products/connect.rb +5 -2
  156. data/lib/aspera/products/desktop.rb +4 -1
  157. data/lib/aspera/products/other.rb +4 -2
  158. data/lib/aspera/products/transferd.rb +6 -2
  159. data/lib/aspera/products/transferd_service.rb +610 -0
  160. data/lib/aspera/proxy_auto_config.js +2 -2
  161. data/lib/aspera/proxy_auto_config.rb +5 -2
  162. data/lib/aspera/rainbow.rb +3 -0
  163. data/lib/aspera/rest/aspera_errors.rb +4 -1
  164. data/lib/aspera/rest/call_error.rb +3 -0
  165. data/lib/aspera/rest/client.rb +22 -29
  166. data/lib/aspera/rest/error_analyzer.rb +5 -2
  167. data/lib/aspera/rest/list.rb +8 -4
  168. data/lib/aspera/rest/parameters.rb +3 -0
  169. data/lib/aspera/rest/util.rb +8 -5
  170. data/lib/aspera/rest.rb +9 -6
  171. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  172. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  173. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  174. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  175. data/lib/aspera/schema/async_tables.yaml +11 -10
  176. data/lib/aspera/schema/documentation.rb +8 -2
  177. data/lib/aspera/schema/reader.rb +7 -0
  178. data/lib/aspera/schema/registry.rb +43 -28
  179. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  180. data/lib/aspera/schema/validator.rb +4 -1
  181. data/lib/aspera/sealed_hash.rb +166 -0
  182. data/lib/aspera/secret/hider.rb +201 -0
  183. data/lib/aspera/secret/reference.rb +150 -0
  184. data/lib/aspera/secret/resolver.rb +212 -0
  185. data/lib/aspera/secret/store/base.rb +153 -0
  186. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  187. data/lib/aspera/secret/store/factory.rb +103 -0
  188. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  189. data/lib/aspera/secret/store/keeper.rb +141 -0
  190. data/lib/aspera/secret/store/macos_security.rb +284 -0
  191. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  192. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  193. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  194. data/lib/aspera/secret/store/secret_service.rb +125 -0
  195. data/lib/aspera/secret/strength.rb +119 -0
  196. data/lib/aspera/servlet_helpers.rb +5 -2
  197. data/lib/aspera/ssh.rb +10 -7
  198. data/lib/aspera/ssl.rb +5 -2
  199. data/lib/aspera/string_ext.rb +3 -0
  200. data/lib/aspera/sync/args.schema.yaml +3 -0
  201. data/lib/aspera/sync/conf.schema.yaml +9 -4
  202. data/lib/aspera/sync/database.rb +3 -0
  203. data/lib/aspera/sync/operations.rb +16 -14
  204. data/lib/aspera/temp_file_manager.rb +8 -4
  205. data/lib/aspera/timer_limiter.rb +3 -0
  206. data/lib/aspera/transfer/error.rb +4 -1
  207. data/lib/aspera/transfer/faux_file.rb +4 -1
  208. data/lib/aspera/transfer/parameters.rb +17 -14
  209. data/lib/aspera/transfer/result.rb +3 -0
  210. data/lib/aspera/transfer/resumer.rb +6 -4
  211. data/lib/aspera/transfer/spec.rb +9 -22
  212. data/lib/aspera/transfer/units.rb +75 -0
  213. data/lib/aspera/uri_reader.rb +57 -7
  214. data/lib/aspera/web_auth/index.html.erb +6 -2
  215. data/lib/aspera/web_auth/paste.rb +109 -0
  216. data/lib/aspera/web_auth/receiver.rb +50 -0
  217. data/lib/aspera/web_auth/relay.rb +76 -0
  218. data/lib/aspera/web_auth/reply.html.erb +150 -0
  219. data/lib/aspera/web_auth/server.rb +47 -10
  220. data/lib/aspera/web_page.rb +7 -2
  221. data/lib/aspera/web_server_simple.rb +6 -3
  222. data/lib/aspera/yaml.rb +5 -1
  223. data/llms.txt +81 -0
  224. data/skills/ascli/SKILL.md +88 -0
  225. data.tar.gz.sig +0 -0
  226. metadata +72 -19
  227. metadata.gz.sig +0 -0
  228. data/lib/aspera/keychain/base.rb +0 -30
  229. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  230. data/lib/aspera/keychain/factory.rb +0 -58
  231. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  232. data/lib/aspera/keychain/macos_security.rb +0 -277
  233. data/lib/aspera/keychain/one_password_api.rb +0 -91
  234. data/lib/aspera/keychain/one_password_base.rb +0 -39
  235. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  236. data/lib/aspera/secret_hider.rb +0 -196
  237. data/lib/aspera/secret_strength.rb +0 -114
data/llms.txt ADDED
@@ -0,0 +1,81 @@
1
+ # ascli: command line interface for IBM Aspera
2
+
3
+ > `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
4
+ > An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
5
+ > transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
6
+
7
+ If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
8
+
9
+ ## Products and plugins
10
+
11
+ The first word after `ascli` is a plugin: one per product.
12
+
13
+ - `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
14
+ - `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
15
+ - `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
16
+ - `node`: Node API of a transfer server (files, access keys, transfers, sync)
17
+ - `shares`: IBM Aspera Shares
18
+ - `console`: IBM Aspera Console
19
+ - `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
20
+ - `ats`: IBM Aspera Transfer Service
21
+ - `cos`: IBM Cloud Object Storage
22
+ - `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
23
+ - `preview`: generation of previews of files
24
+ - `transferd`: Transfer Daemon of the Transfer SDK (install, service)
25
+ - `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
26
+ - `mcp`: Model Context Protocol server
27
+
28
+ ## Two ways to use it
29
+
30
+ - Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
31
+ Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
32
+ - MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
33
+ The description of the tool repeats the rules below.
34
+
35
+ ## Discover, do not guess
36
+
37
+ Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
38
+
39
+ 1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
40
+ 2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
41
+ 3. Filter parameters of a list command: `--query=help`.
42
+ 4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
43
+ 5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
44
+
45
+ ## Workflow development
46
+
47
+ Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
48
+
49
+ - IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
50
+ Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
51
+ Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
52
+ Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
53
+ - IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
54
+
55
+ ## Rules
56
+
57
+ - Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
58
+ - Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
59
+ - 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
+ - Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
61
+ - 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
+ - Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
63
+ - Show the user the command line that was executed.
64
+
65
+ ## Examples
66
+
67
+ ```shell
68
+ ascli config commands faspex5
69
+ ascli faspex5 packages send help
70
+ ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
71
+ ascli aoc files browse / --format=json
72
+ ascli server upload /path/to/file --to-folder=/Upload
73
+ ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
74
+ ```
75
+
76
+ ## Documentation
77
+
78
+ - [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
79
+ - [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
80
+ - [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
81
+ - [Source](https://github.com/IBM/aspera-cli)
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: ascli
3
+ description: 'Operate IBM Aspera products with the ascli command line: Aspera on Cloud, Faspex 5, High-Speed Transfer Server, Node API, Shares, Console, Orchestrator, Cloud Object Storage. Use when the user wants to transfer files with FASP (ascp), send or receive packages, browse or manage remote files, administer users, workspaces, nodes or access keys, analyze ascp logs, or develop Orchestrator or Aspera on Cloud Automation workflows.'
4
+ license: Apache-2.0
5
+ compatibility: Requires the ascli command (Ruby gem aspera-cli) in the shell, or the ascli MCP server.
6
+ ---
7
+
8
+ # ascli: command line interface for IBM Aspera
9
+
10
+ > `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
11
+ > An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
12
+ > transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
13
+
14
+ If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
15
+
16
+ ## Products and plugins
17
+
18
+ The first word after `ascli` is a plugin: one per product.
19
+
20
+ - `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
21
+ - `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
22
+ - `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
23
+ - `node`: Node API of a transfer server (files, access keys, transfers, sync)
24
+ - `shares`: IBM Aspera Shares
25
+ - `console`: IBM Aspera Console
26
+ - `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
27
+ - `ats`: IBM Aspera Transfer Service
28
+ - `cos`: IBM Cloud Object Storage
29
+ - `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
30
+ - `preview`: generation of previews of files
31
+ - `transferd`: Transfer Daemon of the Transfer SDK (install, service)
32
+ - `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
33
+ - `mcp`: Model Context Protocol server
34
+
35
+ ## Two ways to use it
36
+
37
+ - Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
38
+ Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
39
+ - MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
40
+ The description of the tool repeats the rules below.
41
+
42
+ ## Discover, do not guess
43
+
44
+ Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
45
+
46
+ 1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
47
+ 2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
48
+ 3. Filter parameters of a list command: `--query=help`.
49
+ 4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
50
+ 5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
51
+
52
+ ## Workflow development
53
+
54
+ Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
55
+
56
+ - IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
57
+ Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
58
+ Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
59
+ Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
60
+ - IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
61
+
62
+ ## Rules
63
+
64
+ - Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
65
+ - Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
66
+ - 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
+ - Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
68
+ - 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
+ - Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
70
+ - Show the user the command line that was executed.
71
+
72
+ ## Examples
73
+
74
+ ```shell
75
+ ascli config commands faspex5
76
+ ascli faspex5 packages send help
77
+ ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
78
+ ascli aoc files browse / --format=json
79
+ ascli server upload /path/to/file --to-folder=/Upload
80
+ ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
81
+ ```
82
+
83
+ ## Documentation
84
+
85
+ - [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
86
+ - [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
87
+ - [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
88
+ - [Source](https://github.com/IBM/aspera-cli)
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.28.0
4
+ version: 4.29.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Laurent Martin
@@ -142,14 +142,14 @@ dependencies:
142
142
  requirements:
143
143
  - - "~>"
144
144
  - !ruby/object:Gem::Version
145
- version: '1.1'
145
+ version: '2.1'
146
146
  type: :runtime
147
147
  prerelease: false
148
148
  version_requirements: !ruby/object:Gem::Requirement
149
149
  requirements:
150
150
  - - "~>"
151
151
  - !ruby/object:Gem::Version
152
- version: '1.1'
152
+ version: '2.1'
153
153
  - !ruby/object:Gem::Dependency
154
154
  name: mime-types
155
155
  requirement: !ruby/object:Gem::Requirement
@@ -184,14 +184,14 @@ dependencies:
184
184
  requirements:
185
185
  - - "~>"
186
186
  - !ruby/object:Gem::Version
187
- version: '7.3'
187
+ version: '8.1'
188
188
  type: :runtime
189
189
  prerelease: false
190
190
  version_requirements: !ruby/object:Gem::Requirement
191
191
  requirements:
192
192
  - - "~>"
193
193
  - !ruby/object:Gem::Version
194
- version: '7.3'
194
+ version: '8.1'
195
195
  - !ruby/object:Gem::Dependency
196
196
  name: rainbow
197
197
  requirement: !ruby/object:Gem::Requirement
@@ -206,6 +206,20 @@ dependencies:
206
206
  - - "~>"
207
207
  - !ruby/object:Gem::Version
208
208
  version: '3.0'
209
+ - !ruby/object:Gem::Dependency
210
+ name: regexp_parser
211
+ requirement: !ruby/object:Gem::Requirement
212
+ requirements:
213
+ - - "!="
214
+ - !ruby/object:Gem::Version
215
+ version: 2.13.2
216
+ type: :runtime
217
+ prerelease: false
218
+ version_requirements: !ruby/object:Gem::Requirement
219
+ requirements:
220
+ - - "!="
221
+ - !ruby/object:Gem::Version
222
+ version: 2.13.2
209
223
  - !ruby/object:Gem::Dependency
210
224
  name: ruby-progressbar
211
225
  requirement: !ruby/object:Gem::Requirement
@@ -318,7 +332,13 @@ dependencies:
318
332
  - - "~>"
319
333
  - !ruby/object:Gem::Version
320
334
  version: '1.0'
321
- description: Command line interface for IBM Aspera products
335
+ description: 'Open-source toolkit to automate, integrate and operate IBM Aspera products:
336
+ high-speed transfers with FASP (ascp), send and receive packages, manage files and
337
+ administer Aspera on Cloud, Faspex, Shares, Node, Console, Orchestrator and High
338
+ Speed Transfer Server. Structured output for scripts and pipelines, presets and
339
+ secret vaults for multiple environments, analysis of ascp logs. Usable by AI assistants
340
+ and AI agents: in a shell (see llms.txt and the agent skill), or through its MCP
341
+ (Model Context Protocol) server.'
322
342
  email:
323
343
  - laurent.martin.aspera@fr.ibm.com
324
344
  executables:
@@ -329,8 +349,12 @@ extra_rdoc_files: []
329
349
  files:
330
350
  - BUGS.md
331
351
  - CHANGELOG.md
352
+ - CODE_OF_CONDUCT.md
332
353
  - CONTRIBUTING.md
354
+ - GOVERNANCE.md
355
+ - LICENSE
333
356
  - README.md
357
+ - SECURITY.md
334
358
  - TODO.md
335
359
  - bin/ascli
336
360
  - bin/asession
@@ -355,9 +379,20 @@ files:
355
379
  - lib/aspera/api/queries/bss_subscription_usage.graphql
356
380
  - lib/aspera/ascmd.rb
357
381
  - lib/aspera/ascp/installation.rb
382
+ - lib/aspera/ascp/log.schema.yaml
383
+ - lib/aspera/ascp/log_analyzer.rb
384
+ - lib/aspera/ascp/log_analyzer/advice.rb
385
+ - lib/aspera/ascp/log_analyzer/diagnostics.rb
386
+ - lib/aspera/ascp/log_analyzer/lines.rb
387
+ - lib/aspera/ascp/log_analyzer/log_file.rb
388
+ - lib/aspera/ascp/log_analyzer/records.rb
389
+ - lib/aspera/ascp/log_analyzer/rules.rb
390
+ - lib/aspera/ascp/log_analyzer/session.rb
358
391
  - lib/aspera/ascp/management.rb
392
+ - lib/aspera/ascp/session_errors.rb
359
393
  - lib/aspera/assert.rb
360
394
  - lib/aspera/cli/ascp_actions.rb
395
+ - lib/aspera/cli/ascp_logs_actions.rb
361
396
  - lib/aspera/cli/async_transfer_store.rb
362
397
  - lib/aspera/cli/bootstrapper.rb
363
398
  - lib/aspera/cli/command_line.rb
@@ -406,6 +441,7 @@ files:
406
441
  - lib/aspera/cli/plugins/preview.rb
407
442
  - lib/aspera/cli/plugins/server.rb
408
443
  - lib/aspera/cli/plugins/shares.rb
444
+ - lib/aspera/cli/plugins/transferd.rb
409
445
  - lib/aspera/cli/preset_actions.rb
410
446
  - lib/aspera/cli/preset_manager.rb
411
447
  - lib/aspera/cli/prompt.rb
@@ -420,6 +456,7 @@ files:
420
456
  - lib/aspera/cli/transfer_actions.rb
421
457
  - lib/aspera/cli/transfer_agent.rb
422
458
  - lib/aspera/cli/transfer_progress.rb
459
+ - lib/aspera/cli/vault_actions.rb
423
460
  - lib/aspera/cli/vault_manager.rb
424
461
  - lib/aspera/cli/version.rb
425
462
  - lib/aspera/cli/web_secret.html.erb
@@ -447,14 +484,6 @@ files:
447
484
  - lib/aspera/id_generator.rb
448
485
  - lib/aspera/json_rpc/client.rb
449
486
  - lib/aspera/json_rpc/version.rb
450
- - lib/aspera/keychain/base.rb
451
- - lib/aspera/keychain/encrypted_hash.rb
452
- - lib/aspera/keychain/factory.rb
453
- - lib/aspera/keychain/hashicorp_vault.rb
454
- - lib/aspera/keychain/macos_security.rb
455
- - lib/aspera/keychain/one_password_api.rb
456
- - lib/aspera/keychain/one_password_base.rb
457
- - lib/aspera/keychain/one_password_cli.rb
458
487
  - lib/aspera/line_logger.rb
459
488
  - lib/aspera/link_header.rb
460
489
  - lib/aspera/log.rb
@@ -468,6 +497,7 @@ files:
468
497
  - lib/aspera/oauth/client/generic.rb
469
498
  - lib/aspera/oauth/client/json_credentials.rb
470
499
  - lib/aspera/oauth/client/jwt.rb
500
+ - lib/aspera/oauth/client/shares_web.rb
471
501
  - lib/aspera/oauth/client/url_json.rb
472
502
  - lib/aspera/oauth/client/web.rb
473
503
  - lib/aspera/oauth/server/authorize.html.erb
@@ -486,6 +516,7 @@ files:
486
516
  - lib/aspera/products/desktop.rb
487
517
  - lib/aspera/products/other.rb
488
518
  - lib/aspera/products/transferd.rb
519
+ - lib/aspera/products/transferd_service.rb
489
520
  - lib/aspera/proxy_auto_config.js
490
521
  - lib/aspera/proxy_auto_config.rb
491
522
  - lib/aspera/rainbow.rb
@@ -509,9 +540,23 @@ files:
509
540
  - lib/aspera/schema/documentation.rb
510
541
  - lib/aspera/schema/reader.rb
511
542
  - lib/aspera/schema/registry.rb
543
+ - lib/aspera/schema/transferd-config.schema.json
512
544
  - lib/aspera/schema/validator.rb
513
- - lib/aspera/secret_hider.rb
514
- - lib/aspera/secret_strength.rb
545
+ - lib/aspera/sealed_hash.rb
546
+ - lib/aspera/secret/hider.rb
547
+ - lib/aspera/secret/reference.rb
548
+ - lib/aspera/secret/resolver.rb
549
+ - lib/aspera/secret/store/base.rb
550
+ - lib/aspera/secret/store/encrypted_hash.rb
551
+ - lib/aspera/secret/store/factory.rb
552
+ - lib/aspera/secret/store/hashicorp_vault.rb
553
+ - lib/aspera/secret/store/keeper.rb
554
+ - lib/aspera/secret/store/macos_security.rb
555
+ - lib/aspera/secret/store/one_password_api.rb
556
+ - lib/aspera/secret/store/one_password_base.rb
557
+ - lib/aspera/secret/store/one_password_cli.rb
558
+ - lib/aspera/secret/store/secret_service.rb
559
+ - lib/aspera/secret/strength.rb
515
560
  - lib/aspera/servlet_helpers.rb
516
561
  - lib/aspera/ssh.rb
517
562
  - lib/aspera/ssl.rb
@@ -529,8 +574,13 @@ files:
529
574
  - lib/aspera/transfer/resumer.rb
530
575
  - lib/aspera/transfer/spec.rb
531
576
  - lib/aspera/transfer/spec.schema.yaml
577
+ - lib/aspera/transfer/units.rb
532
578
  - lib/aspera/uri_reader.rb
533
579
  - lib/aspera/web_auth/index.html.erb
580
+ - lib/aspera/web_auth/paste.rb
581
+ - lib/aspera/web_auth/receiver.rb
582
+ - lib/aspera/web_auth/relay.rb
583
+ - lib/aspera/web_auth/reply.html.erb
534
584
  - lib/aspera/web_auth/server.rb
535
585
  - lib/aspera/web_page.html.erb
536
586
  - lib/aspera/web_page.rb
@@ -538,6 +588,8 @@ files:
538
588
  - lib/aspera/yaml.rb
539
589
  - lib/transferd_pb.rb
540
590
  - lib/transferd_services_pb.rb
591
+ - llms.txt
592
+ - skills/ascli/SKILL.md
541
593
  homepage: https://github.com/IBM/aspera-cli
542
594
  licenses:
543
595
  - Apache-2.0
@@ -555,7 +607,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
555
607
  requirements:
556
608
  - - ">="
557
609
  - !ruby/object:Gem::Version
558
- version: '3.2'
610
+ version: '3.3'
559
611
  required_rubygems_version: !ruby/object:Gem::Requirement
560
612
  requirements:
561
613
  - - ">="
@@ -565,6 +617,7 @@ requirements:
565
617
  - Read the manual for any requirement
566
618
  rubygems_version: 4.0.20
567
619
  specification_version: 4
568
- summary: 'Execute actions using command line on IBM Aspera Server products: Aspera
569
- on Cloud, Faspex, Shares, Node, Console, Orchestrator, High Speed Transfer Server'
620
+ summary: 'The automation interface for IBM Aspera, from command line to AI agents:
621
+ transfers, packages, files and administration of Aspera on Cloud, Faspex, Shares,
622
+ Node, Console, Orchestrator, High Speed Transfer Server'
570
623
  test_files: []
metadata.gz.sig CHANGED
Binary file
@@ -1,30 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Aspera
4
- module Keychain
5
- class Base
6
- CONTENT_KEYS = %i[label username password url description].freeze
7
-
8
- # Returns a lightweight list: one Hash per secret with :label (and :id if the backend has one).
9
- # Override in subclasses that can provide this cheaply without fetching full item details.
10
- def ids
11
- all.map { |s| s.slice(:id, :label).compact }
12
- end
13
-
14
- def validate_set(options)
15
- Aspera.assert_type(options, Hash) { 'options' }
16
- unsupported = options.keys - CONTENT_KEYS
17
- Aspera.assert(unsupported.empty?) { "unsupported options: #{unsupported}, use #{CONTENT_KEYS.join(', ')}" }
18
- options.each_pair do |k, v|
19
- Aspera.assert_type(v, String) { k.to_s }
20
- end
21
- Aspera.assert(options.key?(:label), 'label is required')
22
- end
23
-
24
- # Labels are unique: `set` does not overwrite an existing secret
25
- def assert_new_label(label)
26
- Aspera.assert(get(label: label, exception: false).nil?) { "secret #{label} already exist, delete first" }
27
- end
28
- end
29
- end
30
- end
@@ -1,192 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require 'aspera/hash_ext'
4
- require 'aspera/environment'
5
- require 'aspera/log'
6
- require 'aspera/assert'
7
- require 'aspera/keychain/base'
8
- require 'aspera/yaml'
9
- require 'openssl'
10
- require 'yaml'
11
-
12
- module Aspera
13
- module Keychain
14
- # Manage secrets in a simple Hash
15
- class EncryptedHash < Base
16
- LEGACY_CIPHER_NAME = 'aes-256-cbc'
17
- DEFAULT_CIPHER_NAME = 'aes-256-cbc'
18
- FILE_TYPE = 'encrypted_hash_vault'
19
- FILE_KEYS = %w[version type cipher data].sort.freeze
20
- FILE_KEYS_KDF = (%w[kdf] + FILE_KEYS).sort.freeze
21
- # PBKDF2 parameters for new vaults
22
- KDF_ITERATIONS = 200_000
23
- KDF_DIGEST = 'SHA256'
24
- KDF_SALT_BYTES = 16
25
- private_constant :LEGACY_CIPHER_NAME, :DEFAULT_CIPHER_NAME, :FILE_TYPE, :FILE_KEYS, :FILE_KEYS_KDF,
26
- :KDF_ITERATIONS, :KDF_DIGEST, :KDF_SALT_BYTES
27
-
28
- def initialize(file:, password:)
29
- super()
30
- Aspera.assert_type(file, String) { 'path to vault file' }
31
- @path = file
32
- Log.dump(:vault_file, @path)
33
- @all_secrets = {}
34
- @cipher_name = DEFAULT_CIPHER_NAME
35
- @kdf_params = nil
36
- # true when the vault was created by v4.26.0 (password padded with zeros, no KDF)
37
- @legacy_key = false
38
- vault_encrypted_data = nil
39
- Log.dump(:vault_file, File.expand_path(@path))
40
- if File.exist?(@path)
41
- vault_file = File.read(@path)
42
- if vault_file.start_with?('---')
43
- vault_info = Yaml.safe_load(vault_file)
44
- Aspera.assert_type(vault_info, Hash) { "Invalid vault file: #{@path}" }
45
- sorted_keys = vault_info.keys.sort
46
- Aspera.assert(sorted_keys == FILE_KEYS || sorted_keys == FILE_KEYS_KDF) { "Invalid vault file: #{@path}: #{sorted_keys}" }
47
- @cipher_name = vault_info['cipher']
48
- @kdf_params = vault_info['kdf']
49
- # vault created before PBKDF2 was introduced (v4.26.0 format: no kdf field)
50
- @legacy_key = @kdf_params.nil?
51
- vault_encrypted_data = vault_info['data']
52
- else
53
- # legacy vault file (binary, pre-YAML format)
54
- @cipher_name = LEGACY_CIPHER_NAME
55
- @legacy_key = true
56
- vault_encrypted_data = File.read(@path, mode: 'rb')
57
- end
58
- end
59
- # setting password also creates the cipher
60
- @cipher = cipher(password)
61
- @all_secrets = Yaml.safe_load(@cipher.decrypt(vault_encrypted_data)) || {} if !vault_encrypted_data.nil?
62
- end
63
-
64
- def info
65
- return {
66
- file: @path
67
- }
68
- end
69
-
70
- def all
71
- result = []
72
- @all_secrets.each do |label, values|
73
- normal = values.symbolize_keys
74
- normal[:label] = label
75
- CONTENT_KEYS.each { |k| normal[k] = '' unless normal.key?(k) }
76
- result.push(normal)
77
- end
78
- return result
79
- end
80
-
81
- # set a secret
82
- # @param options [Hash] with keys :label, :username, :password, :url, :description
83
- def set(options)
84
- validate_set(options)
85
- label = options.delete(:label)
86
- assert_new_label(label)
87
- @all_secrets[label] = options.symbolize_keys
88
- save
89
- end
90
-
91
- def get(label:, exception: true)
92
- Aspera.assert(@all_secrets.key?(label)) { "Label not found: #{label}" } if exception
93
- result = @all_secrets[label].clone
94
- result[:label] = label if result.is_a?(Hash)
95
- return result
96
- end
97
-
98
- def delete(label:)
99
- Aspera.assert(@all_secrets.key?(label)) { "Label not found: #{label}" }
100
- @all_secrets.delete(label)
101
- save
102
- end
103
-
104
- def change_password(password)
105
- # Generate new KDF params so a password change also re-salts the vault
106
- # (and migrates a legacy vault to PBKDF2)
107
- @legacy_key = false
108
- @kdf_params = nil
109
- @cipher = cipher(password)
110
- save
111
- end
112
-
113
- private
114
-
115
- # Minimal cipher wrapper using OpenSSL, compatible with the SymmetricEncryption
116
- # binary format: a 6-byte header "@EnC\x00\x00" followed by AES ciphertext
117
- # produced with a zero IV (encoding: :none, no random IV in header).
118
- class OsslCipher
119
- HEADER = "@EnC\x00\x00".b.freeze
120
- HEADER_SIZE = HEADER.bytesize
121
-
122
- def initialize(cipher_name, key)
123
- @cipher_name = cipher_name
124
- @key = key
125
- end
126
-
127
- def encrypt(plaintext)
128
- c = OpenSSL::Cipher.new(@cipher_name)
129
- c.encrypt
130
- c.key = @key
131
- c.iv = "\x00".b * c.iv_len
132
- HEADER + c.update(plaintext.b) + c.final
133
- end
134
-
135
- def decrypt(ciphertext)
136
- body = ciphertext.b[HEADER_SIZE..]
137
- c = OpenSSL::Cipher.new(@cipher_name)
138
- c.decrypt
139
- c.key = @key
140
- c.iv = "\x00".b * c.iv_len
141
- (c.update(body) + c.final).force_encoding(Encoding::UTF_8)
142
- end
143
- end
144
-
145
- # Derive an AES key from `new_password`.
146
- # @legacy_key is true for vaults created by v4.26.0 or earlier (no kdf field):
147
- # key = password truncated/zero-padded to key_bytes (same as symmetric-encryption did).
148
- # Otherwise PBKDF2 is used. When @kdf_params is nil (new vault or password change)
149
- # a fresh salt is generated; when already set (existing vault) it is reused.
150
- def cipher(new_password)
151
- key_bytes = @cipher_name.split('-')[1].to_i / Environment::BITS_PER_BYTE
152
- key =
153
- if @legacy_key
154
- # Replicate the v4.26.0 key derivation: password + NUL padding, truncated to key_bytes
155
- (new_password + ("\x00" * key_bytes))[0, key_bytes]
156
- else
157
- if @kdf_params.nil?
158
- # New vault or password change: generate a fresh salt
159
- salt = OpenSSL::Random.random_bytes(KDF_SALT_BYTES)
160
- @kdf_params = {
161
- 'algo' => 'PBKDF2',
162
- 'digest' => KDF_DIGEST,
163
- 'iterations' => KDF_ITERATIONS,
164
- 'salt' => [salt].pack('m0') # base64, no newlines
165
- }
166
- end
167
- salt = @kdf_params['salt'].unpack1('m0')
168
- OpenSSL::KDF.pbkdf2_hmac(
169
- new_password,
170
- salt: salt,
171
- iterations: @kdf_params['iterations'],
172
- length: key_bytes,
173
- hash: @kdf_params['digest']
174
- )
175
- end
176
- OsslCipher.new(@cipher_name, key)
177
- end
178
-
179
- # save current data to file with format
180
- def save
181
- vault_info = {
182
- 'version' => '1.1.0',
183
- 'type' => FILE_TYPE,
184
- 'cipher' => @cipher_name,
185
- 'kdf' => @kdf_params,
186
- 'data' => @cipher.encrypt(YAML.dump(@all_secrets))
187
- }
188
- Environment.write_file_restricted(@path, force: true) { YAML.dump(vault_info) }
189
- end
190
- end
191
- end
192
- end