aspera-cli 4.28.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 (242) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +217 -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 +122 -26
  10. data/SECURITY.md +84 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1895 -632
  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 +29 -22
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +95 -67
  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 +370 -0
  41. data/lib/aspera/ascp/log_locations.rb +163 -0
  42. data/lib/aspera/ascp/management.rb +16 -8
  43. data/lib/aspera/ascp/session_errors.rb +217 -0
  44. data/lib/aspera/assert.rb +4 -0
  45. data/lib/aspera/cli/ascp_actions.rb +12 -19
  46. data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
  47. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  48. data/lib/aspera/cli/bootstrapper.rb +38 -33
  49. data/lib/aspera/cli/command_line.rb +63 -8
  50. data/lib/aspera/cli/command_registry.rb +9 -1
  51. data/lib/aspera/cli/command_spec.rb +47 -7
  52. data/lib/aspera/cli/completion/ascli.bash +19 -5
  53. data/lib/aspera/cli/completion/ascli.fish +13 -2
  54. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  55. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  56. data/lib/aspera/cli/completion_actions.rb +303 -69
  57. data/lib/aspera/cli/context.rb +9 -4
  58. data/lib/aspera/cli/deprecation.rb +5 -2
  59. data/lib/aspera/cli/error.rb +6 -0
  60. data/lib/aspera/cli/extended_value.rb +66 -31
  61. data/lib/aspera/cli/formatter.rb +43 -30
  62. data/lib/aspera/cli/gem_checker.rb +9 -6
  63. data/lib/aspera/cli/hints.rb +22 -10
  64. data/lib/aspera/cli/http.rb +38 -10
  65. data/lib/aspera/cli/info.rb +12 -7
  66. data/lib/aspera/cli/mailer.rb +6 -3
  67. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  68. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  69. data/lib/aspera/cli/mcp/tool.rb +20 -17
  70. data/lib/aspera/cli/option_declarator.rb +10 -4
  71. data/lib/aspera/cli/option_registry.rb +6 -3
  72. data/lib/aspera/cli/option_types.rb +17 -2
  73. data/lib/aspera/cli/option_value.rb +77 -18
  74. data/lib/aspera/cli/options.schema.yaml +641 -80
  75. data/lib/aspera/cli/parser.rb +71 -35
  76. data/lib/aspera/cli/plugins/alee.rb +7 -4
  77. data/lib/aspera/cli/plugins/aoc.rb +248 -37
  78. data/lib/aspera/cli/plugins/ats.rb +10 -9
  79. data/lib/aspera/cli/plugins/base.rb +50 -18
  80. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  81. data/lib/aspera/cli/plugins/config.rb +210 -104
  82. data/lib/aspera/cli/plugins/console.rb +6 -3
  83. data/lib/aspera/cli/plugins/cos.rb +8 -4
  84. data/lib/aspera/cli/plugins/factory.rb +21 -7
  85. data/lib/aspera/cli/plugins/faspex5.rb +31 -26
  86. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  87. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  88. data/lib/aspera/cli/plugins/mcp.rb +42 -22
  89. data/lib/aspera/cli/plugins/node.rb +39 -38
  90. data/lib/aspera/cli/plugins/oauth.rb +23 -6
  91. data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
  92. data/lib/aspera/cli/plugins/preview.rb +72 -45
  93. data/lib/aspera/cli/plugins/server.rb +66 -14
  94. data/lib/aspera/cli/plugins/shares.rb +87 -18
  95. data/lib/aspera/cli/plugins/transferd.rb +228 -0
  96. data/lib/aspera/cli/poll.rb +236 -0
  97. data/lib/aspera/cli/preset_actions.rb +144 -30
  98. data/lib/aspera/cli/preset_manager.rb +113 -35
  99. data/lib/aspera/cli/prompt.rb +157 -9
  100. data/lib/aspera/cli/result.rb +12 -8
  101. data/lib/aspera/cli/runner.rb +89 -48
  102. data/lib/aspera/cli/secret_finder.rb +4 -1
  103. data/lib/aspera/cli/security.rb +89 -9
  104. data/lib/aspera/cli/special_values.rb +4 -1
  105. data/lib/aspera/cli/sync_actions.rb +15 -10
  106. data/lib/aspera/cli/table_fitter.rb +3 -0
  107. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  108. data/lib/aspera/cli/transfer_actions.rb +11 -8
  109. data/lib/aspera/cli/transfer_agent.rb +43 -20
  110. data/lib/aspera/cli/transfer_progress.rb +14 -45
  111. data/lib/aspera/cli/vault_actions.rb +45 -0
  112. data/lib/aspera/cli/vault_manager.rb +188 -42
  113. data/lib/aspera/cli/version.rb +4 -1
  114. data/lib/aspera/cli/web_secret.rb +12 -10
  115. data/lib/aspera/cli/wizard.rb +42 -39
  116. data/lib/aspera/command_line_builder.rb +9 -5
  117. data/lib/aspera/command_line_converter.rb +4 -1
  118. data/lib/aspera/coverage.rb +103 -33
  119. data/lib/aspera/data_repository.rb +4 -1
  120. data/lib/aspera/dot_container.rb +4 -1
  121. data/lib/aspera/environment.rb +23 -12
  122. data/lib/aspera/exec_spec.rb +3 -0
  123. data/lib/aspera/faspex_gw.rb +13 -9
  124. data/lib/aspera/faspex_postproc.rb +15 -12
  125. data/lib/aspera/formatter_interface.rb +4 -1
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +20 -5
  129. data/lib/aspera/inflate.rb +43 -0
  130. data/lib/aspera/json_rpc/client.rb +6 -5
  131. data/lib/aspera/json_rpc/version.rb +3 -0
  132. data/lib/aspera/line_logger.rb +4 -1
  133. data/lib/aspera/link_header.rb +4 -1
  134. data/lib/aspera/log.rb +18 -5
  135. data/lib/aspera/markdown.rb +5 -2
  136. data/lib/aspera/mime.rb +3 -0
  137. data/lib/aspera/nagios.rb +6 -4
  138. data/lib/aspera/node_emulator.rb +15 -13
  139. data/lib/aspera/oauth/client/base.rb +124 -73
  140. data/lib/aspera/oauth/client/boot.rb +7 -4
  141. data/lib/aspera/oauth/client/factory.rb +41 -18
  142. data/lib/aspera/oauth/client/generic.rb +5 -1
  143. data/lib/aspera/oauth/client/json_credentials.rb +7 -3
  144. data/lib/aspera/oauth/client/jwt.rb +6 -3
  145. data/lib/aspera/oauth/client/shares_web.rb +94 -0
  146. data/lib/aspera/oauth/client/url_json.rb +7 -3
  147. data/lib/aspera/oauth/client/web.rb +40 -13
  148. data/lib/aspera/oauth/server/pkce.rb +6 -5
  149. data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +16 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +17 -2
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +3 -0
  165. data/lib/aspera/rest/aspera_errors.rb +4 -1
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +45 -34
  168. data/lib/aspera/rest/error_analyzer.rb +5 -2
  169. data/lib/aspera/rest/list.rb +8 -4
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +8 -5
  172. data/lib/aspera/rest.rb +9 -6
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  175. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  176. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  177. data/lib/aspera/schema/async_tables.yaml +11 -10
  178. data/lib/aspera/schema/documentation.rb +8 -2
  179. data/lib/aspera/schema/reader.rb +7 -0
  180. data/lib/aspera/schema/registry.rb +44 -28
  181. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  182. data/lib/aspera/schema/validator.rb +4 -1
  183. data/lib/aspera/sealed_hash.rb +150 -0
  184. data/lib/aspera/secret/hider.rb +213 -0
  185. data/lib/aspera/secret/reference.rb +150 -0
  186. data/lib/aspera/secret/resolver.rb +212 -0
  187. data/lib/aspera/secret/store/base.rb +153 -0
  188. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  189. data/lib/aspera/secret/store/factory.rb +103 -0
  190. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  191. data/lib/aspera/secret/store/keeper.rb +141 -0
  192. data/lib/aspera/secret/store/macos_security.rb +284 -0
  193. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  194. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  195. data/lib/aspera/secret/store/one_password_cli.rb +112 -0
  196. data/lib/aspera/secret/store/secret_service.rb +125 -0
  197. data/lib/aspera/secret/strength.rb +119 -0
  198. data/lib/aspera/servlet_helpers.rb +5 -2
  199. data/lib/aspera/ssh.rb +10 -7
  200. data/lib/aspera/ssl.rb +5 -2
  201. data/lib/aspera/string_ext.rb +3 -0
  202. data/lib/aspera/sync/args.schema.yaml +3 -0
  203. data/lib/aspera/sync/conf.schema.yaml +9 -4
  204. data/lib/aspera/sync/database.rb +3 -0
  205. data/lib/aspera/sync/operations.rb +17 -15
  206. data/lib/aspera/temp_file_manager.rb +8 -4
  207. data/lib/aspera/timer_limiter.rb +3 -0
  208. data/lib/aspera/transfer/error.rb +4 -1
  209. data/lib/aspera/transfer/faux_file.rb +4 -1
  210. data/lib/aspera/transfer/parameters.rb +17 -14
  211. data/lib/aspera/transfer/result.rb +23 -0
  212. data/lib/aspera/transfer/resumer.rb +6 -4
  213. data/lib/aspera/transfer/spec.rb +9 -22
  214. data/lib/aspera/units/decimal.rb +67 -0
  215. data/lib/aspera/units/duration.rb +109 -0
  216. data/lib/aspera/uri_reader.rb +64 -9
  217. data/lib/aspera/web_auth/index.html.erb +6 -2
  218. data/lib/aspera/web_auth/paste.rb +109 -0
  219. data/lib/aspera/web_auth/receiver.rb +50 -0
  220. data/lib/aspera/web_auth/relay.rb +76 -0
  221. data/lib/aspera/web_auth/reply.html.erb +150 -0
  222. data/lib/aspera/web_auth/server.rb +47 -10
  223. data/lib/aspera/web_page.rb +7 -2
  224. data/lib/aspera/web_server_simple.rb +6 -3
  225. data/lib/aspera/yaml.rb +5 -1
  226. data/llms-install.md +88 -0
  227. data/llms.txt +87 -0
  228. data/skills/ascli/SKILL.md +94 -0
  229. data.tar.gz.sig +0 -0
  230. metadata +77 -20
  231. metadata.gz.sig +0 -0
  232. data/lib/aspera/duration.rb +0 -42
  233. data/lib/aspera/keychain/base.rb +0 -30
  234. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  235. data/lib/aspera/keychain/factory.rb +0 -58
  236. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  237. data/lib/aspera/keychain/macos_security.rb +0 -277
  238. data/lib/aspera/keychain/one_password_api.rb +0 -91
  239. data/lib/aspera/keychain/one_password_base.rb +0 -39
  240. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  241. data/lib/aspera/secret_hider.rb +0 -196
  242. data/lib/aspera/secret_strength.rb +0 -114
data/docs/README.md CHANGED
@@ -10,14 +10,16 @@ EDITING GUIDELINES:
10
10
  ellipsis : ... (not U+2026)
11
11
  - Emphasis style: use **bold** (double asterisks) only. Do not use *single asterisk italic*, _underscore_, or __double underscore__ style.
12
12
  DO NOT EDIT: THIS FILE IS GENERATED, edit docs/README.erb.md.
13
- PANDOC_DEFAULTS_BEGIN
14
- metadata:
15
- subtitle: "ascli 4.28.0"
16
- author: "Laurent Martin"
17
- PANDOC_DEFAULTS_END
18
13
  -->
19
14
  <!-- markdownlint-disable MD033 -->
20
15
 
16
+ <!-- gfm2pdf
17
+ common:
18
+ metadata:
19
+ subtitle: "ascli 4.29.1"
20
+ author: "Laurent Martin"
21
+ -->
22
+
21
23
  <!-- Admonitions: NOTE CAUTION WARNING IMPORTANT TIP INFO -->
22
24
 
23
25
  <!-- markdownlint-disable MD028 -->
@@ -28,9 +30,17 @@ PANDOC_DEFAULTS_END
28
30
 
29
31
  ### Overview
30
32
 
33
+ **The automation interface for IBM Aspera. From command line to AI agents.**
34
+
31
35
  The IBM Aspera Command Line Interface (`ascli`) is an enterprise-grade tool that provides comprehensive command-line access to IBM Aspera's suite of high-speed file transfer products and services.
32
36
  Designed for automation, scripting, and integration scenarios, `ascli` enables organizations to leverage Aspera's FASP technology within their existing workflows and DevOps pipelines.
33
37
 
38
+ > [!TIP]
39
+ > For any question about `ascli` (behavior, options), or to build a command line, give this manual to an AI assistant as a reference and ask it.
40
+ > See [Leveraging AI Assistance](#leveraging-ai-assistance).
41
+
42
+ ![Architecture: transfer agents, IBM Aspera applications and transfer servers](architecture.svg)
43
+
34
44
  ### Key Features
35
45
 
36
46
  **Multi-Product Integration**
@@ -45,6 +55,15 @@ Designed for automation, scripting, and integration scenarios, `ascli` enables o
45
55
  **Configuration Management**
46
56
  : Persistent configuration presets, environment variables, and flexible option handling for streamlined operations.
47
57
 
58
+ **Structured Output**
59
+ : JSON, YAML, CSV or tables, with filtering and JMESPath queries, for scripts, schedulers and CI/CD pipelines.
60
+
61
+ **Secrets Management**
62
+ : Secrets kept in a vault (encrypted file, HashiCorp Vault, Keeper, 1Password, macOS keychain, Linux Secret Service), never in scripts.
63
+
64
+ **AI Assistants and Agents**
65
+ : AI assistants operate IBM Aspera products with `ascli`, in a shell (with `llms.txt` or the agent skill) or through the built-in MCP server, with restrictions and without seeing secrets.
66
+
48
67
  **Developer Friendly**
49
68
  : Comprehensive logging, debugging capabilities, and API exploration tools for development and troubleshooting.
50
69
 
@@ -71,6 +90,16 @@ This manual is organized into the following sections:
71
90
 
72
91
  ### When to use and when not to use
73
92
 
93
+ | Need | Best choice | Why |
94
+ | ---- | ----------- | --- |
95
+ | Script or schedule transfers, packages, file management or administration of Aspera products (shell, `cron`, CI/CD) | `ascli` | One tool for all products, presets and vault per environment, structured output, automatic resume |
96
+ | Let an AI assistant or agent operate Aspera products | `ascli`: in a shell, or its MCP server | Same commands as people, restrictions, secrets never shown (see [Leveraging AI Assistance](#leveraging-ai-assistance)) |
97
+ | Administer, troubleshoot, or analyze `ascp` logs, interactively | `ascli` | Commands for every product, `ascp` log diagnostics |
98
+ | Learn or test an Aspera REST API | `ascli` | Shows the API calls (see [Logging, Debugging](#logging-debugging)) |
99
+ | Simple transfer with an HSTS, where nothing else can be installed | `ascp` | Included with every Aspera transfer product (see [`ascli` or `ascp`?](#ascli-or-ascp)) |
100
+ | Build an application (C/C++, Go, Python, Java, .NET, NodeJS...) | Aspera REST APIs and Transfer Daemon (gRPC) | Better for long-term development and maintenance |
101
+ | Users who transfer files with a graphical interface | IBM Aspera for Desktop, or the web interface of the application | Interactive use, no command line |
102
+
74
103
  > [!NOTE]
75
104
  > If you are scripting or automating transfers from the command line, `ascli` is the right choice.
76
105
  > If you are developing an application, prefer the APIs or SDKs instead.
@@ -166,7 +195,7 @@ This section walks you through your first interaction with `ascli` on Linux.
166
195
 
167
196
  ```shell
168
197
  mkdir -p $HOME/bin
169
- tar -C $HOME/bin -zxvf ascli-4.28.0-linux-x86_64.tgz
198
+ tar -C $HOME/bin -zxvf ascli-4.29.1-linux-x86_64.tgz
170
199
  export PATH=$PATH:$HOME/bin
171
200
  ```
172
201
 
@@ -180,13 +209,13 @@ ascli -v
180
209
  ```
181
210
 
182
211
  ```text
183
- 4.28.0
212
+ 4.29.1
184
213
  ```
185
214
 
186
215
  - Install the Aspera transfer runtime (tested version), as it is not included in the `ascli` package:
187
216
 
188
217
  ```shell
189
- ascli config transferd install
218
+ ascli transferd install
190
219
  ```
191
220
 
192
221
  ### Option A - Test with the Aspera Demo Server
@@ -240,7 +269,7 @@ The steps below create a preset, set it as the default for the server plugin, br
240
269
  - Create a preset with your server's connection details:
241
270
 
242
271
  ```shell
243
- ascli config preset update <SERVER_PRESET_NAME> --url=ssh://hsts.example.com:33001 --username=<USERNAME> --password=<PASSWORD>
272
+ ascli config preset set <SERVER_PRESET_NAME> @: url=ssh://hsts.example.com:33001 username=<USERNAME> password=<PASSWORD>
244
273
  ```
245
274
 
246
275
  ```text
@@ -267,10 +296,36 @@ If you'd prefer to test against Aspera on Cloud, skip ahead to the [AoC Wizard](
267
296
 
268
297
  ### Leveraging AI Assistance
269
298
 
270
- You can significantly accelerate your workflow by using an AI assistant to generate and troubleshoot commands for `ascli`.
271
- For the best results, provide the AI with the most recent documentation as context.
299
+ You can significantly accelerate your workflow by using an AI assistant with `ascli`.
300
+ There are three ways, the first one is the simplest:
301
+
302
+ - **The AI executes commands in a shell** (coding agents): nothing to set up, and no limitation: the AI uses `ascli` as you do, with your configuration.
303
+ Give it the file [`llms.txt`](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/llms.txt), located at the root of the gem and of the GitHub repository.
304
+ It tells the AI what `ascli` does with IBM Aspera products, and how to discover commands, arguments and options (`config commands`, `help`, `config options`, `config documentation`).
305
+ The same content is displayed by `ascli config skill`: an AI that can execute `ascli` can read it with no file to find.
306
+ With an AI client that supports agent skills, install the skill instead: the AI loads it by itself when a request is about IBM Aspera.
307
+ The skill, in the [Agent Skills](https://agentskills.io) format, is the folder `skills/ascli` of the gem (and of the GitHub repository): copy it to the skills folder of the AI client, for example:
308
+
309
+ ```shell
310
+ cp -R "$(gem contents aspera-cli | grep 'skills/ascli/SKILL.md$' | xargs dirname)" ~/.claude/skills/
311
+ ```
312
+
313
+ With Claude Code, install it as a plugin from the GitHub repository, which is also a plugin marketplace: it is updated with the repository.
314
+
315
+ ```text
316
+ /plugin marketplace add IBM/aspera-cli
317
+ /plugin install ascli@aspera-cli
318
+ ```
319
+
320
+ - **The AI executes commands through MCP**: for an AI client without a shell, start the [MCP server](#plugin-mcp-model-context-protocol-server) and register it in the AI client.
321
+ The AI discovers commands and their arguments by itself, and executes them.
322
+ By default, the server restricts what the AI can do (see [Security](#security)), and the AI never sees secrets.
323
+
324
+ - **The AI generates commands that you execute** (chat assistant that cannot execute commands): it cannot read the documentation through `ascli`, so provide it as context, as described below.
325
+
326
+ In the first two ways, the AI reads the documentation by itself, one section at a time, with `ascli config documentation`: there is no need to provide the manual.
272
327
 
273
- Recommended Workflow:
328
+ Recommended Workflow for a chat assistant:
274
329
 
275
330
  - **Contextualize**: Download the project manual (this manual in Markdown format, [`docs/README.md`](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md)) from the GitHub repository.
276
331
 
@@ -321,7 +376,7 @@ There are several ways to install `ascli`:
321
376
  - On Windows, as a [portable package](#windows-portable-package)
322
377
 
323
378
  This method is the simplest on Windows: extract and run. It includes Ruby, gems and `ascp`.
324
- - On Windows, with the [Chocolatey package](#windows-chocolatey-package) (installs Ruby and the gem).
379
+ - On Windows, with the [Chocolatey package](#windows-chocolatey-package): it installs the portable package and adds `ascli` to the `PATH`.
325
380
  - As a [container](#container) (`docker`, `podman`, `singularity`).
326
381
 
327
382
  The following sections describe the various installation methods.
@@ -347,7 +402,7 @@ This executable includes the Ruby runtime and gems, but not the transfer SDK.
347
402
 
348
403
  ```shell
349
404
  tar zxvf aspera-cli-<VERSION>-<PLATFORM>.tgz
350
- ./ascli config transferd install
405
+ ./ascli transferd install
351
406
  ```
352
407
 
353
408
  #### Linux: Checking the GLIBC version
@@ -406,7 +461,7 @@ The GLIBC of the system must be at least the version in the archive name, see [C
406
461
 
407
462
  > [!NOTE]
408
463
  > The launcher `ascli` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
409
- > So, `ascli config transferd install` is not needed.
464
+ > So, `ascli transferd install` is not needed.
410
465
 
411
466
  The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
412
467
  To upgrade, extract the new version, and update the symbolic link.
@@ -443,7 +498,7 @@ Apart from the prerequisite below, no installation step, no administrator rights
443
498
 
444
499
  > [!NOTE]
445
500
  > The launcher `ascli.cmd` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
446
- > So, `ascli config transferd install` is not needed.
501
+ > So, `ascli transferd install` is not needed.
447
502
 
448
503
  The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
449
504
  To upgrade, extract the new version, and update the `PATH` if the folder name changed.
@@ -451,7 +506,8 @@ To uninstall, delete the folder, and remove it from the `PATH` if it was added.
451
506
 
452
507
  ### Windows: Chocolatey package
453
508
 
454
- If you use [Chocolatey](https://chocolatey.org/), `ascli` can be installed with the `aspera-cli` package: it installs Ruby (if not already present) and the `aspera-cli` gem.
509
+ If you use [Chocolatey](https://chocolatey.org/), `ascli` can be installed with the `aspera-cli` package.
510
+ It installs the [portable package](#windows-portable-package) (Ruby, gems and `ascp` included, checked with its SHA-256) and adds only the command `ascli` to the `PATH`: no Ruby installation is needed.
455
511
 
456
512
  In a PowerShell as Administrator:
457
513
 
@@ -459,16 +515,16 @@ In a PowerShell as Administrator:
459
515
  choco install aspera-cli -y
460
516
  ```
461
517
 
462
- Then, install the Aspera Transfer Daemon, see [Installing `ascp` through `transferd`](#installing-ascp-through-transferd).
518
+ Upgrade with `choco upgrade aspera-cli`, uninstall with `choco uninstall aspera-cli` (the configuration is kept).
463
519
 
464
520
  ### Ruby
465
521
 
466
522
  A Ruby interpreter is required to run `ascli`.
467
523
 
468
- Required Ruby version is version: >= 3.2.
524
+ Required Ruby version is version: >= 3.3.
469
525
 
470
526
  > [!WARNING]
471
- > The minimum Ruby version will be 3.3 in a future version.
527
+ > The minimum Ruby version will be 3.4 in a future version.
472
528
 
473
529
  **Ruby can be installed using any of the following methods**: `rpm`, `yum`, `dnf`, `rvm`, `rbenv`, `brew`, Windows installer, ...
474
530
 
@@ -479,10 +535,21 @@ Required Ruby version is version: >= 3.2.
479
535
 
480
536
  For convenience, you may refer to the following sections for a proposed method for specific operating systems.
481
537
 
482
- `ascli` supports a Ruby version until 18 months after its [end of official support](https://www.ruby-lang.org/en/downloads/branches/).
538
+ `ascli` supports a Ruby version until 6 months after its [end of official support](https://www.ruby-lang.org/en/downloads/branches/).
483
539
  The minimum version is increased accordingly, and announced in advance.
484
540
  If only an older Ruby version must be used due to system constraints, use an older version of `ascli` that supports it; refer to [rubygems.org](https://rubygems.org/gems/aspera-cli).
485
541
 
542
+ The following table summarizes Ruby version life cycles and `ascli` support status:
543
+
544
+ | Ruby Version | Official EOL Date | ascli Support End (EOL + 6 mo) | ascli Status |
545
+ | ------------ | ----------------- | ------------------------------ | --------------------------------- |
546
+ | 4.0 | 2029-03-31 | 2029-09-30 | **Supported (Tested & Packaged)** |
547
+ | 3.4 | 2028-03-31 | 2028-09-30 | **Supported (Future minimum)** |
548
+ | 3.3 | 2027-03-31 | 2027-09-30 | **Supported (Current minimum)** |
549
+ | 3.2 | 2026-03-31 | 2026-09-30 | End of Support |
550
+ | 3.1 | 2025-03-26 | 2025-09-26 | End of Support |
551
+ | 3.0 | 2024-04-23 | 2024-10-23 | End of Support |
552
+
486
553
  #### Windows: Installer
487
554
 
488
555
  Manual installation:
@@ -545,6 +612,24 @@ Add it to your shell configuration file:
545
612
 
546
613
  #### Linux: Package
547
614
 
615
+ `ascli` supports Linux distributions that are officially maintained by their vendor (Red Hat for RHEL / UBI, Canonical for Ubuntu LTS).
616
+
617
+ - **GLIBC Requirement:** The Transfer SDK executables (`ascp`, `transferd`) and the Linux portable package require **`glibc >= 2.28`**.
618
+ - **Installation Compatibility:**
619
+ - If the OS provides a Ruby package or DNF module stream meeting the required version (≥ 3.3), the `aspera-cli` gem can be installed directly with `gem install`.
620
+ - If the OS is under maintenance but ships an older default system Ruby (e.g. Ubuntu 22.04 LTS with Ruby 3.0), `ascli` is fully supported via the [Linux portable package](#linux-portable-package), the [container image](#container), or a Ruby version manager (`rbenv`, `rvm`).
621
+
622
+ The following table summarizes supported Linux distributions, vendor end of support dates, GLIBC versions, available Ruby streams, and recommended `ascli` installation modes:
623
+
624
+ | Linux Distribution | OS Support End (EOL) | GLIBC (>= 2.28) | OS Ruby Version(s) | ascli Support / Mode |
625
+ | -------------------- | -------------------- | ------------------ | ------------------------------------ | ----------------------------------------------------- |
626
+ | **RHEL / UBI 10** | 2035-05-31 | 2.39+ (Compatible) | >= 3.3 (default) | Gem, Portable, Container |
627
+ | **RHEL / UBI 9** | 2032-05-31 | 2.34 (Compatible) | 3.0 (default), 3.1, 3.3 (DNF module) | Gem (`dnf module enable ruby:3.3`), Portable, Container |
628
+ | **RHEL / UBI 8** | 2029-05-31 | 2.28 (Compatible) | 3.1, 3.3 (DNF module) | Gem (`dnf module enable ruby:3.3`), Portable, Container |
629
+ | **Ubuntu 26.04 LTS** | 2031-05-29 | 2.43+ (Compatible) | >= 3.3 (APT package) | Gem, Portable, Container |
630
+ | **Ubuntu 24.04 LTS** | 2029-05-31 | 2.39 (Compatible) | 3.2 (APT package) | Gem (`apt install ruby-full`), Portable, Container |
631
+ | **Ubuntu 22.04 LTS** | 2027-06-01 | 2.35 (Compatible) | 3.0 (APT package) | Portable, Container, rbenv (OS Ruby < 3.2) |
632
+
548
633
  If your Linux distribution provides a standard Ruby package, you can use it provided that the version is supported.
549
634
 
550
635
  **Example:** RHEL 8+, Rocky Linux 8+: with extensions to compile native gems:
@@ -754,30 +839,30 @@ Those are not installed as part of dependencies because they involve compilation
754
839
  See [Gemfile](../Gemfile):
755
840
 
756
841
  | name | version | comment |
757
- |---------------------|-----------|-------------------------------------------------------------------------------|
842
+ | ---------------------- | --------- | -------------------------------------------------------------------------------- |
758
843
  | rake | ~> 13.0 | |
759
844
  | debug | ~> 1.11 | (no jruby) |
760
845
  | grpc-tools | ~> 1.67 | |
761
- | reek | ~> 6.5.0 | |
846
+ | reek | ~> 6.6.0 | |
762
847
  | rspec | ~> 3.0 | |
763
848
  | rubocop | ~> 1.75 | |
764
849
  | rubocop-ast | ~> 1.4 | |
765
850
  | rubocop-performance | ~> 1.10 | (no jruby) |
766
- | rubocop-shopify | ~> 2.0 | |
767
- | simplecov | ~> 0.22 | |
851
+ | rubocop-shopify | ~> 3.1 | |
852
+ | simplecov | ~> 1.3 | |
768
853
  | solargraph | ~> 0.48 | (no jruby) |
769
- | ferrum | ~> 0.19.1 | (no jruby) |
854
+ | ferrum | ~> 0.20.1 | (no jruby) |
770
855
  | mcp | ~> 1.2 | for ascli mcp server (MCP protocol support) |
771
856
  | rack | ~> 3.0 | for ascli mcp server HTTP transport (required by mcp StreamableHTTPTransport) |
772
857
  | grpc | ~> 1.71 | (no jruby) for Aspera Transfer Daemon |
773
858
  | sqlite3 | ~> 2.7 | (no jruby) for async DB |
774
859
  | jdbc-sqlite3 | ~> 3.46 | (jruby) for async DB |
775
860
  | sequel | ~> 5.96 | (jruby) for async DB |
776
- | ed25519 | ~> 1.4 | (no jruby) for ed25519 and OpenSSH file format |
777
- | bcrypt_pbkdf | ~> 1.1 | (no jruby) for ed25519 and OpenSSH file format |
861
+ | bcrypt_pbkdf | ~> 1.1 | (no jruby) for passphrase-protected OpenSSH private keys (ed25519 is native in net-ssh 8) |
778
862
  | syslog | ~> 0.3 | (no jruby) for logger=syslog |
779
863
  | zxcvbn | ~> 1.0 | for better estimate of secret strength (faspex5 postprocessing secret_token) |
780
- | rmagick | ~> 6.1 | (no jruby) for terminal view |
864
+ | keeper_secrets_manager | ~> 17.2 | for vault of type keeper (Keeper Secrets Manager) |
865
+ | rmagick | ~> 7.2 | (no jruby) for terminal view |
781
866
 
782
867
  Install like this:
783
868
 
@@ -785,26 +870,26 @@ Install like this:
785
870
  gem install rake -v '~> 13.0'
786
871
  gem install debug -v '~> 1.11'
787
872
  gem install grpc-tools -v '~> 1.67'
788
- gem install reek -v '~> 6.5.0'
873
+ gem install reek -v '~> 6.6.0'
789
874
  gem install rspec -v '~> 3.0'
790
875
  gem install rubocop -v '~> 1.75'
791
876
  gem install rubocop-ast -v '~> 1.4'
792
877
  gem install rubocop-performance -v '~> 1.10'
793
- gem install rubocop-shopify -v '~> 2.0'
794
- gem install simplecov -v '~> 0.22'
878
+ gem install rubocop-shopify -v '~> 3.1'
879
+ gem install simplecov -v '~> 1.3'
795
880
  gem install solargraph -v '~> 0.48'
796
- gem install ferrum -v '~> 0.19.1'
881
+ gem install ferrum -v '~> 0.20.1'
797
882
  gem install mcp -v '~> 1.2'
798
883
  gem install rack -v '~> 3.0'
799
884
  gem install grpc -v '~> 1.71'
800
885
  gem install sqlite3 -v '~> 2.7'
801
886
  gem install jdbc-sqlite3 -v '~> 3.46'
802
887
  gem install sequel -v '~> 5.96'
803
- gem install ed25519 -v '~> 1.4'
804
888
  gem install bcrypt_pbkdf -v '~> 1.1'
805
889
  gem install syslog -v '~> 0.3'
806
890
  gem install zxcvbn -v '~> 1.0'
807
- gem install rmagick -v '~> 6.1'
891
+ gem install keeper_secrets_manager -v '~> 17.2'
892
+ gem install rmagick -v '~> 7.2'
808
893
  ```
809
894
 
810
895
  ### Ruby gem: `aspera-cli`
@@ -880,7 +965,7 @@ The easiest option to install `ascp` is through the use of the IBM Aspera Transf
880
965
  Install it using `ascli` (for the current platform) with:
881
966
 
882
967
  ```shell
883
- ascli config transferd install
968
+ ascli transferd install
884
969
  ```
885
970
 
886
971
  The installation of the transfer binaries follows those steps:
@@ -893,6 +978,8 @@ The installation of the transfer binaries follows those steps:
893
978
  - This YAML file lists supported architectures (OS, CPU) and Aspera Transfer Daemon versions with their associated package URLs.
894
979
  - The SDK version is selected as follows: if an additional **positional parameter** is provided it specifies the version; if the special value `LATEST` is given the latest available version is used; otherwise the version tested with this release of `ascli` is used.
895
980
  - The package URL matching the current system architecture is then used.
981
+ - The request for the YAML file includes the version of `ascli` in the HTTP header `Referer`.
982
+ - The YAML file is not read if the requested version is already installed, or if option `sdk_url` gives the archive.
896
983
  - **Extract the archive**
897
984
  - By default, the archive is extracted to `$HOME/.aspera/sdk`.
898
985
  - The destination folder can be changed by setting the `sdk_folder` option.
@@ -903,30 +990,33 @@ The installation of the transfer binaries follows those steps:
903
990
  | `locations_url` | List of URLs to get download URLs of Aspera Transfer Daemon from IBM official repository, tried in order.<br/>A list given in options replaces the default list.<br/>Default:<br/>- `https://ibm.biz/sdk_location`<br/>- `https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/sdk_location.yaml`|
904
991
  | `sdk_folder` | Folder where the SDK archive is extracted.<br/>Default: `$HOME/.aspera/sdk` |
905
992
 
906
- Transfer Daemon versions available from `locations_url` can be listed with: `ascli config transferd list`
993
+ > [!NOTE]
994
+ > Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
995
+
996
+ Transfer Daemon versions available from `locations_url` can be listed with: `ascli transferd list`
907
997
 
908
998
  To install a specific version, for example, 1.1.3:
909
999
 
910
1000
  ```shell
911
- ascli config transferd install 1.1.3
1001
+ ascli transferd install 1.1.3
912
1002
  ```
913
1003
 
914
1004
  To get the download URL for a specific platform and version:
915
1005
 
916
1006
  ```shell
917
- ascli config transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url
1007
+ ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url
918
1008
  ```
919
1009
 
920
1010
  To download it, pipe to `config download`:
921
1011
 
922
1012
  ```shell
923
- ascli config transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url | ascli config download @stdin:
1013
+ ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url | ascli config download @stdin:
924
1014
  ```
925
1015
 
926
1016
  To install from a local file (air-gapped installation) instead of fetching from the internet, specify the location of the SDK file with option `sdk_url`:
927
1017
 
928
1018
  ```shell
929
- ascli config transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
1019
+ ascli transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
930
1020
  ```
931
1021
 
932
1022
  The format is: `file:///<PATH>` (canonical form) or `file:<PATH>` (short form), where `<PATH>` can be either a relative path (not starting with `/`), or an absolute path (starting with `/`).
@@ -942,7 +1032,7 @@ Supported platforms are listed in the [Release Notes](https://developer.ibm.com/
942
1032
 
943
1033
  If the embedded method is not used, the following packages are also suitable:
944
1034
 
945
- - IBM Aspera Connect Client (Free)
1035
+ - IBM Aspera Connect Client (Free, to be deprecated in 2027, use IBM Aspera for Desktop)
946
1036
  - IBM Aspera Desktop Client (Free)
947
1037
  - IBM Aspera for Desktop (Free)
948
1038
  - IBM Aspera High Speed Transfer Server (Licensed)
@@ -980,13 +1070,13 @@ For an air-gapped installation, two alternatives are available:
980
1070
  On a system with internet access, retrieve the SDK archive for the target platform and version:
981
1071
 
982
1072
  ```shell
983
- ascli config transferd list --select.platform=<PLATFORM> --select.version=<VERSION> --fields=url | ascli config download @stdin:
1073
+ ascli transferd list --select.platform=<PLATFORM> --select.version=<VERSION> --fields=url | ascli config download @stdin:
984
1074
  ```
985
1075
 
986
1076
  On the air-gapped system, install from the downloaded file using option `--sdk-url`:
987
1077
 
988
1078
  ```shell
989
- ascli config transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1079
+ ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
990
1080
  ```
991
1081
 
992
1082
  2. Retrieve the [single file executable](#single-file-executable) from the release, if available, and the SDK (not included) as described above.
@@ -999,11 +1089,11 @@ Alternatively, the necessary gems can be packaged into a `tar.gz` archive as fol
999
1089
 
1000
1090
  ```shell
1001
1091
  mkdir temp_folder
1002
- gem install aspera-cli:4.28.0 --no-document --install-dir temp_folder
1092
+ gem install aspera-cli:4.29.1 --no-document --install-dir temp_folder
1003
1093
  find temp_folder
1004
- mv temp_folder/cache aspera-cli-4.28.0-gems
1094
+ mv temp_folder/cache aspera-cli-4.29.1-gems
1005
1095
  rm -fr temp_folder
1006
- tar zcvf aspera-cli-4.28.0-gems.tgz aspera-cli-4.28.0-gems
1096
+ tar zcvf aspera-cli-4.29.1-gems.tgz aspera-cli-4.29.1-gems
1007
1097
  ```
1008
1098
 
1009
1099
  #### Unix-like: Alternative installation using `rvm`
@@ -1028,7 +1118,7 @@ The following procedure applies when using RVM for the Ruby installation:
1028
1118
  cd $HOME
1029
1119
  tar zxvf rvm-ascli.tgz
1030
1120
  source ~/.rvm/scripts/rvm
1031
- ascli config transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1121
+ ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1032
1122
  ```
1033
1123
 
1034
1124
  6. Add the following line to the shell environment file (`.profile`):
@@ -1076,7 +1166,7 @@ On the target system:
1076
1166
  4. Install the Aspera Transfer Daemon SDK:
1077
1167
 
1078
1168
  ```shell
1079
- ascli config transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1169
+ ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1080
1170
  ```
1081
1171
 
1082
1172
  ### Container
@@ -1139,7 +1229,7 @@ ascli -v
1139
1229
  ```
1140
1230
 
1141
1231
  ```text
1142
- 4.28.0
1232
+ 4.29.1
1143
1233
  ```
1144
1234
 
1145
1235
  To persist the configuration on the host, specify your user's configuration folder as a volume for the container.
@@ -1464,7 +1554,6 @@ Command line arguments that are not options are referred to as **Positional Argu
1464
1554
 
1465
1555
  For example:
1466
1556
 
1467
-
1468
1557
  ```shell
1469
1558
  ascli plugin command verb --option-name=VAL1 VAL2
1470
1559
  ```
@@ -1474,6 +1563,7 @@ ascli plugin command verb --option-name=VAL1 VAL2
1474
1563
 
1475
1564
  Enumeration values (positional arguments and option names/values) support prefix matching.
1476
1565
  See [Enumerations](#enumerations) for details.
1566
+
1477
1567
  For example `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`.
1478
1568
 
1479
1569
  The value of **Options** and **Command Parameters** is evaluated with the [Extended Value](#extended-value-syntax) syntax.
@@ -1580,7 +1670,6 @@ The following are enumerations:
1580
1670
 
1581
1671
  Examples:
1582
1672
 
1583
-
1584
1673
  - Positional: `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`
1585
1674
  - Option name: `--log-l=debug` is the same as `--log-level=debug`
1586
1675
  - Option value: `--format=c` is the same as `--format=csv`
@@ -1602,7 +1691,7 @@ Understanding this concept once makes it immediately usable everywhere it appear
1602
1691
  | [Option](#options) names | `--opt.key.sub=value` | Input | write |
1603
1692
  | [Positional arguments](#positional-arguments) | `@: key.sub=value ... [END]` | Input | write |
1604
1693
  | [Extended value](#extended-value-syntax) `@preset:` | `@preset:key.sub` | Input | read |
1605
- | [Output field names](#option-fields-selection-of-output-object-fields) | `--fields=key.sub` | Output | read |
1694
+ | [Output field names](#filtering-results) | `--out.fields=key.sub` | Output | read |
1606
1695
 
1607
1696
  A [dot-path](#dot-path-notation) is a `String` where segments are separated by `.` (dot), each segment designating a key in a nested structure:
1608
1697
 
@@ -1666,6 +1755,8 @@ The general syntax for this argument is:
1666
1755
  The optional text after `:` sets the end marker. If it is empty, the marker is `END`.
1667
1756
 
1668
1757
  - `<DOT_PATH>=<VALUE>`: An assignment using the standard [dot-path](#dot-path-notation) notation. Multiple assignments can be provided in sequence to build a complex object.
1758
+ The value is converted like any [dot-path](#dot-path-notation) value, and can be an [Extended Value](#extended-value-syntax), for example `public_key=@file:~/.ssh/id_rsa.pub`.
1759
+ Options placed among the assignments are not collected: they are processed as usual, for example `@: a=1 --format=json b=2`.
1669
1760
 
1670
1761
  - `<MARKER>` (`END` by default): An optional argument that ends the collection.
1671
1762
 
@@ -1788,6 +1879,44 @@ The behavior can be controlled with:
1788
1879
  - `--ask-options=<yes|no>` (default=no)
1789
1880
  - `yes`: Optional parameters/arguments are asked to the user.
1790
1881
 
1882
+ #### Hidden Input
1883
+
1884
+ Secrets (passwords, `@secret:`, code or URL pasted after a web login) are read without displaying them.
1885
+ On a terminal, a mark shows the state of the input, without revealing its length:
1886
+
1887
+ | Mark | ASCII | State |
1888
+ |------|-------|-------|
1889
+ | `🔑` | `***` | Waiting for input: nothing typed or pasted yet. |
1890
+ | `…` | `...` | Something was typed or pasted. |
1891
+ | `✓` (green) | `valid` | Checked input: it is valid. |
1892
+ | `✗` (red) | `invalid` | Checked input: it is not valid (yet), e.g. incomplete, mistyped or expired. |
1893
+
1894
+ The ASCII form is used when the locale does not support Unicode.
1895
+
1896
+ Some inputs are checked while they are typed or pasted, e.g. the code displayed by Shares after login (see [Authentication of SAML users](#authentication-of-saml-users)): `✓` or `✗` replaces `…`.
1897
+ If `Enter` is pressed on an input that is not valid, the error is displayed and the input is asked again (`Ctrl-C` to stop).
1898
+ If the standard input is not a terminal, an input that is not valid is an error.
1899
+
1900
+ Keys:
1901
+
1902
+ | Key | Action |
1903
+ |-----|--------|
1904
+ | `Enter` | End the input. |
1905
+ | `Backspace` | Erase the last character. |
1906
+ | `Ctrl-W` | Erase the last word. |
1907
+ | `Ctrl-U` | Erase all (for example, to paste again). |
1908
+ | `Ctrl-D` (Unix), `Ctrl-Z` (Windows) | End the input; if empty: error (end of input). |
1909
+ | `Ctrl-C` | Stop `ascli`. |
1910
+
1911
+ If the standard input is not a terminal (for example, a pipe), the line is read as is, without mark.
1912
+ It is the same if the terminal does not support reading characters one by one (raw mode).
1913
+
1914
+ To read secrets without any mark (no feedback, as `getpass`), set option `ui.hidden_silent` to `yes`:
1915
+
1916
+ ```shell
1917
+ ascli config preset set GLOBAL ui.hidden_silent yes
1918
+ ```
1919
+
1791
1920
  ### Output
1792
1921
 
1793
1922
  Command execution will result in output (terminal, stdout/stderr).
@@ -1838,9 +1967,212 @@ ascli config echo @json:'{"ni":null,"es":"","ea":[],"eh":{}}'
1838
1967
  ╰───────┴────────────────╯
1839
1968
  ```
1840
1969
 
1841
- #### Option: `format`
1970
+ #### Filtering results
1971
+
1972
+ The result of a command can be filtered on the server side, by the API, and then on the client side, by `ascli`.
1973
+ Filtering on the server side reduces the data transferred, while filtering on the client side accepts any condition.
1974
+
1975
+ Options are evaluated in this order:
1976
+
1977
+ ![Order of evaluation of the options that filter results](filtering-order.svg)
1978
+
1979
+ 1. `--query`: parameters sent to the API.
1980
+ 2. `--out.secrets`: secrets are hidden first, so that an expression cannot reveal them.
1981
+ 3. `--out.query`: JMESPath expression or Ruby lambda, applied to the data as returned by the API.
1982
+ 4. `--out.select`: selection of items (rows).
1983
+ 5. `--out.fields`: selection of fields (columns).
1984
+ 6. Display in the format set by `--out.format`.
1985
+
1986
+ | To | Use |
1987
+ |------------------------------------------|------------------------------------------|
1988
+ | Limit what the API returns | `--query`, with parameters `max` and `pmax` |
1989
+ | Filter on any condition, reshape, count | `--out.query` |
1990
+ | Select items by the value of fields | `--out.select` |
1991
+ | Choose the fields displayed | `--out.fields` |
1992
+
1993
+ ##### Option: `--query`: Parameters of the API
1994
+
1995
+ The `query` option can generally be used to add URL parameters to commands that list resources.
1996
+ It takes a `Hash`, corresponding to key/value pairs that appear in the query part of the request.
1997
+
1998
+ For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
1999
+
2000
+ If the same parameter needs to be provided several times, then it is also possible to provide an `Array`.
2001
+
2002
+ For example: `--query=@json:'{"p":["v1","v2"]}'` leads to query: `?p=v1&p=v2`.
2003
+
2004
+ If PHP-style arrays are expected in the API, add `[]` to the name of the parameter.
2005
+
2006
+ For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=v2`.
2007
+
2008
+ Commands that read a list by pages (for example, `aoc admin user list`) also accept parameters `max` and `pmax`.
2009
+ They are processed by `ascli`, not sent to the API: they limit the number of items (`max`) and of pages (`pmax`) requested.
2010
+
2011
+ For example: `--query.max=10` reads the first 10 items.
2012
+
2013
+ > [!TIP]
2014
+ > Use `--query=help` on any `list` command to display the available query parameters and their types, as documented in the API.
2015
+ > For example: `ascli faspex5 admin accounts list --query=help`
2016
+
2017
+ ##### Option: `--out.query`: JMESPath expression
2018
+
2019
+ Option `--out.query` applies a [JMESPath](https://jmespath.org) expression to the result of a command, when it is an object or a list.
2020
+ JMESPath is a standard query language for JSON, also used by option `--query` of the AWS and Azure CLIs.
2021
+
2022
+ The expression is applied to the data as returned by the API (secrets hidden), before options `--out.select` and `--out.fields`.
2023
+ Its syntax is checked before the command is executed.
2024
+ Results of other types (status, no result) are not changed.
2025
+
2026
+ Examples:
2027
+
2028
+ ```shell
2029
+ # Name and email of ATS administrators
2030
+ ascli aoc admin user list --out.query='[?ats_admin].{name: name, email: email}'
2031
+ # Number of users
2032
+ ascli aoc admin user list --out.query='length(@)'
2033
+ # Email of users, one per line, for use in a shell loop
2034
+ ascli aoc admin user list --out.query='[].email' --format=text
2035
+ ```
2036
+
2037
+ > [!TIP]
2038
+ > Enclose the expression in single quotes for the shell.
2039
+ > In JMESPath, literal values are enclosed in backticks, for example: ``[?size > `1000`]``.
2040
+ > An expression with string literals in single quotes (`'...'`) is enclosed in double quotes, for example: `"[?name=='Ann']"`.
2041
+
2042
+ For processing that JMESPath does not provide (regular expressions, string manipulation, grouping), the value can be a Ruby lambda (`@ruby:`): it is called with the data, and returns the new data, converted to JSON data (for example, symbols and dates become strings).
2043
+ It is refused at [Security Level](#security-level) `medium` and `high`.
1842
2044
 
1843
- The style of output can be set using the `format` option:
2045
+ ```shell
2046
+ # Number of users per email domain
2047
+ ascli aoc admin user list --out.query=@ruby:'->(users){users.group_by{|u|u["email"].split("@").last}.transform_values(&:count)}'
2048
+ ```
2049
+
2050
+ The result of the query is displayed according to its type: a list of objects as a table, a list of values with one value per line, a single value as is.
2051
+ A list of lists (for example, `[].[name, email]`) is displayed only with a structured format (`json`, `yaml`, ...): to display a table, or CSV, use a multi-select hash instead, for example, `[].{name: name, email: email}`.
2052
+
2053
+ > [!NOTE]
2054
+ > Option `--query` gives filtering parameters to the API, while option `--out.query` filters and reshapes the result received.
2055
+ > Option `--out.query` is the equivalent of option `--query` of the AWS and Azure CLIs.
2056
+
2057
+ ##### Option: `--out.select`: Selection of items
2058
+
2059
+ A list of objects (`object_list`) can be filtered with option `--out.select` (or `--select`).
2060
+ Its value is either a `Hash` or a `Proc`:
2061
+
2062
+ - `Hash`: an item is selected if each key of the `Hash` is a field of the item with the same value, and the same type: `true` (`Boolean`) is not `"true"` (`String`).
2063
+ - `Proc`: a Ruby lambda called with each item (`Hash`), that returns `true` to select it, or `false` to remove it.
2064
+
2065
+ Example:
2066
+
2067
+ ```shell
2068
+ ascli aoc admin user list --out.fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --out.select=@json:'{"ats_admin":true}'
2069
+ ```
2070
+
2071
+ ```text
2072
+ ╭────────────────┬─────────────────────┬───────────╮
2073
+ │ name │ email │ ats_admin │
2074
+ ╞════════════════╪═════════════════════╪═══════════╡
2075
+ │ John Curtis │ john@example.com │ true │
2076
+ │ Laurent Martin │ laurent@example.com │ true │
2077
+ ╰────────────────┴─────────────────────┴───────────╯
2078
+ ```
2079
+
2080
+ In the above example, the same result is obtained with option:
2081
+
2082
+ ```shell
2083
+ --out.select=@ruby:'->(i){i["ats_admin"]}'
2084
+ ```
2085
+
2086
+ A key can be a [dot-path](#dot-path-notation), for example, `directory_user.type`, with all formats.
2087
+
2088
+ ##### Option: `--out.fields`: Selection of fields
2089
+
2090
+ Depending on the command, results may include by default all fields, or only some selected fields.
2091
+ It is possible to define specific columns to be displayed, by setting option `--out.fields` (or `--fields`).
2092
+
2093
+ The `--out.fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
2094
+
2095
+ Individual elements of the list can be:
2096
+
2097
+ - **property**: add property to the current list
2098
+ - `-`**property**: remove property from the current list
2099
+ - `DEF`: default list of fields (that is the default, when not set)
2100
+ - `ALL`: all fields
2101
+ - A Ruby `RegEx`: using `@ruby:'/.../'`, or `@re:...` add those matching to the list
2102
+
2103
+ To display a **property** inside a complex structure (`Hash`, `Array`), use [dot-path](#dot-path-notation) notation, only with `--format=table` or `csv` (see option `--out.flat`).
2104
+ With other formats, use a JMESPath multi-select hash with option `--out.query`, for example: `--out.query='[].{name: name, type: directory_user.type}'`.
2105
+
2106
+ Examples:
2107
+
2108
+ - `a,b,c`: the list of attributes specified as a comma-separated list (overrides the default)
2109
+ - `@list:,a,b,c`: `Array` [Extended Value](#extended-value-syntax): same as above
2110
+ - `@json:'["a","b","c"]'`: `Array` [Extended Value](#extended-value-syntax): same as above
2111
+ - `b,DEF,-a`: default property list, remove `a` and add `b` in first position
2112
+ - `@ruby:'/^server/'`: Display all fields whose name begins with `server`
2113
+
2114
+ ##### `--out.select` or `--out.query`
2115
+
2116
+ Option `--out.select` is shorter for a test of equality, while option `--out.query` accepts any condition.
2117
+
2118
+ | Condition | `--out.select` | `--out.query` |
2119
+ |--------------------------|----------------------------------------------------|--------------------------------------------------|
2120
+ | Equal to a `Boolean` | `@json:'{"ats_admin":true}'` | `'[?ats_admin]'` |
2121
+ | Equal to a `String` | `@json:'{"name":"Ann"}'` | `"[?name=='Ann']"` |
2122
+ | Field of a nested object | `@json:'{"directory_user.type":"active_directory"}'` | `"[?directory_user.type=='active_directory']"` |
2123
+ | Several conditions (and) | `@json:'{"ats_admin":true,"name":"Ann"}'` | `"[?ats_admin && name=='Ann']"` |
2124
+ | Negation, or | Ruby lambda (`@ruby:`) | `'[?!ats_admin]'`, or: see [Recipes](#recipes) |
2125
+ | Number comparison | Ruby lambda (`@ruby:`) | ``'[?size > `1000000`]'`` |
2126
+ | Substring | Ruby lambda (`@ruby:`) | ``'[?contains(email, `@example`)]'`` |
2127
+ | Choice of fields | With option `--out.fields` | `'[].{name: name, email: email}'` |
2128
+ | Count | Not possible | `'length(@)'` |
2129
+
2130
+ > [!WARNING]
2131
+ >
2132
+ > - Values are compared with their type. With `--out.select`, `"true"` (`String`) does not match `true` (`Boolean`). In JMESPath, ``[?ats_admin == `true`]`` matches, but `[?ats_admin == 'true']` does not: `'...'` is a string literal.
2133
+ > - After `--out.query`, the default fields of the command no longer apply: all the fields of the result are displayed. Choose fields in the expression (multi-select hash), or with option `--out.fields`.
2134
+ > - Secrets are hidden before `--out.query` is applied, so that the expression cannot reveal them.
2135
+
2136
+ ##### Recipes
2137
+
2138
+ ```shell
2139
+ # Users of Active Directory, with user name and email
2140
+ ascli shares admin user all list --out.query="[?directory_user.type=='active_directory'].{username: username, email: email}"
2141
+ # Users without directory (field missing or null)
2142
+ ascli shares admin user all list --out.query='[?directory_user == null].username'
2143
+ # Number of ATS administrators
2144
+ ascli aoc admin user list --out.query='length([?ats_admin])'
2145
+ # Users who are ATS administrators, or have no email
2146
+ ascli aoc admin user list --out.query='[?ats_admin || !email].name'
2147
+ # Emails of a domain, one per line
2148
+ ascli aoc admin user list --out.query='[?ends_with(email, `@example.com`)].email' --format=text
2149
+ # Largest file of a folder
2150
+ ascli node browse / --out.query='max_by([?type==`file`], &size).path'
2151
+ # Files larger than 1 MB
2152
+ ascli node browse / --out.query='[?size > `1000000`].{path: path, size: size}'
2153
+ # Files modified since a date
2154
+ ascli node browse / --out.query='[?mtime >= `"2025-06-01"`].path'
2155
+ ```
2156
+
2157
+ > [!NOTE]
2158
+ > The JMESPath implementation of `ascli` (gem `jmespath`) also compares strings with `<`, `<=`, `>` and `>=`, which the JMESPath specification defines only for numbers.
2159
+ > Dates in ISO 8601 format, in the same time zone, are compared in chronological order.
2160
+
2161
+ The result in JSON (`--format=json`) can also be processed by other tools, such as [`jq`](https://jqlang.org), whose language differs from JMESPath: for example, `jq 'map(select(.directory_user.type == "active_directory"))'`.
2162
+
2163
+ ##### Other filters
2164
+
2165
+ Some commands provide their own filters:
2166
+
2167
+ - [Percent selector](#percent-selector) `%<field>:<value>`: selects a single resource by the value of one of its fields.
2168
+ - `find` of plugin `node` (gen4) and `aoc files find`: recursive search of files on the client side, with a glob or a Ruby lambda (see [Operation `find`](#operation-find-on-gen4access-key)).
2169
+ - `faspex5 packages list`: a Ruby lambda as last argument (see [Faspex 5: List packages](#faspex-5-list-packages)).
2170
+ - `console transfer`: query parameter `filter` (see [Transfer filter](#transfer-filter)).
2171
+ - `preview`: options `--filter` and `--skip-folders` (see [Candidate detection](#candidate-detection-for-creation-or-update-or-deletion)).
2172
+
2173
+ #### Option: `--out.format`
2174
+
2175
+ The style of output can be set using option `--out.format` (or `--format`):
1844
2176
 
1845
2177
  | `format` | Output formatting |
1846
2178
  | -------- | -------- |
@@ -1894,7 +2226,7 @@ ascli config echo @json:'[{"name":"foo","id":1},{"name":"bar","id":8}]' --format
1894
2226
 
1895
2227
  This option controls how object fields are displayed for complex objects.
1896
2228
 
1897
- Effective only when `format` is `table` to display `single_object` or `object_list`.
2229
+ Effective only when `format` is `table` or `csv` to display `single_object` or `object_list`.
1898
2230
 
1899
2231
  If value is `no`, then object's `field` names are only the first level keys of the `Hash` result and values that are `Hash` are displayed as such in Ruby syntax.
1900
2232
 
@@ -2076,110 +2408,59 @@ ascli config preset overview --out.colors=no --out.utf8=no
2076
2408
  > [!NOTE]
2077
2409
  > Logs issued before the option is processed (e.g. at startup) use the detected value.
2078
2410
 
2079
- #### Option: `fields`: Selection of output object fields
2411
+ ### Polling: Option `poll`
2080
2412
 
2081
- Depending on the command, results may include by default all fields, or only some selected fields.
2082
- It is possible to define specific columns to be displayed, by setting the `fields` option.
2083
-
2084
- The `fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
2413
+ Option `--poll` executes a read-only command several times, and displays its results, for example to wait for a state: a work order complete, a task waiting for a user, a package received.
2414
+ It replaces a shell loop with `sleep`: arguments are read once (identifiers looked up once), the command runs again in the same process.
2085
2415
 
2086
- Individual elements of the list can be:
2416
+ Its value is a `Hash` (also with dot-notation, e.g. `--poll.interval=10`):
2087
2417
 
2088
- - **property**: add property to the current list
2089
- - `-`**property**: remove property from the current list
2090
- - `DEF`: default list of fields (that is the default, when not set)
2091
- - `ALL`: all fields
2092
- - A Ruby `RegEx`: using `@ruby:'/.../'`, or `@re:...` add those matching to the list
2093
-
2094
- To display a **property** inside a complex structure (`Hash`, `Array`) use [dot-path](#dot-path-notation) notation.
2095
-
2096
- Examples:
2097
-
2098
- - `a,b,c`: the list of attributes specified as a comma-separated list (overrides the default)
2099
- - `@list:,a,b,c`: `Array` [Extended Value](#extended-value-syntax): same as above
2100
- - `@json:'["a","b","c"]'`: `Array` [Extended Value](#extended-value-syntax): same as above
2101
- - `b,DEF,-a`: default property list, remove `a` and add `b` in first position
2102
- - `@ruby:'/^server/'`: Display all fields whose name begins with `server`
2103
-
2104
- #### Option: `select`
2105
-
2106
- Table output (`object_list`) can be filtered using option `select`.
2107
- This option is either a `Hash` or `Proc`.
2108
- The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda expression that shall return `true` to select or `false` to remove an entry.
2109
-
2110
- Example:
2111
-
2112
- ```shell
2113
- ascli aoc admin user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
2114
- ```
2115
-
2116
- ```text
2117
- ╭────────────────┬─────────────────────┬───────────╮
2118
- │ name │ email │ ats_admin │
2119
- ╞════════════════╪═════════════════════╪═══════════╡
2120
- │ John Curtis │ john@example.com │ true │
2121
- │ Laurent Martin │ laurent@example.com │ true │
2122
- ╰────────────────┴─────────────────────┴───────────╯
2123
- ```
2124
-
2125
- > [!NOTE]
2126
- > Option `select` filters elements from the result of command, while the `query` option gives filtering parameters to the API when listing elements.
2127
-
2128
- In the above example, the same result is obtained with option:
2129
-
2130
- ```shell
2131
- --select=@ruby:'->(i){i["ats_admin"]}'
2132
- ```
2133
-
2134
- Option `select` applies the filter after a possible "flattening" with option `--out.flat`.
2135
-
2136
- For comparisons, functions or reshaping of results, use option `--out.query`.
2137
-
2138
- #### Option: `--out.query`
2139
-
2140
- Option `--out.query` applies a [JMESPath](https://jmespath.org) expression to the result of a command, when it is an object or a list.
2141
- JMESPath is a standard query language for JSON, also used by option `--query` of the AWS and Azure CLIs.
2142
-
2143
- The expression is applied to the data as returned by the API, before the options `select` and `fields`, and before flattening with `--out.flat`.
2144
- Its syntax is checked before the command is executed.
2145
- Results of other types (status, no result) are not changed.
2146
-
2147
- Examples:
2148
-
2149
- ```shell
2150
- # Name and email of ATS administrators
2151
- ascli aoc admin user list --out.query='[?ats_admin].{name: name, email: email}'
2152
- # Number of users
2153
- ascli aoc admin user list --out.query='length(@)'
2154
- # Email of users, one per line, for use in a shell loop
2155
- ascli aoc admin user list --out.query='[].email' --format=text
2156
- ```
2157
-
2158
- > [!TIP]
2159
- > Enclose the expression in single quotes for the shell.
2160
- > In JMESPath, literal values are enclosed in backticks, for example: ``[?size > `1000`]``.
2418
+ | Field | Type | Description |
2419
+ | -------- | -------------- | -------------------------------------------------------------------------------- |
2420
+ | `errors` | `Enum[String]` | What an error of a run does (e.g. an API error, an entity not found yet).<br/>- `fail`: the command ends with this error.<br/>- `retry`: the error is shown on the status line, and the command runs again, as for a result where `until` is false. If the last run fails, the command ends with its error.<br/>Allowed values: `fail`, `retry`.<br/>Default: `fail`. |
2421
+ | `interval` | `Number, String` | Time to wait after a run, before the next one. A duration: a number of seconds, or a `String`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00` (rounded down to seconds).<br/>Default: `5`. |
2422
+ | `max` | `Integer` | Maximum number of runs. No limit by default. |
2423
+ | `show` | `Enum[String]` | Which results are displayed.<br/>- `change`: the first result, then each result whose display differs from the previous one.<br/>- `each`: every result.<br/>- `last`: only the last result, when polling stops (including when the condition is not met).<br/>Allowed values: `change`, `each`, `last`.<br/>Default: `change`. |
2424
+ | `timeout` | `Number, String` | Maximum time since the start of the first run. A duration, as `interval`, e.g. `600`, `10m`, `1h`. A last run occurs at this time. No limit by default. With `max`, polling stops at the first limit reached. |
2425
+ | `until` | `String` | JMESPath expression (https://jmespath.org) evaluated on the JSON view of the result data: after `--select` (for a list of objects), before `--fields` and `--out.query`. Polling stops at the first run where it is true: as in JMESPath, `false`, `null`, empty string, empty list and empty object are false, other values are true. So `@` (the data itself) waits for a non-empty result, e.g. a list with at least one item. The syntax is checked before the first run. If the condition is not met after the last run (`max` or `timeout`), the command fails (exit code 1). |
2161
2426
 
2162
- For processing that JMESPath does not provide (regular expressions, string manipulation, grouping), the value can be a Ruby lambda (`@ruby:`): it is called with the data, and returns the new data, converted to JSON data (for example, symbols and dates become strings).
2163
- It is refused at [Security Level](#security-level) `medium` and `high`.
2427
+ `interval` and `timeout` are durations: a number of seconds, or a `String` with units `w`, `d`, `h`, `m`, `s`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00`, as for the [HTTP socket parameters](#http-socket-parameters).
2164
2428
 
2165
2429
  ```shell
2166
- # Number of users per email domain
2167
- ascli aoc admin user list --out.query=@ruby:'->(users){users.group_by{|u|u["email"].split("@").last}.transform_values(&:count)}'
2430
+ # Wait for a work order to complete, check every 10 seconds, at most 30 times
2431
+ ascli orchestrator workorders status <WORKORDER_ID> --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'
2432
+ # Same, with dot-notation, and a timeout of 10 minutes
2433
+ ascli orchestrator workorders status <WORKORDER_ID> --poll.interval=10s --poll.timeout=10m --poll.until='status == `Complete`'
2434
+ # Wait for a task waiting for a user (a non-empty list), display only the last result
2435
+ ascli orchestrator tasks list --poll=@json:'{"interval":5,"max":60,"until":"@","show":"last"}' --format=json
2436
+ # Display the status of the resources of a pool, each time it changes, until interrupted (Ctrl-C)
2437
+ ascli orchestrator pools status <POOL_NAME> --poll.interval=5
2168
2438
  ```
2169
2439
 
2170
- The result of the query is displayed according to its type: a list of objects as a table, a list of values with one value per line, a single value as is.
2171
- A list of lists (for example, `[].[name, email]`) is displayed only with a structured format (`json`, `yaml`, ...): to display a table, or CSV, use a multi-select hash instead, for example, `[].{name: name, email: email}`.
2440
+ Behavior:
2172
2441
 
2173
- > [!NOTE]
2174
- > Option `--query` gives filtering parameters to the API, while option `--out.query` filters and reshapes the result received.
2175
- > Option `--out.query` is the equivalent of option `--query` of the AWS and Azure CLIs.
2442
+ - Polling stops at the first run where `until` is true, or after `max` runs, or at `timeout`.
2443
+ - Without `until`, the command runs `max` times (or until `timeout`, or until interrupted), and the exit status is success.
2444
+ - If `until` is not true after the last run, the command fails with `condition not met after <N> runs` (exit status `1`).
2445
+ - `until` is evaluated on the data of the result (as seen by `--out.query`: JSON values), after `--out.select`, before `--out.fields` and `--out.query`.
2446
+ Expression `@` is true for a non-empty result: e.g. a list with at least one item.
2447
+ - Options `--format`, `--out.fields`, `--out.select` and `--out.query` apply to each result displayed.
2448
+ With `show=change` (default), a result is displayed when its display differs from the previous one.
2449
+ - Before each result displayed, a status line on `stderr` gives the run number and the time, e.g. `poll: run 3/30 2026-01-02 10:20:30`.
2450
+ Output is flushed after each result: it can be read line by line by another program, e.g. with `--format=json` (one line per result).
2451
+ - An error of a run (e.g. an API error) ends the command with this error, unless `errors` is `retry`: then the run counts as one where `until` is false.
2452
+ - `Ctrl-C` ends polling: with `show=last`, the last result is displayed, and the exit status is `130`.
2453
+
2454
+ For safety, option `poll` is refused, before anything is executed, on a command that is not marked read-only: a command that creates, modifies, deletes, sends, starts or cancels something, e.g. `faspex5 packages send`.
2455
+ Commands named `list`, `show`, `status`, `info`, `health`, `ls`, `browse` and `find` are read-only (except `preview show`, which generates a preview file), and some others, e.g. `orchestrator workflows workorders`, `server du`, `node ssync state`.
2456
+ It is also refused with options `once_only` (state saved at each run) and `notify_to` (email sent at each run), with format `nagios`, and in [MCP server](#plugin-mcp-model-context-protocol-server) mode (the client calls the tool again instead).
2176
2457
 
2177
2458
  ### Exit status
2178
2459
 
2179
2460
  The exit code of `ascli` indicates the category of error, so that scripts can react to it:
2180
2461
 
2181
2462
  | Code | Description |
2182
- |------|----------------------------------------------------------------------------|
2463
+ | ---- | -------------------------------------------------------------------------- |
2183
2464
  | `0` | Success |
2184
2465
  | `1` | Other error |
2185
2466
  | `2` | Command line error: unknown command or option, invalid or missing argument |
@@ -2256,10 +2537,10 @@ The following decoders are supported:
2256
2537
  | `stdin` | `String` | `String` | Read from stdin in text mode. Argument: `<empty>`, `bin` or `chomp`. |
2257
2538
  | `uri` | `String` | `String` | Read value from specified URL. Supported schemes: `http:`, `https:`, `data:`, `file:`. For example, `--fpac=@uri:http://serv/f.pac` or `--key=@uri:file:/path/to/key.pem` |
2258
2539
  | `val` | `String` | `String` | Prevent decoding by the decoders on the right. For example, `--key=@val:@file:foo` sets the option `key` to value `@file:foo`. |
2259
- | `vault` | `String` | `String` | Read a secret from the [Secret Vault](#secret-vault): `<label>.<field>`. For example, `--password=@vault:my_label.password` |
2540
+ | `vault` | `String` | `String` | Read a secret from the [Secret Vault](#secret-vault): `<label>.<field>`, or a [reference](#vault-secret-references) `//<store>/<path>[?<options>][#<field>]`. For example, `--password=@vault:my_label.password` |
2260
2541
  | `yaml` | `String` | Any | Decode YAML. |
2261
2542
  | `zlib` | `String` | `String` | Decompress data using zlib. |
2262
- | `<empty>`| None | Any | The **dot-path** modifier: argument `@:` collects the following positional arguments as `key.subkey=value` assignments and builds a `Hash` or `Array` using [dot-path](#dot-path-notation) notation. Shell-friendly alternative to `@json:` for structured values.<br/>See [Positional Arguments with Dot-path](#positional-arguments-with-dot-path) for full syntax. Use `END` to stop collection when further positional arguments must follow. |
2543
+ | `<empty>`| `String` | Any | The **dot-path** modifier: argument `@:` collects the following positional arguments as `key.subkey=value` assignments and builds a `Hash` or `Array` using [dot-path](#dot-path-notation) notation. Shell-friendly alternative to `@json:` for structured values.<br/>Argument is the end marker: `<empty>` for `END`, or a custom marker (e.g. `@:STOP`). Use the end marker to stop collection when further positional arguments must follow.<br/>See [Positional Arguments with Dot-path](#positional-arguments-with-dot-path) for full syntax. |
2263
2544
 
2264
2545
  > [!NOTE]
2265
2546
  > A few commands support a value of type `Proc` (lambda expression).
@@ -2270,7 +2551,21 @@ The following decoders are supported:
2270
2551
  To display the result of an [Extended Value](#extended-value-syntax), use the `config echo` command.
2271
2552
 
2272
2553
  The `extend` decoder is useful to evaluate embedded [Extended Value](#extended-value-syntax) syntax in a string.
2273
- It expects a `@` to close the embedded [Extended Value](#extended-value-syntax) syntax.
2554
+ It expects a `@` to close the embedded [Extended Value](#extended-value-syntax) syntax: `@vault:my_label.password@`.
2555
+ A value inserted by `extend` is not evaluated again: `@extend:@file:<PATH>@` inserts the content of the file as is.
2556
+ If the text on the right of `@extend:` is a single [Extended Value](#extended-value-syntax) without closing `@` (for example `@extend:@file:<PATH>`), it is decoded first, and embedded values in the result are then evaluated.
2557
+
2558
+ Example: a JSON file whose values are read from the [vault](#secret-vault):
2559
+
2560
+ ```json
2561
+ {"title":"Report","recipients":["@vault:my_label.username@"]}
2562
+ ```
2563
+
2564
+ ```shell
2565
+ ascli config echo @json:@extend:@file:<PATH>
2566
+ ```
2567
+
2568
+ In the file, an embedded value without closing `@` (`"@vault:my_label.username"`) is not evaluated: it stays a string, and `@json:@file:<PATH>` does not evaluate values inside the JSON.
2274
2569
 
2275
2570
  Option `parser` allows definition of a default parser when the positional parameter or option expects a `Hash` or `Array`.
2276
2571
  For example, with `--parser=json`, the parameter `{}` will be parsed as an empty JSON Hash, even without prefix `@json:`.
@@ -2550,7 +2845,6 @@ Adding `--show-config` to any command line performs a dry run and displays the r
2550
2845
  To display a specific option, add `--fields=<option_name>`.
2551
2846
  Add `--out.flat=no` when the option holds a structured value (`Hash`, `Array`) to display it as-is rather than flattened into dot-path keys:
2552
2847
 
2553
-
2554
2848
  ```shell
2555
2849
  ascli --opt=@json:'{"a":1,"b":"two"}' some_plugin --show-config --fields=opt --out.flat=no
2556
2850
  ascli --opt.a=1 --opt.b=two some_plugin --show-config --fields=opt --out.flat=no
@@ -2588,18 +2882,51 @@ It is a `Hash` with the following keys:
2588
2882
  |-----|-----|-----|-----|
2589
2883
  | `level` | `string` | `low` | `low`, `medium`, or `high` |
2590
2884
  | `allowed_paths` | `Array<string>` | - | With level `medium`: files and folders that `@file:` can read |
2885
+ | `writable_paths` | `Array<string>` | - | With levels `medium` and `high`: folders where files can be written |
2591
2886
 
2592
- | Level | `@file:` | `@ruby:`, `@uri:`, and `@env:` | Secret processed by another extended value |
2593
- |---|---|---|---|
2594
- | `low` | Allowed | Allowed | Allowed |
2595
- | `medium` | Only files in `allowed_paths` | Refused | Refused |
2596
- | `high` | Refused | Refused | Refused |
2887
+ | Level | `@file:` | `@ruby:`, `@uri:`, `@env:`, and `@zlib:` | Secret processed by another extended value | Write files | Features that execute code |
2888
+ |---|---|---|---|---|---|
2889
+ | `low` | Allowed | Allowed | Allowed | Allowed | Allowed |
2890
+ | `medium` | Only files in `allowed_paths` | Refused | Refused | Only in `writable_paths` | Refused |
2891
+ | `high` | Refused | Refused | Refused | Only in `writable_paths` | Refused |
2597
2892
 
2598
2893
  With level `medium`, the real path of the file is checked: a symbolic link leading outside of `allowed_paths` is refused.
2599
2894
 
2895
+ `@zlib:` is refused with levels `medium` and `high`: a small value can decompress to gigabytes and exhaust the memory of the system.
2896
+
2897
+ With levels `medium` and `high`, files are written only in `writable_paths` (none by default): downloaded files (`config download`, and transfers that receive files), because a file written where the client chooses could replace a file that is used later, for example a plugin or a shell startup file.
2898
+ The real path of the folder is checked: neither `..` nor a symbolic link leading outside of `writable_paths` is accepted.
2899
+
2900
+ > [!NOTE]
2901
+ > Reading files is not restricted for transfers: a command that sends files (for example `server upload`, or `orchestrator workflows import`) reads the files that it is given, whatever the level.
2902
+ > The security level restricts extended values, not the paths of transfers.
2903
+ > A command that reads a local file to display something about its content (for example `orchestrator workflows check_import`) reads it as `@file:`.
2904
+
2905
+ The same applies to `@file:<path>` in the parameters of stores of option `vault`, and in option `vault_password` (for example, `token`), although the file is read when used, not when the option is evaluated.
2906
+
2600
2907
  A secret (read by `@secret:`, `@vault:`, or `@preset:`) is hidden in results by its value: processed by another extended value, it could be revealed (for example, split by `@list:@vault:...`, or with a short value in a text by `@extend:`).
2601
2908
  With levels `medium` and `high`, a secret must be the whole value of an option or argument, for example `@preset:<PRESET_NAME>.password` for option `password`, and it cannot be a parameter name of `config preset set`.
2602
2909
 
2910
+ Features that execute code (own, or downloaded), load code, or write a file chosen by the client, are available only at level `low`:
2911
+
2912
+ | Feature | Why |
2913
+ |---|---|
2914
+ | Option `notify_template` | ERB template: Ruby code |
2915
+ | Option `fpac` | Proxy auto configuration: JavaScript code |
2916
+ | Option `ui`, key `command` | Command executed to open a URL |
2917
+ | Options `sdk_url` and `locations_url` | The SDK, including `ascp`, is downloaded from this location, then executed |
2918
+ | Option `out`, key `file` (and `output`), option `pid_file` | Write (or truncate, or delete) a file chosen by the client |
2919
+ | Option `home` | Configuration folder: its presets, and its folder `plugins` (Ruby code) are used |
2920
+ | Option `plugin_folder` | Plugins are Ruby code |
2921
+ | Plugins of the folder `plugins` of the configuration folder, and of option `plugin_folder` | Ruby code: not loaded at other levels, also if the file was there before |
2922
+ | Command `config plugins create` | Creates Ruby code, loaded as a plugin |
2923
+ | Command `faspex5 postprocessing` | Executes scripts, or Ruby code |
2924
+
2925
+ At other levels, an option is refused whatever the way it is set (command line, or preset), and a command is not listed by `config commands`.
2926
+ Values from the environment of the process (for example `ASCLI_HOME`) are not restricted: they are set by the one who starts the process, not by a client.
2927
+ A sub-option of an option is restricted in the same way: it is marked `x-security: low` in the schema of the option (for example, `file` of option `out`), and refused when given, by dot notation (`--out.file=...`) or in a `Hash`.
2928
+ A preset is used later, maybe at level `low`: at level `medium` and `high`, `config preset set` refuses such an option, and a value that contains an extended value that the level refuses (for example `@val:@ruby:...`).
2929
+
2603
2930
  Options are evaluated in the order of the command line: place `--security` before options that use extended values.
2604
2931
 
2605
2932
  ```shell
@@ -2607,7 +2934,7 @@ ascli config echo @file:/etc/hosts --security.level=high
2607
2934
  ```
2608
2935
 
2609
2936
  ```text
2610
- ERRR Argument: Evaluation of file for argument: value: @file: extended value is disabled by security level high
2937
+ ERRR Argument: Evaluation of @file: for argument: value: @file: extended value is disabled by security level high: use level medium with the file in security.allowed_paths (option security), or give the value itself
2611
2938
  ```
2612
2939
 
2613
2940
  ### Main, configuration and Persistency Folder
@@ -2740,61 +3067,56 @@ An [Option Preset](#option-preset) is a collection of options and their associat
2740
3067
  A named [Option Preset](#option-preset) can be modified directly using `ascli`, which will update the configuration file:
2741
3068
 
2742
3069
  ```text
2743
- ascli config preset <show|delete|get|unset|set|initialize|update|ask> <PRESET_NAME> ...
3070
+ ascli config preset <show|delete|get|set|ask> <PRESET_NAME> ...
2744
3071
  ```
2745
3072
 
2746
3073
  The syntax of all `config preset` commands, including `list` and `overview`, is displayed with `ascli config commands config preset`.
2747
3074
 
2748
- The command `initialize` allows setting several options at once, but it deletes an existing configuration instead of updating it, and expects a `Hash` [Extended Value](#extended-value-syntax).
3075
+ The command `set` merges values into the configuration, at one of three levels, depending on its arguments:
2749
3076
 
2750
- ```shell
2751
- ascli config preset initialize demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"<PASSWORD>","ts":{"precalculate_job_size":true}}'
2752
- ```
2753
-
2754
- One can also use [positional arguments with dot-path](#positional-arguments-with-dot-path):
2755
-
2756
- ```shell
2757
- ascli config preset initialize demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb password=<PASSWORD> ts.precalculate_job_size=true
2758
- ```
3077
+ | Arguments | Merged into | Example |
3078
+ | --------- | ----------- | ------- |
3079
+ | `<Hash>` | Presets, by name | `ascli config preset set @: demo_server.url=ssh://demo.asperasoft.com:33001 default.server=demo_server` |
3080
+ | `<preset_name> <Hash>` | Parameters of a preset | `ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb` |
3081
+ | `<preset_name> <parameter_name> <value>` | One parameter of a preset | `ascli config preset set demo_server password <PASSWORD>` |
2759
3082
 
2760
- The command `update` creates an [Option Preset](#option-preset) from options provided on the command line, for example:
3083
+ The `Hash` is usually given with [dot-path](#positional-arguments-with-dot-path) (`@:`), or with `@json:`.
3084
+ Parameters have the names of options, without `--`, for example:
2761
3085
 
2762
3086
  ```shell
2763
- ascli config preset update demo_server --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=<PASSWORD> --ts=@json:'{"precalculate_job_size":true}'
3087
+ ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb password=<PASSWORD> ts.precalculate_job_size=true
3088
+ ascli config preset set demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"<PASSWORD>","ts":{"precalculate_job_size":true}}'
2764
3089
  ```
2765
3090
 
2766
- This creates an [Option Preset](#option-preset) `demo_server` with all provided options.
2767
-
2768
- > [!NOTE]
2769
- > `update` takes **ALL** options provided on the command line (starting with `--` with a value).
2770
-
2771
- The command `set` allows setting individual options in an [Option Preset](#option-preset):
2772
-
2773
- ```text
2774
- ascli config preset set <PRESET_NAME> <PARAMETER_NAME> <PARAMETER_VALUE>
2775
- ```
3091
+ A preset is created if needed.
3092
+ Values are **deep-merged** (as JSON Merge Patch, RFC 7396): parameters not given are kept, also in a nested `Hash`: for example, `@: out.level=data` keeps `out.format`.
2776
3093
 
2777
- Example:
3094
+ The value `@none:` (`null` in JSON) **removes** a key: a parameter, a key in a nested `Hash`, or a whole preset (with its default declarations):
2778
3095
 
2779
3096
  ```shell
2780
- ascli config preset set demo_server password <PASSWORD>
3097
+ ascli config preset set GLOBAL out.table.pivot @none:
3098
+ ascli config preset set demo_server @: username=@none: ts.precalculate_job_size=@none:
3099
+ ascli config preset set @: demo_server=@none:
2781
3100
  ```
2782
3101
 
2783
- The parameter name supports **dot-notation** to set nested hash options.
2784
- If an intermediate hash already exists, the new value is **deep-merged** into it (existing sibling keys are preserved).
3102
+ The parameter name of the third form supports **dot-notation** to set nested hash options:
2785
3103
 
2786
3104
  ```shell
2787
3105
  ascli config preset set GLOBAL out.table.pivot single
2788
3106
  ascli config preset set GLOBAL out.level data
2789
3107
  ```
2790
3108
 
2791
- The parameter value is **automatically coerced** to its natural type: integers, floats and booleans (`true`/`yes`/`false`/`no`) are stored as native YAML types rather than strings.
3109
+ Values given on the command line (with `@:`, or the value of the third form) are **automatically coerced** to their natural type: integers, floats and booleans (`true`/`yes`/`false`/`no`) are stored as native YAML types rather than strings.
2792
3110
 
2793
- To **delete** a key from a preset, pass `@none:` as the value (evaluates to `nil`):
3111
+ Options of the command line are not saved in the preset: they apply to the command `set` itself (for example `--log-level`).
3112
+ The section `config` of the configuration file cannot be changed.
2794
3113
 
2795
- ```shell
2796
- ascli config preset set GLOBAL out.table.pivot @none:
2797
- ```
3114
+ > [!NOTE]
3115
+ > Commands `update`, `initialize` and `unset` are deprecated, and show the command to use instead:
3116
+ >
3117
+ > - `update <preset_name> --url=...` is replaced by `set <preset_name> @: url=...`. It takes only the options placed after `update`.
3118
+ > - `initialize <preset_name> <Hash>`, which replaces a preset, is replaced by `delete <preset_name>`, then `set <preset_name> <Hash>`.
3119
+ > - `unset <preset_name> <parameter_name>` is replaced by `set <preset_name> <parameter_name> @none:`.
2798
3120
 
2799
3121
  A full terminal based overview of the configuration can be displayed using:
2800
3122
 
@@ -2822,6 +3144,10 @@ demo_server:
2822
3144
  > [!NOTE]
2823
3145
  > Comment keys are preserved and visible in `config preset overview` for inspection, but are never injected as CLI options.
2824
3146
 
3147
+ By convention, `_comment` holds a short description of the preset.
3148
+ The [shell completion](#shell-completion) of preset names (e.g. `-P <tab>`) shows it next to each name.
3149
+ The wizard sets it for the presets it creates: `_comment: "wizard: <application>"`.
3150
+
2825
3151
  A good practice is to not manually edit the configuration file and use modification commands instead.
2826
3152
  If necessary, the configuration file can be opened in a text editor with:
2827
3153
 
@@ -2894,10 +3220,10 @@ Some temporary files may be needed during runtime, for example the file list of
2894
3220
  The composite option `temp` (use `--temp=help` to display this schema) controls them:
2895
3221
 
2896
3222
  | Field | Type | Description |
2897
- |--------|----------------------|----------------------------------------------------------------------------------|
3223
+ | ------ | -------------------- | -------------------------------------------------------------------------------- |
2898
3224
  | `clean` | `Bool` | Delete temporary files created by the command when it ends. `false` keeps them, e.g. for debugging. Files left by previous commands are still deleted according to `expiry`.<br/>Default: `true`. |
2899
3225
  | `expiry` | `String, Number, Bool` | Age after which file lists of `ascp` left by previous commands (e.g. interrupted) are deleted, when a command starts. They are in folder `filelists` of the main folder (option `home`). A duration, e.g. `5d`, `12h`, `1w`, `1h 30m`, `1d 02:00:00`, a plain number is seconds. `false` or `null` (`@none:`): never delete them. `0`: delete all of them, including file lists of transfers in progress in other executions of ascli. Such a transfer fails if `ascp` reads its file list again: next session of a multi-session transfer, or resume after an error. Use `0` only when no other transfer is in progress, not in a permanent configuration.<br/>Default: `5d`. |
2900
- | `folder` | `String` | Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd`. `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`). `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).<br/>Default: `@sys`. |
3226
+ | `folder` | `String` | Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd`.<br/>- `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`).<br/>- `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).<br/>Default: `@sys`. |
2901
3227
 
2902
3228
  A plain value is the `folder`, for example: `--temp=/data/tmp`.
2903
3229
 
@@ -2918,7 +3244,7 @@ Plugin `config` provides general commands for `ascli`:
2918
3244
  - `wizard`
2919
3245
  - `vault`
2920
3246
  - `ascp`
2921
- - `transferd`
3247
+ - `transferd` (deprecated, use plugin [`transferd`](#plugin-transferd-transfer-daemon))
2922
3248
 
2923
3249
  The default preset for `config` is read for any plugin invocation: this allows setting global options, such as `--log-level` or `--interactive`.
2924
3250
  When `ascli` starts, it looks for the `default` Option Preset and checks the value for `config`.
@@ -2960,6 +3286,9 @@ ascli config preset set GLOBAL version_check_days 0
2960
3286
  > Add `ascli config` in front of the following commands:
2961
3287
 
2962
3288
  ```shell
3289
+ agents jobs cleanup
3290
+ agents jobs list
3291
+ agents jobs status <CONF_ASYNC_NODE_UPLOAD>
2963
3292
  agents list
2964
3293
  agents parameters connect
2965
3294
  agents parameters direct
@@ -2968,9 +3297,6 @@ agents show connect
2968
3297
  agents show direct
2969
3298
  ascp errors
2970
3299
  ascp info --sdk-folder=sdk_test_dir
2971
- ascp install
2972
- ascp install --sdk-folder=sdk_test_dir
2973
- ascp install 1.1.3
2974
3300
  ascp products list
2975
3301
  ascp schema --format=jsonpp
2976
3302
  ascp show
@@ -2985,15 +3311,15 @@ commands
2985
3311
  commands aoc --expand-mounts=yes
2986
3312
  commands aoc files
2987
3313
  commands server
2988
- detect app.example.com
2989
- detect https://f5.example.com/path
2990
- detect https://f5.example.com/path faspex5
2991
- detect https://node.example.com/path
2992
- detect https://server.example.com/path
2993
- detect https://shares.example.com/path shares
2994
- detect https://tst.example.com/path faspio
2995
- detect https://tst.example.com/path httpgw
2996
- detect my_org aoc
3314
+ detect @: url=app.example.com
3315
+ detect @: url=https://f5.example.com/path
3316
+ detect @: url=https://f5.example.com/path plugin=faspex5
3317
+ detect @: url=https://node.example.com/path
3318
+ detect @: url=https://server1.example.com/path
3319
+ detect @: url=https://shares.example.com/path plugin=shares
3320
+ detect @: url=https://tst.example.com/path plugin=faspio
3321
+ detect @: url=https://tst.example.com/path plugin=httpgw
3322
+ detect @: url=my_org plugin=aoc
2997
3323
  doc
2998
3324
  doc github transfer-parameters
2999
3325
  doc local quick-start --ui=text
@@ -3041,49 +3367,50 @@ options server --select=@json:'{"option":"--display"}' --fields=replacement
3041
3367
  plugins create my_command .
3042
3368
  plugins list
3043
3369
  preset delete conf_name
3044
- preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
3045
3370
  preset list
3046
3371
  preset overview
3372
+ preset set @: conf_name.p4=v4 conf_name_other.p1=v1
3373
+ preset set @: conf_name_other=@none:
3047
3374
  preset set GLOBAL sdk_folder 'product:IBM Aspera Connect'
3048
- preset set GLOBAL vault @: type=file name=/secure/vault_file
3375
+ preset set GLOBAL vault @: default=local stores.local.type=file stores.local.file=/secure/vault_file
3049
3376
  preset set GLOBAL vault_password <PASSWORD>
3050
3377
  preset set GLOBAL version_check_days 0
3378
+ preset set conf_name @: p1=@none: p2.sub=v2 p3=v3
3379
+ preset set conf_name param @none:
3051
3380
  preset set conf_name param value
3052
3381
  preset set default shares conf_name
3053
3382
  preset show conf_name
3054
- preset unset conf_name param
3055
- preset update conf_name --p1=v1 --p2=v2
3056
3383
  proxy_check --fpac=@file:proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
3057
3384
  pubkey @file:my_key
3058
3385
  remote_certificate chain https://node.example.com/path
3059
3386
  remote_certificate name https://node.example.com/path
3060
3387
  remote_certificate only https://node.example.com/path
3388
+ skill
3061
3389
  smtp_settings
3062
3390
  sync spec
3063
3391
  tokens flush
3064
3392
  tokens list
3065
- transfer cleanup
3066
- transfer list
3067
- transfer status <conf_async_node_upload>
3068
- transferd install
3069
- transferd list
3393
+ vault check @vault://local/my_label
3070
3394
  vault create @: label=my_label password=<PASSWORD> 'description=my secret'
3071
3395
  vault delete foo --vault.type=system
3072
3396
  vault delete my_label
3397
+ vault field my_label
3073
3398
  vault ids
3074
3399
  vault info
3075
3400
  vault list
3401
+ vault overview
3076
3402
  vault show my_label
3077
- wizard https://console.example.com/path console
3078
- wizard https://f5.example.com/path faspex5 --key-path=my_private_key
3079
- wizard https://node.example.com/path node --username=test --password=<PASSWORD>
3080
- wizard https://orch.example.com/path orchestrator --username=test --password=<PASSWORD>
3081
- wizard https://server.example.com/path server --username=my_username --password=<PASSWORD>
3082
- wizard https://shares.example.com/path shares --username=test --password=<PASSWORD>
3083
- wizard https://tst.example.com/path faspio --override=yes --username=my_username --password=<PASSWORD>
3084
- wizard https://tst.example.com/path httpgw
3085
- wizard my_org aoc --key-path=my_private_key --username=my_user_email --use-generic-client=yes
3086
- wizard my_org aoc mypreset --key-path=my_private_key --username=my_user_email
3403
+ wizard @: url=https://console.example.com/path plugin=console override=yes --username=my_username --password=<PASSWORD>
3404
+ wizard @: url=https://f5.example.com/path plugin=faspex5 override=yes --username=my_username --private-key=@file:<PRIVATE_KEY_FILE> --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET>
3405
+ wizard @: url=https://node.example.com/path plugin=node override=yes --username=test --password=<PASSWORD>
3406
+ wizard @: url=https://orch.example.com/path plugin=orchestrator override=yes --username=test --password=<PASSWORD>
3407
+ wizard @: url=https://server1.example.com/path plugin=server override=yes --username=my_username --password=<PASSWORD>
3408
+ wizard @: url=https://shares.example.com/path plugin=shares override=yes --username=test --password=<PASSWORD>
3409
+ wizard @: url=https://tst.example.com/path plugin=faspio override=yes --username=my_username --password=<PASSWORD>
3410
+ wizard @: url=https://tst.example.com/path plugin=httpgw override=yes
3411
+ wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=no --interactive=yes
3412
+ wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=yes
3413
+ wizard @: url=my_org plugin=aoc preset=my_aoc_preset override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE>
3087
3414
  ```
3088
3415
 
3089
3416
  #### Evaluation order of options
@@ -3117,10 +3444,10 @@ ascli config preset set cli_default interactive no
3117
3444
  ascli config preset set default config cli_default
3118
3445
  ```
3119
3446
 
3120
- An [Option Preset](#option-preset) value can be removed with `unset`:
3447
+ An [Option Preset](#option-preset) value can be removed with `@none:`:
3121
3448
 
3122
3449
  ```shell
3123
- ascli config preset unset cli_default interactive
3450
+ ascli config preset set cli_default interactive @none:
3124
3451
  ```
3125
3452
 
3126
3453
  Example: Define options using command line:
@@ -3140,6 +3467,9 @@ ascli -N --preset=@json:'{"url":"<URL>","password":"<PASSWORD>","username":"<USE
3140
3467
  `ascli` supports shell tab-completion for **Bash**, **Zsh**, **Fish**, and **PowerShell** (Windows PowerShell 5.1 and PowerShell 7, on any OS).
3141
3468
  The command `ascli config completion <shell>` displays the completion script for the given shell.
3142
3469
 
3470
+ The default shell is Zsh on macOS, Bash on most Linux distributions, and PowerShell on Windows (its prompt starts with `PS`).
3471
+ In Bash and Zsh, `echo $0` displays the name of the running shell.
3472
+
3143
3473
  To activate completion, add the line for your shell to its startup file:
3144
3474
 
3145
3475
  ```bash
@@ -3185,26 +3515,40 @@ In PowerShell, the words proposed are kept for the session, so only the first `T
3185
3515
 
3186
3516
  Once active, press `Tab` to complete:
3187
3517
 
3188
-
3189
3518
  ```bash
3190
3519
  ascli <Tab> # plugins and global options: aoc, server, node, ..., --format, ...
3191
3520
  ascli server <Tab> # sub-commands and options of plugin: upload, download, ls, ..., --url, ...
3192
3521
  ascli aoc admin <Tab> # sub-commands at any depth: user, node, ...
3193
3522
  ascli server ls --u<Tab> # options, after any command: --url, --username, ...
3194
3523
  ascli --format=<Tab> # values of option: --format=json, --format=table, ...
3195
- ascli --ts.<Tab> # keys of option, from its schema: --ts.direction, --ts.target_rate_kbps, ...
3524
+ ascli --ts.<Tab> # keys of option, from its schema: --ts.direction=, --ts.target_rate_kbps=, ...
3525
+ ascli --out.t<Tab> # a sub-structure is followed by a dot: --out.table.
3196
3526
  ascli --ts.direction=<Tab> # values of key: --ts.direction=send, --ts.direction=receive
3527
+ ascli --transfer=<Tab> # plain value of option, key agent: --transfer=direct, --transfer=node, ...
3528
+ ascli faspex5 admin accounts list --query.<Tab> # keys of --query, from the command: --query.limit=, ...
3197
3529
  ascli server upload <Tab> # local files
3198
- ascli config preset show <Tab> # type of expected value, not inserted: <identifier>
3530
+ ascli server download --to-folder <Tab> # local folders
3531
+ ascli config genkey <Tab> # local files, where a local path is expected
3532
+ ascli --temp.folder=<Tab> # local folders, for a key of option
3533
+ ascli --ts=@<Tab> # extended value modifiers: @json:, @file:, @preset:, @:, ...
3534
+ ascli --private-key=@file:<Tab> # local files, after @file: or @path:
3535
+ ascli -P <Tab> # presets: also for config preset show, @preset:
3536
+ ascli config preset get myconf <Tab> # parameters of preset: url, username, ...
3537
+ ascli config agents jobs status <Tab> # asynchronous transfer jobs
3538
+ ascli node access_keys do <Tab> # type of expected value, not inserted: <identifier>
3199
3539
  ascli aoc packages send <Tab> # type, and keys of structure (required ones with *): <Hash> name*, workspace_id*, ...
3200
- ascli aoc packages send @: name=x <Tab> # end marker of structure built with @: END
3540
+ ascli aoc packages send @: <Tab> # keys of structure built with @:, from its schema: name=, workspace_id=, recipients.0., ...
3541
+ ascli aoc packages send @: archived=<Tab> # values of key: archived=true, archived=false
3542
+ ascli aoc packages send @: name=x <Tab> # end marker of structure built with @: END, and the other keys
3201
3543
  ```
3202
3544
 
3203
- Zsh, Fish and PowerShell also display the description of commands and options.
3545
+ No space is inserted after a word that continues: `key=`, `key.`, `@file:`, or a folder (Bash 4 and later).
3546
+ Zsh, Fish and PowerShell also display the description of commands, options, keys and extended value modifiers.
3547
+ In PowerShell, a word starting with `@` is inserted with quotes (e.g. `'@file:README.md'`), as required by PowerShell.
3204
3548
  Zsh lists options once `-` is typed (zsh style `prefix-needed`).
3205
3549
  The type of an expected value is displayed by Bash and Zsh, and by PowerShell in the list of `MenuComplete` (`Ctrl+Space`).
3206
3550
 
3207
- The scripts call `ascli config completion candidates -- [<word>...] <current word>`, which lists the candidates for the word at the cursor, with their description, followed by a directive for the shell.
3551
+ The scripts call `ascli config completion candidates -- [<word>...] <current word>`, which lists the candidates for the word at the cursor, with their description, followed by a directive for the shell: `:files` or `:folders` (local paths, followed by the beginning of the word that is not part of the path, if any, e.g. `:files --private-key=@file:`), `:hint <text>` or `:`.
3208
3552
  The words are not evaluated (e.g. `@env:` is not replaced).
3209
3553
  The command `ascli config completion words [<word>...]` lists the words that can follow the given ones.
3210
3554
  It can be used directly to inspect available commands:
@@ -3217,32 +3561,36 @@ ascli config completion words aoc admin
3217
3561
 
3218
3562
  The wizard is a command that asks the user for information and creates an [Option Preset](#option-preset) with the provided information for a given application.
3219
3563
 
3220
- It takes three optional arguments:
3564
+ It takes one optional argument: a `Hash`, usually given with [`@:`](#positional-arguments-with-dot-path) as `key=value` items, in any order:
3221
3565
 
3222
- |#| Parameter description | If not provided, `ascli` |
3223
- |-|--------------------------------------------|--------------------------------------------|
3224
- |1| **URL** or hostname of the application | ask for it. |
3225
- |2| The **plugin name** to limit search to | tries to detect known plugins from the URL |
3226
- |3| The **preset name** to save in config file | generates a unique preset name |
3566
+ | Key | Description | If not provided, `ascli` |
3567
+ |------------|---------------------------------------------------------------------------------|--------------------------------------------|
3568
+ | `url` | **URL** or hostname of the application | asks for it. |
3569
+ | `plugin` | The **plugin name** to limit search to | tries to detect known plugins from the URL |
3570
+ | `preset` | The **preset name** to save in config file | generates a unique preset name |
3571
+ | `default` | Set the preset as default configuration for the plugin (`yes`/`no`) | `yes` |
3572
+ | `override` | Override the existing default preset of the plugin, if it exists (`yes`/`no`) | `no` |
3227
3573
 
3228
- Options are also available for the wizard:
3574
+ Options of the plugin (for example `--username`, `--password`, `--client-id`, `--private-key`), see the plugin, are given as usual on the command line: they are added to the [Option Preset](#option-preset) created by the wizard.
3575
+ Options that the wizard needs, but that are not provided, are asked.
3576
+ An unknown key in the `Hash` is refused.
3229
3577
 
3230
- | Option | Value | Description |
3231
- |-------------|----------|---------------------------------------------------------------------|
3232
- | `default` | [yes]/no | Set as default configuration for specified plugin. |
3233
- | `override` | yes/[no] | Override existing default preset name for the plugin, if it exists. |
3234
- | `key_path` | path | Path to private key for JWT. |
3578
+ For example:
3235
3579
 
3236
- Other plugin-specific options can be provided to the wizard, such as `--username`.
3237
- They are added to the [Option Preset](#option-preset) created by the wizard.
3580
+ ```shell
3581
+ ascli config wizard @: url=<URL> plugin=<PLUGIN> preset=<PRESET>
3582
+ ```
3583
+
3584
+ The command `config detect` takes the same argument, with keys `url` and `plugin`, and shows the detected applications, without creating a preset.
3585
+ Use `ascli config wizard help` to show the schema of the argument.
3238
3586
 
3239
- The simplest invocation is:
3587
+ The simplest invocation (without argument: the URL is asked) is:
3240
3588
 
3241
3589
  ```shell
3242
3590
  ascli config wizard
3243
3591
  ```
3244
3592
 
3245
- If the application requires a private key, the user can provide the path to it with option `key_path`, or let the wizard generate one.
3593
+ If the application requires a private key, the user can provide it with option `--private-key` (the key, e.g. `@file:<path>`, not only its path), or let the wizard generate one.
3246
3594
  The user is told where to place the associated public key PEM in the application.
3247
3595
 
3248
3596
  #### Example of configuration for a plugin
@@ -3268,13 +3616,13 @@ ascli config preset set shares06 password <PASSWORD>
3268
3616
  This can also be done with one single command:
3269
3617
 
3270
3618
  ```shell
3271
- ascli config preset initialize shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"<PASSWORD>"}'
3619
+ ascli config preset set shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"<PASSWORD>"}'
3272
3620
  ```
3273
3621
 
3274
3622
  Or:
3275
3623
 
3276
3624
  ```shell
3277
- ascli config preset update shares06 --url=https://10.25.0.6 --username=john --password=<PASSWORD>
3625
+ ascli config preset set shares06 @: url=https://10.25.0.6 username=john password=<PASSWORD>
3278
3626
  ```
3279
3627
 
3280
3628
  - Define this [Option Preset](#option-preset) as the default [Option Preset](#option-preset) for the specified plugin (`shares`)
@@ -3326,7 +3674,71 @@ export ASCLI_PASSWORD
3326
3674
 
3327
3675
  Another possibility is to retrieve values from a secret vault.
3328
3676
 
3329
- The vault is configured with option `vault` (a `Hash` describing the vault type and parameters, see sections below) and unlocked with option `vault_password`.
3677
+ Option `vault` declares named secret stores (`stores`), and the name of the default store (`default`):
3678
+
3679
+ - `@vault:<label>.<field>` reads field `<field>` of secret `<label>` of the default store, managed with command `config vault` (see [Vault: Operations](#vault-operations)).
3680
+ - `@vault://<store>/<path>[?<options>][#<field>]` reads a secret of any store (see [Vault: Secret references](#vault-secret-references)).
3681
+
3682
+ | Field | Type | Description |
3683
+ | --------- | ------ | -------------------------------------------------------------------------------- |
3684
+ | `cache_ttl` | `Number` | Time in seconds a value read by reference is kept in memory, `0` for no cache.<br/>Default: `60`. |
3685
+ | `default` | `String` | Name of the default store, in `stores`: read by `@vault:<label>.<field>`, managed by `config vault`, unlocked with option `vault_password`. No default store if not set. |
3686
+ | `stores` | `Hash` | Name of store (letters, digits, `_`, `.`, `-`) → parameters of store, with `type`. Secrets are read by reference with `@vault://<store>/<path>[?<options>][#<field>]` from any store.<br/>Required. |
3687
+
3688
+ For example, to use as default store an encrypted file `vault.bin` in the configuration folder (see [Vault: Encrypted file](#vault-encrypted-file)):
3689
+
3690
+ ```shell
3691
+ ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
3692
+ ```
3693
+
3694
+ Parameters of a store, with `type` (see sections below):
3695
+
3696
+ | Field | Type | Description |
3697
+ | ----------------- | ------------- | -------------------------------------------------------------------------------- |
3698
+ | **type** | `String` | `vault`: IBM HashiCorp Vault secret store. Labels of `config vault` and `@vault:<label>.<field>` are in mount `secret` (KV v2). Reference `@vault://<store>/<mount>/<path>#<field>` (field required) in any KV v2 mount, options `version=<n>`, `mount=<mount>` (when the mount contains `/`). |
3699
+ | `allowed_prefixes` | `Array[String]` | Allowed prefixes of `<mount>/<path>` of references: a prefix ending with `/` is a folder, else a path or a folder. All paths are allowed if not set. |
3700
+ | `approle` | `Hash` | AppRole authentication: the token is obtained by login, renewed, and obtained again when refused. |
3701
+ | `approle.mount` | `String` | Mount path of the AppRole auth method.<br/>Default: `approle`. |
3702
+ | `approle.role_id` | `String` | Role ID.<br/>Required. |
3703
+ | `approle.secret_id` | `String` | Secret ID (if the role requires one): the value, or `@file:<path>`. |
3704
+ | `ca_file` | `String` | File with the CA certificates that verify the certificate of the server (HTTPS). |
3705
+ | `namespace` | `String` | Namespace (Vault Enterprise). |
3706
+ | `token` | `String` | The authentication token. Its value, or `@file:<path>` (e.g. written and renewed by Vault Agent), read again when modified. One of `token` or `approle` is required. For the default store, defaults to the value of `vault_password`, unless `approle` is set.<br/>Example: `<TOKEN>`. |
3707
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `vault`. |
3708
+ | `url` | `String` | URL of the HashiCorp Vault server.<br/>Required.<br/>Example: `http://127.0.0.1:8200`. |
3709
+ | **type** | `String` | `system`: macOS system keychain secret store. |
3710
+ | `name` | `String` | Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).<br/>Default: `ascli`. |
3711
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `system`. |
3712
+ | **type** | `String` | `secret_service`: Linux Secret Service secret store (GNOME Keyring, KWallet, KeePassXC...), using `secret-tool`. |
3713
+ | `name` | `String` | Name of the group of secrets (attribute `service` of the items).<br/>Default: `ascli`. |
3714
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `secret_service`. |
3715
+ | **type** | `String` | `file`: Encrypted file secret store. Reference `@vault://<store>/<label>[#<field>]`, field `password` by default. |
3716
+ | `file` | `String` | Path to the encrypted vault file, created when the first secret is added. Relative paths are resolved from the configuration folder. Read when used, and again when modified.<br/>Default: `vault.bin`. |
3717
+ | `name` | `String` | Same as `file` (compatibility). |
3718
+ | `password` | `String` | Password of the vault file: the value, or `@file:<path>`, read again when modified. For the default store, defaults to the value of `vault_password`. |
3719
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `file`. |
3720
+ | **type** | `String` | `1password`: 1Password secret store (Connect REST API or CLI). |
3721
+ | `account` | `String` | Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted. |
3722
+ | `source` | `Enum[String]` | Backend source. Use `api` for the Connect REST API, `cli` for the `op` CLI.<br/>Required.<br/>Allowed values: `api`, `cli`.<br/>Default: `api`. |
3723
+ | `token` | `String` | Bearer token for the Connect API (required when `source` is `api`). For the default store, defaults to the value of `vault_password`. |
3724
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `1password`. |
3725
+ | `url` | `String` | Base URL of the 1Password Connect server (required when `source` is `api`).<br/>Example: `http://localhost:8080`. |
3726
+ | `vault` | `String` | Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted. |
3727
+ | `vault_id` | `String` | ID of the 1Password vault to use (required when `source` is `api`). |
3728
+ | **type** | `String` | `keeper`: Keeper Secrets Manager secret store (Keeper Vault), using gem `keeper_secrets_manager`. A secret is a record shared with the application: its label is its title or its UID. Reference `@vault://<store>/<title or uid>[#<field>]`, field `password` by default: standard field by type (`login`, `password`, `url`...), custom field by label, or `notes`. |
3729
+ | `config` | `String` | Configuration of the client device (base64 or JSON, e.g. from `ksm profile export`): the value, or `@file:<path>`. For the default store, defaults to the value of `vault_password`. |
3730
+ | `folder_uid` | `String` | UID of the shared folder where `config vault create` adds records (not needed to read). |
3731
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `keeper`. |
3732
+
3733
+ > [!NOTE]
3734
+ > The parameters of one store, without `stores` (for example, `{"type":"file","name":"vault.bin"}`), are deprecated: they define a store named after its type (for example, `file`), which is the default store.
3735
+ > Set the store in `stores`, and its name in `default` instead: `{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}`.
3736
+
3737
+ Secrets used to access a store (`token`, `approle.secret_id`, `password`) are the value, or `@file:<path>` (for example, a credential of `systemd`, or a token written by Vault Agent): the file is read when used, and again when it is modified.
3738
+ As for extended value `@file:`, reading the file is restricted by option `security` (see [Security Level](#security-level)).
3739
+ In a YAML file, quote the value: `@` cannot start a plain scalar.
3740
+
3741
+ The secret of the default store (`password` of type `file`, `token` of type `vault` without `approle`, of type `1password` with `source` `api`, and `config` of type `keeper`), if not in its parameters, is the value of option `vault_password`.
3330
3742
  To avoid exposing the vault password in the shell history, provide it via an environment variable:
3331
3743
 
3332
3744
  ```shell
@@ -3352,29 +3764,20 @@ brew install hashicorp/tap/vault
3352
3764
  vault server -dev -dev-root-token-id=<TOKEN>
3353
3765
  ```
3354
3766
 
3355
- | Field | Type | Description |
3356
- |----------|--------|----------------------------------------------------------------------------------|
3357
- | **type** | `String` | `vault`: IBM HashiCorp Vault secret store. |
3358
- | `token` | `String` | Authentication token. Defaults to the value of `vault_password`.<br/>Example: `dev-only-token`. |
3359
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `vault`. |
3360
- | `url` | `String` | URL of the HashiCorp Vault server.<br/>Required.<br/>Example: `http://127.0.0.1:8200`. |
3361
- | **type** | `String` | `system`: macOS system keychain secret store. |
3362
- | `name` | `String` | Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).<br/>Default: `ascli`. |
3363
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `system`. |
3364
- | **type** | `String` | `file`: Encrypted file secret store. |
3365
- | `name` | `String` | Path to the encrypted vault file. Relative paths are resolved from the configuration folder.<br/>Default: `vault.bin`. |
3366
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `file`. |
3367
- | **type** | `String` | `1password`: 1Password secret store (Connect REST API or CLI). |
3368
- | `account` | `String` | Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted. |
3369
- | `source` | `String` | Backend source. Use `api` for the Connect REST API, `cli` for the `op` CLI.<br/>Required.<br/>Allowed values: `api`, `cli`.<br/>Default: `api`. |
3370
- | `token` | `String` | Bearer token for the Connect API (required when `source` is `api`). Defaults to the value of `vault_password`. |
3371
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `1password`. |
3372
- | `url` | `String` | Base URL of the 1Password Connect server (required when `source` is `api`).<br/>Example: `http://localhost:8080`. |
3373
- | `vault_id` | `String` | ID of the 1Password vault to use (required when `source` is `api`). |
3374
- | `vault` | `String` | Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted. |
3767
+ ```shell
3768
+ --vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"http://127.0.0.1:8200"}}}' --vault-password=<TOKEN>
3769
+ ```
3770
+
3771
+ With a token in a file (for example, written and renewed by Vault Agent), read again when the file is modified:
3772
+
3773
+ ```shell
3774
+ --vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","token":"@file:/run/vault/token"}}}'
3775
+ ```
3776
+
3777
+ With AppRole authentication, the token is obtained by login, and renewed:
3375
3778
 
3376
3779
  ```shell
3377
- --vault=@json:'{"type":"vault","url":"http://127.0.0.1:8200"}' --vault-password=<TOKEN>
3780
+ --vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","approle":{"role_id":"<ROLE_ID>","secret_id":"@file:/etc/vault/secret_id"}}}}'
3378
3781
  ```
3379
3782
 
3380
3783
  #### Vault: System keychain
@@ -3386,28 +3789,42 @@ It is possible to manage secrets in macOS keychain.
3386
3789
  Commands `list`, `ids` and `delete` are not supported: use the **Keychain Access** app.
3387
3790
 
3388
3791
  ```shell
3389
- --vault=@json:'{"type":"system","name":"ascli"}'
3792
+ --vault=@json:'{"default":"keychain","stores":{"keychain":{"type":"system","name":"ascli"}}}'
3793
+ ```
3794
+
3795
+ #### Vault: Linux Secret Service
3796
+
3797
+ > [!WARNING]
3798
+ > **Linux only**
3799
+
3800
+ It is possible to manage secrets in the Linux Secret Service (GNOME Keyring, KWallet, KeePassXC...), using the `secret-tool` command of `libsecret` (for example, package `libsecret-tools` on Debian and Ubuntu).
3801
+ A session with an unlocked keyring is required.
3802
+ Secrets are grouped with attribute `service`, which is parameter `name` (default: `ascli`).
3803
+
3804
+ ```shell
3805
+ --vault=@json:'{"default":"keyring","stores":{"keyring":{"type":"secret_service","name":"ascli"}}}'
3390
3806
  ```
3391
3807
 
3392
3808
  #### Vault: Encrypted file
3393
3809
 
3394
- It is possible to store and use secrets encrypted in a file using option `vault` set to:
3810
+ It is possible to store and use secrets encrypted in a file, with a store of type `file`:
3395
3811
 
3396
3812
  ```json
3397
- {"type":"file","name":"vault.bin"}
3813
+ {"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}
3398
3814
  ```
3399
3815
 
3400
- To configure the encrypted file vault as the default, set the `vault` option in the global preset:
3816
+ To configure the encrypted file vault as the default store, set the `vault` option in the global preset:
3401
3817
 
3402
3818
  ```shell
3403
- ascli config preset set GLOBAL vault @: type=file name=vault.bin
3819
+ ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
3404
3820
  ```
3405
3821
 
3406
- The vault file is created automatically on first use - no explicit initialization is needed.
3822
+ The vault file is created automatically when the first secret is added - no explicit initialization is needed.
3823
+ It is read when used, and again when it is modified.
3407
3824
 
3408
3825
  > [!WARNING]
3409
3826
  > The `vault_password` option should **not** be stored in the config file: doing so would protect secrets with a password that is itself stored in plain text, defeating the purpose of the vault.
3410
- > Use an environment variable as described above.
3827
+ > Use an environment variable as described above, or parameter `password` with `@file:<path>` (for example, a credential of `systemd`).
3411
3828
 
3412
3829
  #### Vault: 1Password
3413
3830
 
@@ -3428,7 +3845,7 @@ docker run -d --name op-connect \
3428
3845
  ```
3429
3846
 
3430
3847
  ```shell
3431
- --vault=@json:'{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}' \
3848
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}}}' \
3432
3849
  --vault-password=<CONNECT_TOKEN>
3433
3850
  ```
3434
3851
 
@@ -3448,9 +3865,9 @@ Requires the `op` CLI to be installed and signed in.
3448
3865
  No server to deploy: authentication is handled by the 1Password desktop app (biometric unlock) or by `op signin`.
3449
3866
 
3450
3867
  ```shell
3451
- --vault=@json:'{"type":"1password","source":"cli"}'
3868
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli"}}}'
3452
3869
  # or, to target a specific vault and account:
3453
- --vault=@json:'{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}'
3870
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}}}'
3454
3871
  ```
3455
3872
 
3456
3873
  > [!TIP]
@@ -3469,18 +3886,57 @@ An item can be referenced by its title (label) or by its 1Password ID, in `@vaul
3469
3886
  > [!NOTE]
3470
3887
  > If several items share the same title, use the item ID (or the `vault` parameter to restrict the search).
3471
3888
 
3889
+ #### Vault: Keeper
3890
+
3891
+ <https://docs.keeper.io/keeperpam/secrets-manager/overview>
3892
+
3893
+ Keeper Secrets Manager (KSM) gives an application access to the records of shared folders of a Keeper vault, without the credentials of a user.
3894
+ It requires the optional gem `keeper_secrets_manager`:
3895
+
3896
+ ```shell
3897
+ gem install keeper_secrets_manager
3898
+ ```
3899
+
3900
+ Create an application and a client device in Keeper (see the [Quick Start Guide](https://docs.keeper.io/keeperpam/secrets-manager/quick-start-guide)), share the folders of secrets with the application, and get the configuration of the device (base64 or JSON, for example with `ksm profile export`).
3901
+ Parameter `config` is the value, or `@file:<path>`:
3902
+
3903
+ ```shell
3904
+ --vault=@json:'{"default":"keeper","stores":{"keeper":{"type":"keeper","config":"@file:<KSM_CONFIG_FILE>"}}}'
3905
+ ```
3906
+
3907
+ If `config` is not set in the default store, it is the value of option `vault_password`.
3908
+
3909
+ A secret is a record of the vault: its label is its title, or its UID.
3910
+ The field of a reference is `password` by default: standard field of the record (`login`, `password`, `url`...), custom field by its label, or `notes`.
3911
+ Field `username` is an alias of `login`.
3912
+
3913
+ ```shell
3914
+ --password=@vault:<RECORD_TITLE>.password
3915
+ --password=@vault://keeper/<RECORD_TITLE>#<FIELD>
3916
+ ```
3917
+
3918
+ To create records with `config vault create` (type `login`), set parameter `folder_uid`: UID of the shared folder where records are added.
3919
+ Reading does not need it.
3920
+
3921
+ > [!NOTE]
3922
+ > If several records share the same title, use the UID.
3923
+ > Deleting a record with `config vault delete` requires that the application has edit permission.
3924
+
3472
3925
  #### Vault: Operations
3473
3926
 
3474
- Secrets can be manipulated using the `config vault` command:
3927
+ Secrets of the default store can be manipulated using the `config vault` command:
3475
3928
 
3476
3929
  - `info` : Show vault information
3477
3930
  - `ids` : List secret labels in the vault
3478
3931
  - `list` : List all secrets with full details
3932
+ - `overview` : List labels of all secrets with their field names, without values
3933
+ - `field` : List field names of a secret by label, without values
3479
3934
  - `show` : Show a secret by label (or id)
3480
3935
  - `create` : Add a new secret to the vault
3481
3936
  - `delete` : Delete a secret by label (or id)
3482
3937
  - `password` : Set a new password for the vault
3483
3938
  - `import` : Import secrets from a JSON array (supports `--bulk`)
3939
+ - `check` : Check that a [Secret Reference](#vault-secret-references) can be read, without its value
3484
3940
 
3485
3941
  To add a new password entry in the vault for label `<NAME>`:
3486
3942
 
@@ -3497,10 +3953,10 @@ To migrate all secrets from one vault backend to another (for example, from the
3497
3953
 
3498
3954
  ```shell
3499
3955
  ascli config vault list --format=json --out.level=data --out.secrets=yes \
3500
- --vault=@json:'{"type":"file","name":"<SOURCE_VAULT_FILE>"}' \
3956
+ --vault=@json:'{"default":"local","stores":{"local":{"type":"file","file":"<SOURCE_VAULT_FILE>"}}}' \
3501
3957
  --vault-password=<SOURCE_PASSWORD> | \
3502
3958
  ascli config vault import @json:@stdin: --bulk=yes \
3503
- --vault=@json:'{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}' \
3959
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}}}' \
3504
3960
  --vault-password=<CONNECT_TOKEN>
3505
3961
  ```
3506
3962
 
@@ -3512,6 +3968,44 @@ The `import` command accepts a JSON array where each element is a vault secret o
3512
3968
  On error (for example a duplicate label), the default behavior is to stop (`--bfail=yes`).
3513
3969
  Pass `--bfail=no` to skip failures and continue with the remaining entries.
3514
3970
 
3971
+ #### Vault: Secret references
3972
+
3973
+ Secrets can also be read by reference, from any store of option `vault`:
3974
+
3975
+ ```text
3976
+ @vault://<store>/<path>[?<options>][#<field>]
3977
+ ```
3978
+
3979
+ - `<store>`: name of a store in `stores` of option `vault`.
3980
+ - `<path>`: path of the secret in the store, and `<field>`: field of the secret. Both are percent-decoded (for example, `%20` for a space).
3981
+ For most types, the path is the label, and the field is `password` by default.
3982
+ For type `vault`, the path is `<mount>/<path>` in a KV v2 secrets engine, and the field is required.
3983
+ - `<options>`: options of the store, as a URL query (for example, `version=2`).
3984
+
3985
+ References only read secrets: they are managed with the tools of the store (for example, `vault kv put` for HashiCorp Vault), or with `config vault` for the default store.
3986
+ Compared to `@vault:<label>.<field>`, several stores can be used in the same command, and a HashiCorp Vault store reads any KV v2 mount, a given version, and limits the paths that can be read by reference (`allowed_prefixes`).
3987
+ Values read by reference are kept in memory for `cache_ttl` seconds.
3988
+ The configuration of stores is the same as in applications that use the library with references `secret://<store>/<path>` (for example, IBM Aspera Orchestrator).
3989
+
3990
+ For example, a HashiCorp Vault server with AppRole authentication, limited to secrets under `kv/aspera/`, and the encrypted file of `config vault` as default store, unlocked with option `vault_password`:
3991
+
3992
+ ```shell
3993
+ --vault=@json:'{"default":"local","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","approle":{"role_id":"<ROLE_ID>","secret_id":"@file:/etc/vault/secret_id"},"allowed_prefixes":["kv/aspera/"]},"local":{"type":"file","file":"vault.bin"}}}'
3994
+ ```
3995
+
3996
+ References in a preset: to field `password` of secret `aspera/faspex` in mount `kv`, and to field `password` (default field of type `file`) of label `<VAULT_LABEL>` in the encrypted file:
3997
+
3998
+ ```shell
3999
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://corp/kv/aspera/faspex#password
4000
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://local/<VAULT_LABEL>
4001
+ ```
4002
+
4003
+ To check that a reference can be read, without its value (store, version, time of update):
4004
+
4005
+ ```shell
4006
+ ascli config vault check @vault://corp/kv/aspera/faspex#password
4007
+ ```
4008
+
3515
4009
  #### Configuration Finder
3516
4010
 
3517
4011
  When a secret is needed by a sub command, the command can search for existing configurations in the configuration file by setting option `secret` to the special value `PRESET`.
@@ -3524,13 +4018,13 @@ A password can be saved in clear in an [Option Preset](#option-preset) together
3524
4018
  Example:
3525
4019
 
3526
4020
  ```shell
3527
- ascli config preset update <PRESET_NAME> --url=... --username=... --password=...
4021
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=...
3528
4022
  ```
3529
4023
 
3530
4024
  For more secure storage, first create a vault entry (see [Vault: Operations](#vault-operations)), then refer to it in the preset:
3531
4025
 
3532
4026
  ```shell
3533
- ascli config preset update <PRESET_NAME> --url=... --username=... --password=@val:@vault:<VAULT_LABEL>.password
4027
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault:<VAULT_LABEL>.password
3534
4028
  ```
3535
4029
 
3536
4030
  > [!NOTE]
@@ -3549,7 +4043,7 @@ This scans all presets (or a single one if a name is provided) and, for every op
3549
4043
  ascli config preset secure <PRESET_NAME>
3550
4044
  ```
3551
4045
 
3552
- When a vault is configured, the `update`, `set`, and `ask` preset commands automatically move secret values (options ending with `password` or `secret`) into the vault as they are written, so no manual migration is needed.
4046
+ When a vault is configured, the `set` and `ask` preset commands automatically move secret values (options ending with `password` or `secret`) into the vault as they are written, so no manual migration is needed.
3553
4047
  To disable this behavior for a single command, pass `--vault=@none:`.
3554
4048
 
3555
4049
  ### Private Key
@@ -3565,13 +4059,12 @@ The file containing the private key (key pair) can optionally be protected by a
3565
4059
  If the key is protected by a passphrase, then the passphrase is prompted when the key is used.
3566
4060
  Some plugins support option `passphrase`.
3567
4061
 
3568
- By default, `ascli` does not support `ed25519` type, nor OpenSSH encoded keys.
3569
- See section: [Private key type ed25519](#private-key-type-ed25519-not-supported-by-default).
3570
- It requires PEM encoded keys.
3571
- To support `ed25519` and OpenSSH format (default on modern Linux), install those gems:
4062
+ Keys of type `ed25519` and OpenSSH encoded keys (default on modern Linux) are supported.
4063
+ See section: [Private key type ed25519](#private-key-type-ed25519).
4064
+ For OpenSSH encoded keys protected by a passphrase, install gem `bcrypt_pbkdf` (not available for JRuby):
3572
4065
 
3573
4066
  ```shell
3574
- gem install ed25519 bcrypt_pbkdf
4067
+ gem install bcrypt_pbkdf
3575
4068
  ```
3576
4069
 
3577
4070
  The following sample commands use the shell variable `KEY_PAIR_PATH`.
@@ -3650,9 +4143,35 @@ For example: <https://cryptotools.net/rsagen>
3650
4143
 
3651
4144
  ### Web service
3652
4145
 
3653
- Some plugins start a local web server.
3654
- This server can serve HTTP or HTTPS (with certificate).
4146
+ `ascli` is a command-line tool: it runs in a shell, with the credentials and presets of the user who starts it, and it assumes that only this user uses it.
4147
+ It is not intended to be a public-facing web server.
4148
+ When commands come from another program, for example an MCP client, see [Security Level](#security-level).
4149
+
4150
+ Some commands start a web server, for a specific client:
4151
+
4152
+ | Command | Client | Protection required when `url` is not loopback |
4153
+ |---|---|---|
4154
+ | `mcp server`, `http` transport | MCP client | `auth_token`, see [MCP Security](#security) |
4155
+ | `faspex5 postprocessing` | Faspex 5 web hooks | `secret_token` or `allowed_ips`, see [Faspex 4-style post-processing](#faspex-5-faspex-4-style-post-processing) |
4156
+ | `faspex5 gateway`, `aoc gateway` | Faspex 4 client applications | `username` and `password`, see [Faspex 4 Gateway](#faspex-5-faspex-4-gateway) |
4157
+ | `node emulator` | Node API clients, for tests | `username` and `password`, see [Node emulator](#node-emulator) |
3655
4158
 
4159
+ By default, the server listens on a loopback address: `localhost`, an address of `127.0.0.0/8`, or `::1`.
4160
+ It can be reached only from the same host.
4161
+
4162
+ > [!WARNING]
4163
+ > Loopback restricts the host, not the user: on a host shared with other users, they can also reach the server.
4164
+ > On such a host, also set the protection of the command.
4165
+
4166
+ When the host of `url` is not a loopback address, for example `0.0.0.0` (all interfaces), the server can be reached from the network: the command refuses to start without its protection.
4167
+ On a network, use HTTPS (`https://` in `url`) or a reverse proxy with TLS: with HTTP, passwords and tokens are sent in clear.
4168
+
4169
+ Other features listen on a loopback address only, to receive input from the browser of the user:
4170
+
4171
+ - [Web login flow](#web-login-flow): the result of the login, on `redirect_uri`.
4172
+ - `@secret:`, with option `ui` set to `graphical` (see [Secret Vault](#secret-vault)), or with `mcp server` and the `stdio` transport (see [Secrets entered in a web page](#secrets-entered-in-a-web-page)): the secret entered by the user.
4173
+
4174
+ The server serves HTTP, or HTTPS with a certificate.
3656
4175
  The following parameters are supported:
3657
4176
 
3658
4177
  | Parameter | Type | Default | Description |
@@ -3692,7 +4211,7 @@ This feature can be used:
3692
4211
  The following options can be specified in option `--out.img`:
3693
4212
 
3694
4213
  | Field | Type | Description |
3695
- |------------|---------|----------------------------------------------------------------------------------|
4214
+ | ---------- | ------- | -------------------------------------------------------------------------------- |
3696
4215
  | `double` | `Bool` | Use double vertical resolution via half-block characters (Unicode). Default is `true` if the terminal supports Unicode (see `utf8`). |
3697
4216
  | `font_ratio` | `Number` | Terminal font aspect ratio (height divided by width).<br/>Default: `2.3`. |
3698
4217
  | `reserve` | `Integer` | Number of terminal lines reserved for non-image output.<br/>Default: `3`. |
@@ -3726,40 +4245,202 @@ Some actions may require the use of a graphical tool:
3726
4245
  - A browser to enter a secret requested with `@secret:`
3727
4246
  - A text editor for editing the configuration file
3728
4247
 
3729
- By default, `ascli` assumes that a graphical environment is available on Windows; on other systems, it relies on the presence of the `DISPLAY` environment variable.
3730
- The composite option `ui` (use `--ui=help` to display this schema) selects the mode and the browser command:
4248
+ By default, `ascli` assumes that a graphical environment is available on Windows and macOS; on other systems, it relies on the presence of the `DISPLAY` environment variable.
4249
+ The composite option `ui` (use `--ui=help` to display this schema) selects the mode, the way a web login is received, and the browser command:
3731
4250
 
3732
4251
  | Field | Type | Description |
3733
- |---------|---------------|----------------------------------------------------------------------------------|
3734
- | `command` | `Array[String]` | Command that opens a URL, instead of the system default. First item is the executable, then its arguments. The URL is added as last argument. When set, it is used to open URLs, whatever the `mode`. |
3735
- | `mode` | `String` | `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`. `terminal`: URLs and files to open are displayed on terminal, and secrets are entered on terminal. `browser`: a browser opens URLs, secrets are entered on a web page, and a text editor opens files. `text` is an alias for `terminal`, and `graphical` is an alias for `browser`.<br/>Allowed values: `auto`, `terminal`, `browser`, `text`, `graphical`.<br/>Default: `auto`. |
4252
+ | ------------- | ------------- | -------------------------------------------------------------------------------- |
4253
+ | `command` | `Array[String]` | Command that opens a URL, instead of the system default. First item is the executable (full path, or name of an executable found in `PATH`), then its arguments. The URL is added as last argument. When set, it is used to open URLs, whatever the `mode`. |
4254
+ | `hidden_silent` | `Bool` | Secrets typed or pasted on a terminal are read without any feedback (no echo, no mark), as `getpass`. By default, a mark shows whether something was typed or pasted, without revealing the length.<br/>Default: `false`. |
4255
+ | `mode` | `Enum[String]` | - `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`.<br/>- `terminal`: URLs to open are displayed on terminal, and secrets are entered on terminal.<br/>- `browser`: a browser opens URLs, and secrets are entered on a web page.<br/>`text` is an alias for `terminal`, and `graphical` is an alias for `browser`.<br/>Files to edit are always opened with a text editor, whatever the `mode`.<br/>Allowed values: `auto`, `terminal`, `browser`, `text`, `graphical`.<br/>Default: `auto`. |
4256
+ | `web_auth` | `Enum[String]` | How the result of a web login (`--auth=web`, SSO) is received.<br/>- `port`: `ascli` listens on the loopback port of `redirect_uri`, the browser is redirected to it.<br/>- `paste`: no port is opened. After login, the browser shows a connection error on `redirect_uri`: copy the full URL from the address bar of the browser and paste it in the terminal. Use it when the browser cannot reach the host that runs `ascli` and a SSH tunnel is not possible. For `shares`, Shares displays a code (a long text of letters, digits, `-` and `_`) instead: paste it in the terminal.<br/>Allowed values: `port`, `paste`.<br/>Default: `port`. |
3736
4257
 
3737
4258
  A plain value is the `mode`:
3738
4259
 
3739
- - `--ui=browser` (or `graphical`) forces a graphical environment: a browser is opened for URLs or secrets, or a text editor for files.
3740
- - `--ui=terminal` (or `text`) forces a text environment, the URL or file path to open is displayed on terminal, and secrets are entered on terminal.
4260
+ - `--ui=browser` (or `graphical`) forces a graphical environment: a browser is opened for URLs or secrets.
4261
+ - `--ui=terminal` (or `text`) forces a text environment: the URL to open is displayed on terminal, and secrets are entered on terminal.
3741
4262
  - `--ui=auto` selects the mode from the environment (default).
3742
4263
 
3743
4264
  The browser is opened, by priority, with: `--ui.command`, or the system default.
4265
+ The system default is opened with the following command:
4266
+
4267
+ | OS | Command |
4268
+ |---------|------------------------|
4269
+ | macOS | `open <url>` |
4270
+ | Windows | `start explorer "<url>"` |
4271
+ | Linux | `xdg-open <url>` |
4272
+
4273
+ To edit a file (for example `config open`), whatever the `mode`, the editor is, by priority: the command in the environment variable `EDITOR`, else `notepad.exe` on Windows, else the system default above (or `--ui.command` if defined).
4274
+
3744
4275
  When a command is defined, it is used to open URLs whatever the `mode`.
3745
4276
  The command is an array: the URL is appended as last argument.
4277
+ The executable is either a full path, or the name of an executable found in the `PATH`.
3746
4278
  For example, to use Firefox:
3747
4279
 
3748
4280
  ```bash
3749
4281
  ascli config echo @secret: --ui=browser --ui.command=@json:'["firefox","--private-window"]'
3750
4282
  ```
3751
4283
 
4284
+ ### Web login flow
4285
+
4286
+ Authentication methods that need a user login in a browser (`--auth=web`, including for Shares) all work the same way: `ascli` listens on a local port, the browser is redirected to it after login.
4287
+
4288
+ ![Web login flow: `ascli` listens on a loopback port and receives the result of the login from the browser](login-flow.svg)
4289
+
4290
+ 1. `ascli` generates a random `state` and starts a local HTTP server on the loopback address of `redirect_uri` (default: `http://localhost:12345`).
4291
+ 2. `ascli` opens the login URL in the browser (see [Graphical Interactions](#graphical-interactions-browser-and-text-editor)): the authorization endpoint with `redirect_uri` and `state` for `web`, or, for Shares, the SAML login page with `RelayState`.
4292
+ If no graphical environment is available, the URL is displayed, to be opened on any browser of the same host.
4293
+ 3. The user logs in on the server, possibly redirected to an identity provider.
4294
+ 4. The server redirects the browser to `redirect_uri`, with the OAuth code (`web`), or, for Shares, the tokens, and the `state`.
4295
+ 5. The browser sends this request to `ascli`, which checks that `state` is the one it generated, and stops listening.
4296
+ 6. `ascli` requests the token to the server: exchange of the code (`web`) or, for Shares, of the refresh token, and saves it in the cache.
4297
+ For Faspex 5, the code is protected with PKCE: `ascli` sends a challenge with the login URL, and the matching verifier with the code.
4298
+ Next calls use the cached token, renewed if needed without a browser.
4299
+
4300
+ The code or tokens never go to another host than the local one: the host of `redirect_uri` shall be loopback.
4301
+
4302
+ #### Option `ui.web_auth`
4303
+
4304
+ Option `ui.web_auth` (part of the composite option `ui`, see [Graphical Interactions](#graphical-interactions-browser-and-text-editor)) selects how the result of a web login is received:
4305
+
4306
+ | Value | Local port | Use when |
4307
+ |------------------|------------|----------|
4308
+ | `port` (default) | Yes: `ascli` listens on the loopback address of `redirect_uri` | The browser runs on the same system as `ascli`, or an SSH tunnel is possible. |
4309
+ | `paste` | No: `redirect_uri` is only used in the login URL | The browser cannot reach the system that runs `ascli`, and no tunnel is possible. |
4310
+
4311
+ With `paste`, after login the user gives the result to `ascli` through the terminal (it is hidden, as it contains a code or tokens: see [Hidden Input](#hidden-input)):
4312
+
4313
+ - the code displayed by Shares (a long text of letters, digits, `-` and `_`), or the code shown by `ascli config web_login` on the workstation,
4314
+ - or the full URL (or only the query) from the address bar of the browser, which shows a connection error on `redirect_uri`: this is expected.
4315
+
4316
+ In all cases the `state` is checked.
4317
+ Details are in the following sections.
4318
+
4319
+ Example:
4320
+
4321
+ ```shell
4322
+ ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
4323
+ ```
4324
+
4325
+ #### Web login when the browser is on another system
4326
+
4327
+ The browser sends the result of the login to `redirect_uri`, on the loopback address of the system where the browser runs.
4328
+ If `ascli` runs on another system than the browser (for example, `ascli` is installed on a server, and the user is connected with SSH from a workstation), the redirection does not reach `ascli`.
4329
+
4330
+ To solve this, forward the port of `redirect_uri` from the workstation to the server with an SSH tunnel, and open the login URL in the browser of the workstation:
4331
+
4332
+ 1. On the workstation, open the SSH session with a tunnel (same port on both sides, default `12345`):
4333
+
4334
+ ```shell
4335
+ ssh -L 127.0.0.1:12345:127.0.0.1:12345 <SERVER_USER>@<SERVER_HOST>
4336
+ ```
4337
+
4338
+ 2. In this session, run the command with `--ui=terminal`, so that the login URL is displayed instead of opening a browser on the server (this is the default if the server has no graphical environment):
4339
+
4340
+ ```shell
4341
+ ascli <PLUGIN> <COMMAND> --ui=terminal
4342
+ ```
4343
+
4344
+ 3. Copy the displayed URL in the browser of the workstation, and log in.
4345
+ 4. The browser is redirected to `http://localhost:12345`: the tunnel sends the request to `ascli` on the server, and the flow continues as described above.
4346
+
4347
+ The tunnel only exists as long as the SSH session is open.
4348
+
4349
+ If no tunnel is possible (for example, a jump server between the workstation and the server), use `--ui.web_auth=paste`: `ascli` then opens no local port, and the result of the login is given through the terminal.
4350
+ There are two ways, depending on whether `ascli` is also installed on the workstation.
4351
+
4352
+ With `--ui.web_auth=port` (default), in an SSH session with `--ui=terminal`, a warning reminds this option.
4353
+
4354
+ ##### With `ascli` on the workstation
4355
+
4356
+ `ascli` on the workstation opens the login page, receives the redirection of the browser, and shows a code to paste in the terminal of the server.
4357
+ Nothing else is needed on the workstation: no configuration, no preset, no access to the server of the application.
4358
+ The exchange of the code for a token is done by `ascli` on the server: the secret of the client does not leave it.
4359
+
4360
+ 1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`:
4361
+
4362
+ ```shell
4363
+ ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
4364
+ ```
4365
+
4366
+ 2. `ascli` displays a message that proposes the two ways to log in, with the login URL for the first one, and a command to run on the workstation for the second one: it contains a code made of letters, digits, `-` and `_`. Then `ascli` waits:
4367
+
4368
+ ```text
4369
+ USER ACTION: To continue, choose one of these two ways:
4370
+ 1. With any browser (ascli is not needed on the workstation):
4371
+ - Open this URL in a browser and log in:
4372
+ https://...
4373
+ - The browser shows a connection error on http://localhost:12345: this is expected.
4374
+ - Copy the full URL from the address bar of the browser, and paste it in the prompt below.
4375
+ 2. If ascli is installed on the workstation that has the browser:
4376
+ - Run there:
4377
+ ascli config web_login <CODE>
4378
+ - Log in in the page that opens.
4379
+ - Copy the code shown by the browser, and paste it in the prompt below.
4380
+ ```
4381
+
4382
+ The command is displayed only if `ascli` does not start the browser itself (`--ui=terminal` without `--ui.command`).
4383
+ If the browser is started by `ascli` (`--ui=graphical`, or `--ui.command`), it is on the same host as `ascli`, and the redirection may be immediate (user already logged in): only the steps to log in, copy the URL from the browser and paste it are displayed.
4384
+
4385
+ 3. On the workstation, run this command.
4386
+ The first time for a login host, `ascli` displays the host of the login page, and asks to trust it (`yes`): it opens a URL that comes from another system.
4387
+ Trusted hosts are saved; without a terminal, an unknown host is refused.
4388
+ `ascli` then opens the browser on the login page and listens on `redirect_uri`.
4389
+ 4. Log in. The browser shows a page "Login Complete" with the code to paste, hidden by default:
4390
+ - The button **Copy** puts the code in the clipboard.
4391
+ - The **eye** button shows or hides the code, to select it manually.
4392
+ 5. Paste the code in the terminal of the server ([hidden](#hidden-input): `🔑` becomes `…`). `ascli` on the server checks the `state`, and the flow continues as described above, from step 6.
4393
+
4394
+ The command on the workstation:
4395
+
4396
+ - accepts only a login page in `https`, and a `redirect_uri` on a loopback address; the host shown for confirmation is the one of the URL, not a label given in the code;
4397
+ - is available only at security level `low`;
4398
+ - ends once the browser has received the page with the code; the port of `redirect_uri` shall be free on the workstation (the URL is registered for the login and cannot be changed);
4399
+ - gives to the server only the parameters it needs (the `code` and the `state`).
4400
+
4401
+ The codes are compressed and encrypted with a key that is not secret (derived from a constant and the current time, in slots of 15 minutes): they are hard to read and are valid for 15 to 30 minutes (the clocks of both computers must be correct), but they are **not confidential**: do not keep them, nor send them. The code shown by Shares also uses the random `state` of the login in its key.
4402
+ The codes are authenticated: a code that is incomplete, mistyped or modified is detected.
4403
+ Spaces and line breaks are ignored (letter case matters): a code displayed on several lines can be pasted.
4404
+
4405
+ ##### Without `ascli` on the workstation
4406
+
4407
+ If `ascli` is not installed on the workstation, the URL of the error page is used:
4408
+
4409
+ 1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`.
4410
+ 2. Copy the displayed login URL in the browser of the workstation, and log in.
4411
+ 3. The browser is redirected to `redirect_uri` (for example `http://localhost:12345/?code=...&state=...`) and shows a connection error: this is expected.
4412
+ 4. Copy the full URL from the address bar of the browser, and paste it in the terminal ([hidden](#hidden-input), as it contains a code or tokens).
4413
+ The query alone (`code=...&state=...`) is also accepted.
4414
+ The `state` is mandatory: it is checked like in the standard flow, then the flow continues from step 6.
4415
+
4416
+ Both ways accept, at the prompt, the code, the URL or the query.
4417
+ If standard input is not a terminal, the line is read from it.
4418
+ The size of a pasted line may be limited by the terminal: the code of the reply contains only what is needed.
4419
+
4420
+ Notes:
4421
+
4422
+ - For Shares with `--auth=web`, `paste` is simpler: Shares itself displays the code, so neither the tunnel, nor `ascli config web_login`, nor the URL of the error page is used (see [Authentication of SAML users](#authentication-of-saml-users)).
4423
+ - The port must be free on the workstation.
4424
+ To use another port, change it in the tunnel and in `--redirect-uri`, for example `--redirect-uri=http://localhost:23456` and `-L 127.0.0.1:23456:127.0.0.1:23456`.
4425
+ For Aspera on Cloud, this `redirect_uri` shall also be declared in the API client (see [API Client Registration](#api-client-registration)).
4426
+ - The tunnel listens on `127.0.0.1`: if the browser resolves `localhost` to `::1`, use `--redirect-uri=http://127.0.0.1:12345`.
4427
+ - On Windows, `ssh` is the OpenSSH client provided with the system; with PuTTY, add a local port forwarding (Connection &rarr; SSH &rarr; Tunnels) from `127.0.0.1:12345` to `127.0.0.1:12345`.
4428
+ - Another solution is X11 forwarding: run an X server on the workstation (for example `VcXsrv` or X410 on Windows) and connect with `ssh -X`.
4429
+ The browser then runs on the server and is displayed on the workstation, so no tunnel is needed.
4430
+ It is heavier (X server to install, slower display), and the browser is the one of the server.
4431
+ - Without interaction (automation), prefer a method that needs no browser, such as `--auth=jwt` for Aspera on Cloud.
4432
+
3752
4433
  ### Logging, Debugging
3753
4434
 
3754
4435
  The gem is equipped with traces, mainly for debugging and learning APIs.
3755
4436
  The composite option `log` groups all logging parameters (use `--log=help` to display this schema):
3756
4437
 
3757
4438
  | Field | Type | Description |
3758
- |---------|--------|---------------------------------------------------------------------------|
3759
- | `format` | `String` | Log line formatter. Use `@ruby:` for a custom lambda.<br/>Allowed values: `default`, `caller`, `standard`.<br/>Default: `default`. |
3760
- | `level` | `String` | Minimum log level displayed.<br/>Allowed values: `trace2`, `trace1`, `debug`, `info`, `warn`, `error`, `fatal`, `unknown`.<br/>Default: `warn`. |
4439
+ | ------- | ------------ | ------------------------------------------------------------------------- |
4440
+ | `format` | `Enum[String]` | Log line formatter. Use `@ruby:` for a custom lambda.<br/>Allowed values: `default`, `caller`, `standard`.<br/>Default: `default`. |
4441
+ | `level` | `Enum[String]` | Minimum log level displayed.<br/>Allowed values: `trace2`, `trace1`, `debug`, `info`, `warn`, `error`, `fatal`, `unknown`.<br/>Default: `warn`. |
3761
4442
  | `secrets` | `Bool` | Show passwords and secrets in logs.<br/>Default: `false`. |
3762
- | `type` | `String` | Log output destination.<br/>Allowed values: `stderr`, `stdout`, `syslog`.<br/>Default: `stderr`. |
4443
+ | `type` | `Enum[String]` | Log output destination.<br/>Allowed values: `stderr`, `stdout`, `syslog`.<br/>Default: `stderr`. |
3763
4444
 
3764
4445
  > [!TIP]
3765
4446
  > Individual options `log_level`, `log_format`, `logger`, and `log_secrets` are also available as aliases for `log.level`, `log.format`, `log.type`, and `log.secrets` respectively.
@@ -3840,23 +4521,26 @@ To disable this warning, set the option `warn_insecure` to `no`.
3840
4521
  HTTP connection parameters (not `ascp` WSS) can be adjusted using option `http_options`:
3841
4522
 
3842
4523
  | Field | Type | Description |
3843
- |-------------------------|---------------|----------------------------------------------------------------------------------|
4524
+ | ----------------------- | -------------- | -------------------------------------------------------------------------------- |
3844
4525
  | `download_partial_suffix` | `String` | File suffix appended to the target filename while a download is in progress. (Rest)<br/>Default: `.http_partial`. |
3845
- | `keep_alive_timeout` | `Number` | Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)<br/>Default: `2`. |
3846
- | `open_timeout` | `Number` | Maximum time in seconds to wait for a connection to be established. (Net::HTTP)<br/>Default: `60`. |
3847
- | `read_timeout` | `Number` | Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)<br/>Default: `60`. |
4526
+ | `jwt_accepted_offset_sec` | `String, Number` | Tolerance of clock difference with the server: a generated JWT is valid since this duration in the past (`nbf`). (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `300`. |
4527
+ | `jwt_expiry_offset_sec` | `String, Number` | Validity of a generated JWT, used to request a token. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `3600`. |
4528
+ | `keep_alive_timeout` | `String, Number` | Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `2`. |
4529
+ | `open_timeout` | `String, Number` | Maximum time in seconds to wait for a connection to be established. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
4530
+ | `read_timeout` | `String, Number` | Maximum time in seconds to wait for data to be read from the server. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
3848
4531
  | `retry_max` | `Integer` | Maximum number of retry attempts. (Rest)<br/>Default: `1`. |
3849
4532
  | `retry_on_error` | `Bool` | Retry the request on any HTTP error response. (Rest)<br/>Default: `false`. |
3850
4533
  | `retry_on_timeout` | `Bool` | Retry the request on connection timeout. (Rest)<br/>Default: `true`. |
3851
4534
  | `retry_on_unavailable` | `Bool` | Retry the request on HTTP 503 Service Unavailable. (Rest)<br/>Default: `true`. |
3852
- | `retry_sleep` | `Integer` | Delay in seconds between retry attempts. (Rest)<br/>Default: `4`. |
4535
+ | `retry_sleep` | `String, Number` | Delay in seconds between retry attempts. (Rest) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `4`. |
3853
4536
  | `ssl_options` | `Array[String]` | List of OpenSSL option flags to set on the HTTP session (e.g. `IGNORE_UNEXPECTED_EOF`). (SSL) |
3854
- | `token_cache_max_age` | `Integer` | Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)<br/>Default: `1800`. |
3855
- | `token_refresh_threshold` | `Integer` | Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)<br/>Default: `120`. |
4537
+ | `token_cache_max_age` | `String, Number` | Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `1800`. |
4538
+ | `token_refresh_max_age` | `String, Number` | Age in seconds (since it was obtained) above which the token is proactively refreshed, `0` for no limit. E.g. keeps a session alive when the refresh token expires at the same time as the token (Shares). (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `0`. |
4539
+ | `token_refresh_threshold` | `String, Number` | Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `120`. |
3856
4540
  | `user_agent` | `String` | Value sent in the `User-Agent` HTTP request header. (Rest) |
3857
- | `write_timeout` | `Number` | Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)<br/>Default: `60`. |
4541
+ | `write_timeout` | `String, Number` | Maximum time in seconds to wait for data to be written to the server. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
3858
4542
 
3859
- Time values are set in **seconds** and can be of type either `Integer` or `Float`.
4543
+ Time values are durations: a number of **seconds** (`Integer` or `Float`), or a `String`, e.g. `30s`, `12h`, `1d`, `1h 30m`, `1d 02:00:00`.
3860
4544
  Any additional key is forwarded as a setter to the `Net::HTTP` session.
3861
4545
  For a full list, refer to the Ruby library: [`Net::HTTP`](https://github.com/ruby/net-http/blob/master/lib/net/http.rb).
3862
4546
 
@@ -3868,6 +4552,13 @@ Example:
3868
4552
  ascli aoc admin package list --http-options=@json:'{"read_timeout":10.0}'
3869
4553
  ```
3870
4554
 
4555
+ With a server whose token and refresh token expire at the same time (e.g. Shares: 24 hours), `token_refresh_max_age` refreshes the token before its refresh token expires.
4556
+ A command run more often than this duration (e.g. scheduled every 12 hours) keeps the session alive without a new login, provided the token stays in cache (`token_cache_max_age`):
4557
+
4558
+ ```shell
4559
+ ascli shares files browse / --http-options=@json:'{"token_cache_max_age":"1d","token_refresh_max_age":"12h"}'
4560
+ ```
4561
+
3871
4562
  The option `ssl_options` corresponds to a list of options as listed in `man SSL_CTX_set_options`.
3872
4563
  The default initial value is the default of Ruby as specified in `openssl/ssl.rb`.
3873
4564
  Each option can be specified as a `String` with the same name as in the OpenSSL library by removing the prefix: `SSL_OP_`, or an `Integer` (for example, `0` resets to no option).
@@ -3993,7 +4684,7 @@ Or, alternatively, (prefer transfer spec like above, generally):
3993
4684
 
3994
4685
  By default, it uses the `direct` agent, which is a local `ascp`.
3995
4686
  Nevertheless, `ascli` does not come with `ascp` installed.
3996
- This is the reason why it is advised to install the Aspera Transfer Daemon during installation (`ascli config transferd install`).
4687
+ This is the reason why it is advised to install the Aspera Transfer Daemon during installation (`ascli transferd install`).
3997
4688
 
3998
4689
  By default, `ascli` uses the `ascp` binary found in **well known locations**, that is, typical Aspera product installation paths.
3999
4690
 
@@ -4002,7 +4693,7 @@ It provides the following commands for `ascp` sub-command:
4002
4693
 
4003
4694
  - `show` : Show the path of `ascp` used
4004
4695
  - `info` : Show information on `ascp` and its environment
4005
- - `install` : Install the Transfer SDK (same as `config transferd install`)
4696
+ - `install` : Install the Transfer SDK (deprecated, same as `transferd install`)
4006
4697
  - `spec` : List transfer spec parameters supported by `ascp`
4007
4698
  - `schema` : Show the JSON schema of the transfer spec
4008
4699
  - `errors` : List known `ascp` errors and whether they are retry-able
@@ -4011,7 +4702,7 @@ It provides the following commands for `ascp` sub-command:
4011
4702
  #### Selection of `ascp` location for [`direct`](#agent-direct) agent
4012
4703
 
4013
4704
  Option: `sdk_folder` is used to specify the location of `ascp`.
4014
- By default, `ascli` uses `ascp` from the Transfer SDK installed in its configuration folder (see `config ascp install`).
4705
+ By default, `ascli` uses `ascp` from the Transfer SDK installed in its configuration folder (see `transferd install`).
4015
4706
 
4016
4707
  To override and use an alternate `ascp` path, use option `sdk_folder` (`--sdk-folder=`).
4017
4708
 
@@ -4099,7 +4790,7 @@ The following agents are supported and selected with option `transfer`:
4099
4790
  |----------|----------|-------------------------------|
4100
4791
  | [`direct`](#agent-direct) | local | direct execution of `ascp` |
4101
4792
  | [`transferd`](#agent-transfer-daemon) | local | Aspera Transfer Daemon |
4102
- | [`connect`](#agent-connect-client) | local | Aspera Connect Client |
4793
+ | [`connect`](#agent-connect-client) | local | Aspera Connect Client (to be deprecated in 2027, use `desktop`) |
4103
4794
  | [`desktop`](#agent-desktop-client) | local | Aspera for Desktop |
4104
4795
  | [`node`](#agent-node-api) | remote | Aspera Transfer Node |
4105
4796
  | [`httpgw`](#agent-http-gateway) | remote | Aspera HTTP Gateway |
@@ -4141,6 +4832,17 @@ Parameters in transfer-spec can be modified with option `ts`.
4141
4832
  > [!NOTE]
4142
4833
  > Parameters in `transfer` are specific for each agent type and are described in the agents respective sections.
4143
4834
 
4835
+ #### Dry run of a transfer
4836
+
4837
+ With option `dry_run` (`--dry-run=yes`), a transfer command does not start the transfer: its result is the final transfer spec, as it would be given to the agent (with option `ts` and file list applied), with secrets hidden (unless `--out.secrets=yes`).
4838
+ Nothing is transferred.
4839
+
4840
+ ```shell
4841
+ ascli server download /aspera-test-dir-large/100MB --dry-run=yes
4842
+ ```
4843
+
4844
+ Commands that change something before the transfer are refused with option `dry_run`, before any change: `aoc packages send` and `faspex5 packages send` (the package is created first), `sync` commands, and preview generation of `preview`.
4845
+
4144
4846
  #### Asynchronous Transfer Mode
4145
4847
 
4146
4848
  Adding `asynchronous: true` to the `transfer` option makes `ascli` return immediately after
@@ -4154,15 +4856,18 @@ ascli server download /remote/big-file.bin --to-folder=/tmp \
4154
4856
  '--transfer=@json:{"agent":"desktop","asynchronous":true}'
4155
4857
 
4156
4858
  # Poll status later
4157
- ascli config transfer status <job_id>
4859
+ ascli config agents jobs status <job_id>
4158
4860
 
4159
4861
  # List all pending/completed async transfers
4160
- ascli config transfer list
4862
+ ascli config agents jobs list
4161
4863
 
4162
4864
  # Remove completed/failed entries
4163
- ascli config transfer cleanup
4865
+ ascli config agents jobs cleanup
4164
4866
  ```
4165
4867
 
4868
+ > [!NOTE]
4869
+ > `config transfer` (`list`, `status`, `cleanup`) is deprecated after 4.28.0: use `config agents jobs`. It still works, with a warning.
4870
+
4166
4871
  All transfer agents support asynchronous mode:
4167
4872
 
4168
4873
  | Agent | Status source | Persisted across restart |
@@ -4176,16 +4881,16 @@ All transfer agents support asynchronous mode:
4176
4881
 
4177
4882
  For `direct` and `httpgw`, the transfer runs as a Ruby thread inside the `ascli` process.
4178
4883
  The `job_id` is persisted on disk but the live thread state is only available as long as the same process is running.
4179
- If the process is restarted, `config transfer status` returns `unknown` for those jobs.
4884
+ If the process is restarted, `config agents jobs status` returns `unknown` for those jobs.
4180
4885
 
4181
- Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config transfer status` takes them from the current `transfer` option, if it is for the same agent (e.g. same option on command line, or in a preset).
4886
+ Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config agents jobs status` takes them from the current `transfer` option, if it is for the same agent (e.g. same option on command line, or in a preset).
4182
4887
 
4183
4888
  > [!NOTE]
4184
4889
  > **`asynchronous` and MCP** - When `ascli` is used as an MCP server, an AI assistant calling
4185
4890
  > a transfer command may time out or cancel the request and retry, causing duplicate transfers.
4186
4891
  > Using `asynchronous: true` eliminates this risk: the transfer is submitted immediately,
4187
4892
  > the `job_id` is returned, and the AI can poll
4188
- > `config transfer status <job_id>` to track progress without any risk of duplication.
4893
+ > `config agents jobs status <job_id>` to track progress without any risk of duplication.
4189
4894
  > This works with all agents, including `direct` and `httpgw`.
4190
4895
 
4191
4896
  #### Agent: Direct
@@ -4200,75 +4905,210 @@ See [FASP](#fasp-configuration).
4200
4905
  The `transfer` option accepts the following optional parameters to control multi-session, Web Socket Session, Resume policy and add any argument to `ascp`:
4201
4906
 
4202
4907
  | Field | Type | Description |
4203
- |----------------------|---------------|----------------------------------------------------------------------------------|
4908
+ | -------------------- | ------------- | -------------------------------------------------------------------------------- |
4204
4909
  | `ascp_args` | `Array[String]` | List of native `ascp` command-line arguments.<br/>Default: `[]`. |
4205
- | `client_ssh_key` | `String` | SSH key type to use for token-based transfers.<br/>Allowed values: `rsa`, `dsa_rsa`, `per_client`.<br/>Default: `rsa`. |
4910
+ | `client_ssh_key` | `Enum[String]` | SSH key type to use for token-based transfers.<br/>Allowed values: `rsa`, `dsa_rsa`, `per_client`.<br/>Default: `rsa`. |
4206
4911
  | `file_list` | `Bool` | If `true`, source paths are written to a temp file passed to `ascp` via `--file-list` or `--file-pair-list`.<br/>If `false`, source paths are placed directly on the `ascp` command line.<br/>Default: `true`. |
4207
4912
  | `monitor` | `Bool` | Enable use of the `ascp` management port for transfer monitoring.<br/>Default: `true`. |
4208
4913
  | `multi_incr_udp` | `Bool` | Multi session - Increment UDP port for each session.<br/>If `true`, each session uses a different UDP port starting at `fasp_port` (default: 33001).<br/>If `false`, all sessions use the same `fasp_port` (or `ascp` default).<br/>Default: `true` on Windows, `false` on other platforms. |
4209
4914
  | `quiet` | `Bool` | Suppress the `ascp` progress bar display.<br/>If `false`, the progress bar of option `progress_bar` is not displayed, unless that option is set.<br/>Default: `true`. |
4915
+ | `resume` | `Hash` | Configuration for automatic transfer resume on interruption. |
4210
4916
  | `resume.iter_max` | `Integer` | Maximum number of retry attempts on error.<br/>Default: `7`. |
4211
4917
  | `resume.sleep_factor` | `Integer` | Multiplier applied to sleep duration between consecutive retry attempts.<br/>Default: `2`. |
4212
4918
  | `resume.sleep_initial` | `Integer` | Initial sleep duration (in seconds) before first retry.<br/>Default: `2`. |
4213
4919
  | `resume.sleep_max` | `Integer` | Maximum sleep duration (in seconds) between retry attempts.<br/>Default: `60`. |
4214
- | `resume` | `Hash` | Configuration for automatic transfer resume on interruption. |
4215
4920
  | `spawn_delay_sec` | `Number` | Multi session - Delay (in seconds) between starting each `ascp` session.<br/>Default: `2`. |
4216
4921
  | `spawn_timeout_sec` | `Number` | Multi session - Maximum time (in seconds) to verify that `ascp` is running.<br/>Default: `2`. |
4217
4922
  | `trusted_certs` | `Array[String]` | List of trusted certificate repositories. |
4218
4923
  | `wss` | `Bool` | Enable Web Socket Session when available.<br/>Default: `true`. |
4219
4924
 
4220
- In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` times.
4221
- Sleep between iterations is given by the following formula where `iter_index` is the current iteration index, starting at 0:
4925
+ In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` times.
4926
+ Sleep between iterations is given by the following formula where `iter_index` is the current iteration index, starting at 0:
4927
+
4928
+ ```text
4929
+ min( sleep_max, sleep_initial * sleep_factor ^ iter_index )
4930
+ ```
4931
+
4932
+ By default, the progress bar of `ascli` is displayed (see [Transfer progress bar](#transfer-progress-bar)): it aggregates all sessions of a multi-session transfer.
4933
+
4934
+ To display the native progress bar of `ascp` instead, set parameter `quiet` to `false`:
4935
+
4936
+ ```shell
4937
+ --transfer.quiet=false
4938
+ ```
4939
+
4940
+ In that case, the progress bar of `ascli` is not displayed, unless option `progress_bar` is set.
4941
+ For multi-session transfers, each `ascp` process displays its own progress bar.
4942
+
4943
+ To skip usage of management port (which disables the progress bar of `ascli`), set option `monitor` to `false`.
4944
+
4945
+ By default, Ruby's root CA store is used to validate any HTTPS endpoint used by `ascp` (for example, WSS).
4946
+ To use a custom certificate store, use the `trusted_certs` option of direct agent's option `transfer`.
4947
+ To use `ascp`'s default, use option:
4948
+
4949
+ ```shell
4950
+ --transfer.trusted_certs=@none:
4951
+ ```
4952
+
4953
+ Some transfer errors are considered **retry-able** (for example, timeout) and others are not (for example, wrong password).
4954
+ The list of known protocol errors and retry level can be listed:
4955
+
4956
+ ```shell
4957
+ ascli config ascp errors
4958
+ ```
4959
+
4960
+ Error codes of sessions (`errcode` in `ascp` logs) are a different numbering, listed with their category and the corresponding error above:
4961
+
4962
+ ```shell
4963
+ ascli config ascp errors session
4964
+ ```
4965
+
4966
+ Examples:
4967
+
4968
+ ```shell
4969
+ ascli ... --transfer.wss=true --transfer.resume.iter_max=20
4970
+ ascli ... --transfer.spawn_delay_sec=2.5 --transfer.multi_incr_udp=false
4971
+ ```
4972
+
4973
+ Parameter `ascp_args` can also be used to activate logging using option `-L` of `ascp`.
4974
+ For example, to activate debug level 2 for `ascp` (`DD`), and display those logs on the terminal (`-`):
4975
+
4976
+ ```shell
4977
+ --transfer=@json:'{"ascp_args":["-DDL-"]}'
4978
+ ```
4979
+
4980
+ This is useful to debug if a transfer fails.
4981
+
4982
+ To store `ascp` logs in file `aspera-scp-transfer.log` in a folder, use `--transfer=@json:'{"ascp_args":["-L","/path/to/folder"]}'`.
4983
+
4984
+ To analyze `ascp` log files (`ascp` 4.0 and later), give log files, or folders with log files, to `config ascp logs`:
4985
+
4986
+ ```shell
4987
+ ascli config ascp logs summary /path/to/folder
4988
+ ascli config ascp logs sessions /path/to/folder/aspera-scp-transfer.log
4989
+ ```
4990
+
4991
+ | Command | Result |
4992
+ |---------------------|-----------------------------------------------------------------|
4993
+ | `summary` | Statistics of sessions, errors by category, maximum throughput, findings. |
4994
+ | `health` | Health check for monitoring in Nagios format (failed sessions and low efficiency over last N minutes). |
4995
+ | `sessions` | One row per session, with diagnostics. |
4996
+ | `diagnostics` | One row per diagnostic of a session: `id`, `severity` (`error`, `warning`, `info`), `message` and `recommendation` (action to take, when the diagnostic has one). |
4997
+ | `multi_sessions` | Multi-session transfers: sessions grouped by transfer, with aggregate rate. |
4998
+ | `snapshots` | Aggregate rates per period. |
4999
+ | `snapshot_sessions` | Rates of each session per period. |
5000
+ | `peers` | Sessions and errors by peer address. |
5001
+ | `transfers` | Transferred files. |
5002
+ | `licenses` | Licenses of local and peer systems. |
5003
+ | `overdrives` | Sessions with loss due to overdriving of network or storage. |
5004
+ | `records` | Log lines parsed into records: `samples`, `sessions` or `transfers` (see below). |
5005
+ | `fields` | Description of the fields of records: `samples`, `sessions` or `transfers`. |
5006
+ | `find` | `ascp` log files of this system (no argument): `path`, `size`, `modified`, `source`, most recent first. |
5007
+
5008
+ Command `find` lists the local files that contain `ascp` log lines, in the log folders of the installed products (including `<logging><directory>` of their `aspera.conf`), of `ascp` found in `PATH`, of IBM Aspera for Desktop, and in the default locations of `ascp` (below). Give the paths it lists to the other commands:
5009
+
5010
+ ```shell
5011
+ ascli config ascp logs find --fields=path
5012
+ ascli config ascp logs sessions ~/Library/Logs/Aspera
5013
+ ```
5014
+
5015
+ `ascp` writes its log in the folder of option `-L`, else in `<logging><directory>` of `aspera.conf`, else in a location that depends on the OS:
5016
+
5017
+ | OS | Default location of the `ascp` log |
5018
+ |---------------|------------------------------------|
5019
+ | Linux, Unix | syslog, facility `local2`: `/var/log/messages` or `/var/log/syslog` by default, `/var/log/aspera.log` if syslog is configured to separate the Aspera logs. |
5020
+ | macOS | `~/Library/Logs/Aspera` (`/Library/Logs/Aspera` for `root`). |
5021
+ | Windows | `var\log` of the product if this folder exists, else the folder of `ascp`. |
5022
+
5023
+ For the `ascp` used by `ascli`, `ascli config ascp info --fields=log` gives this location (a folder, or `syslog`).
5024
+
5025
+ In a folder, the file is `aspera-scp-transfer.<n>.log` (rotated, `n` from `0` to `log_count` of `aspera.conf`), and `aspera-scp-transfer.log` is a hard link to the current one. `ascp` 4 (`ascp4`) writes `ascp4.<n>.log`.
4222
5026
 
4223
- ```text
4224
- min( sleep_max, sleep_initial * sleep_factor ^ iter_index )
4225
- ```
5027
+ | Application | Location of the `ascp` log |
5028
+ |------------------------|----------------------------|
5029
+ | `ascli`, agent `direct` or `transferd` | No `-L`: default location above (e.g. on Linux in syslog). With agent `direct`, `-L` can be set with `ascp_args` (see above). |
5030
+ | IBM Aspera Connect | `-L` set to its log folder (e.g. `~/Library/Logs/Aspera_Connect`). |
5031
+ | IBM Aspera for Desktop | Log folder of the application, also used for its own logs and those of `transferd`: `~/Library/Logs/com.ibm.software.aspera.desktop` on macOS, `%APPDATA%\com.ibm.software.aspera.desktop\logs` on Windows, `~/.config/com.ibm.software.aspera.desktop/logs` on Linux. |
5032
+ | IBM Aspera Transfer Daemon | `-L` set to `fasp_runtime.log.dir` of its configuration (or `localLog` of the transfer), else the default location above. |
5033
+ | Server side of a transfer | On the server, configured by its `aspera.conf`, or by option `-R` of the client: see [`server logs`](#analyze-ascp-logs-of-the-server). |
4226
5034
 
4227
- By default, the progress bar of `ascli` is displayed (see [Transfer progress bar](#transfer-progress-bar)): it aggregates all sessions of a multi-session transfer.
5035
+ On Linux, the syslog files are often readable only by `root`, and a container may have no syslog daemon (the log of `ascp` is then lost): use `-L`, or read the system journal, e.g. `journalctl -t ascp | ascli config ascp logs summary -`.
5036
+ For the other logs of Aspera products, see the IBM support page [Where are IBM Aspera logs located](https://www.ibm.com/support/pages/where-are-ibm-aspera-desktop-client-or-ibm-aspera-server-logs-located).
4228
5037
 
4229
- To display the native progress bar of `ascp` instead, set parameter `quiet` to `false`:
5038
+ Log files compressed with gzip (e.g. rotations `aspera.log-20261101.gz`, `aspera-scp-transfer.1.log.gz`) are read directly, in a folder or given as argument; gzip is detected from the first bytes of the file, not from its name. Argument `-` reads the logs from the standard input, plain or compressed with gzip:
4230
5039
 
4231
5040
  ```shell
4232
- --transfer.quiet=false
5041
+ ascli config ascp logs summary /var/log/aspera.log-20261101.gz
5042
+ zcat /var/log/aspera.log-2026*.gz | ascli config ascp logs summary -
4233
5043
  ```
4234
5044
 
4235
- In that case, the progress bar of `ascli` is not displayed, unless option `progress_bar` is set.
4236
- For multi-session transfers, each `ascp` process displays its own progress bar.
5045
+ To analyze the logs of an HSTS read over SSH, instead of files of the local machine, use command `logs` of the plugin [`server`](#analyze-ascp-logs-of-the-server).
4237
5046
 
4238
- To skip usage of management port (which disables the progress bar of `ascli`), set option `monitor` to `false`.
5047
+ A file must contain `ascp` log lines (`FASP` messages, or lines of process `ascp` in syslog): in a folder, other files are ignored; a file given as argument that is not an `ascp` log is refused.
4239
5048
 
4240
- By default, Ruby's root CA store is used to validate any HTTPS endpoint used by `ascp` (for example, WSS).
4241
- To use a custom certificate store, use the `trusted_certs` option of direct agent's option `transfer`.
4242
- To use `ascp`'s default, use option:
5049
+ When logs of both sides of a session are analyzed (client and server), each session includes the status, error and diagnostics of the other side (`peer_side`, `peer_diagnostics`).
5050
+
5051
+ For example, to list only errors:
4243
5052
 
4244
5053
  ```shell
4245
- --transfer.trusted_certs=@none:
5054
+ ascli config ascp logs diagnostics /path/to/folder --select=@json:'{"severity":"error"}'
4246
5055
  ```
4247
5056
 
4248
- Some transfer errors are considered **retry-able** (for example, timeout) and others are not (for example, wrong password).
4249
- The list of known protocol errors and retry level can be listed:
5057
+ Besides the default columns, `sessions` rows have context columns to filter sessions (show them with `--fields=ALL`, or select with `--fields=session,product_name,transport,authentication`, or filter with `--select`/`--query`); a column is absent when the log does not give it:
4250
5058
 
4251
- ```shell
4252
- ascli config ascp errors
4253
- ```
5059
+ | Column | Value |
5060
+ |------------------|--------------------------------------------------------------------------------------------------------------------|
5061
+ | `product_name` | Product that wrote the log, from the line `<product> version <version>` (e.g. `Aspera High-Speed Transfer Server`, `Aspera Transfer SDK`, `Aspera Connect`), without `IBM`. |
5062
+ | `transport` | `ssh` if `Session Start` has `tcp_port`, `wss` if it has `wss_port`. |
5063
+ | `authentication` | `token` if `ascp` logs that `ASPERA_AUTH_TOKEN` is set, else `node` if it logs the storage of a node access key. Never the token, the access key or the storage root. |
5064
+ | `proxy` | Address of the proxy (`proxy_ip` of `Session Params`), absent if there is none. |
5065
+ | `fips` | `true` or `false` (`fips_enabled` of `Session Params`). |
4254
5066
 
4255
- Examples:
5067
+ Diagnostics of a session include: category of error (e.g. `udp_setup`, `storage`, `authentication`) with a hint, retry of a failed session, parameters set by the server (cipher, resume policy, virtual link), efficiency and loss of control messages, decline of the rate during the transfer (`rate_decline`: second half of the samples below 70% of the first half, not evaluated if the peer changes the rate, if another transfer session starts meanwhile, or if the session failed), and for a sender, which limit of the receiver (network, disk, virtual link) or reading from storage limits the rate. Other diagnostics: no packet received for some seconds, by the receiver (`reception_interruption`) or by the sender, which gets no feedback of the receiver (`feedback_interruption`); overflow of the retransmission timer (`rex_timer_overflow`: the retransmission RTT is very large); maximum rate of the license of `ascp` below the target rate (`license_rate_limit`); license that expires within `license_expiry_days` (default `30`) of the start of the session, or has expired (`license_expiry`); and many small files transferred (`small_files`): at least `small_files_min_count` (default 100) files with a mean size below `small_files_max_mean` (default 1 MB); path MTU measured by `ascp` below `small_mtu_max` (default 1400, `ascp` measures 1492, 1006, 508 or 296), which suggests a VPN or a tunnel (`small_mtu`). Two configuration messages, which have no effect on the transfer, are not diagnostics but only appear in `findings` of `summary`: OpenSSL modules folder not found (`ossl-modules not found`), and a schedule of virtual link capacity that could not be registered (`unable to submit change event`).
4256
5068
 
4257
- ```shell
4258
- ascli ... --transfer.wss=true --transfer.resume.iter_max=20
4259
- ascli ... --transfer.spawn_delay_sec=2.5 --transfer.multi_incr_udp=false
4260
- ```
5069
+ The `recommendation` of a diagnostic is only in the list `diagnostics` (not in `sessions`, where `diagnostics` is a list of messages, and not in `summary`): it tells what to check or change, with the `ascp` options and `aspera.conf` parameters concerned (e.g. UDP port and firewalls, target and minimum rate, storage write, SSH). Diagnostics without action (e.g. information, or cancelled by the user) have no `recommendation`; the diagnostic of the category of a failed session gives its hint in `message`.
4261
5070
 
4262
- Parameter `ascp_args` can also be used to activate logging using option `-L` of `ascp`.
4263
- For example, to activate debug level 2 for `ascp` (`DD`), and display those logs on the terminal (`-`):
5071
+ Option `ascp_logs` (dot-notation) sets `period` (snapshot period in minutes, default `1`), `zero_bytes` (include sessions without transferred bytes), `mtu` (when not found in logs), `resolve` (host names of peers), `timezone`, `health_minutes` (window in minutes for health check command, default `60`), `remote_max_size` (maximum total size in bytes of the log files read from a server with [`server logs`](#analyze-ascp-logs-of-the-server), default `268435456`), and `thresholds` (diagnostic thresholds, including `rate_decline_ratio`, `rate_decline_min_samples`, `rate_decline_delay`, `rate_decline_end_fraction`, `license_expiry_days`, `small_files_min_count`, `small_files_max_mean` and `small_mtu_max`), e.g. `--ascp-logs.period=5` or `--ascp-logs.thresholds.efficiency=95`.
5072
+
5073
+ Times of log lines are read in the time zone of the analyst, and displayed in it. To read the log of another system without shifting it, set the time zone of the log with `timezone`: `UTC` or an offset `+HH:MM`, e.g. `--ascp-logs.timezone=+02:00`. Syslog lines (`Oct 25 00:02:20`) have no year: it is deduced from the modification date of the log file (the current date for the standard input), the log being before this date. So a log from December to January, analyzed in March, has its December lines in the previous year. Keep the modification date of the file when copying it (e.g. `cp -p`, `scp -p`).
5074
+
5075
+ Command `records` gives the log lines parsed into records, with the field names of the log lines, to filter them with `--out.query` (JMESPath):
5076
+
5077
+ | Record | Log lines |
5078
+ |-------------|-------------------------------------------------------------------------------------------------|
5079
+ | `samples` | `Receiver bl` or `Sender bl` line, with the `DS Qs` line that follows it in field `DS`. |
5080
+ | `sessions` | `Session Start`, `Session Params`, `Session Stop` and `Session Statistics` lines of a session, and lines of the process about it (see below). |
5081
+ | `transfers` | `Transfer Start` and `Transfer Stop` lines of a file. |
5082
+
5083
+ A group of a log line becomes an object: for example, `rate t/m/c/n/vl/vr/r=...` becomes `rate.t`, `rate.m`, `rate.c`, etc.
5084
+ Values are numbers when the log value is a number: rates in bps, durations in ms, s or µs, and percentages without `%`.
5085
+ `Session Stop` and `Transfer Stop` have the fields of `Session Start` and `Transfer Start`, with their final values.
5086
+ When several log files are read, field `log_file` gives the log file of each record.
5087
+ Field `cookie` of `Session Params` is never output.
5088
+
5089
+ A session record also has the fields of these lines of the process (`ascp`), when the log has them:
5090
+
5091
+ | Field | Log line |
5092
+ |----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
5093
+ | `fasp_version`, `license_max_rate`, `license_expires` | `Initializing FASP version <version>, license expires on <date>, max rate=<N> Mbps, ...`: `license_max_rate` (bps) and `license_expires` are absent if the license is unlimited or has no expiry date. `account no.` and `license no.` are never output. |
5094
+ | `pMTU`, `start_brtt` | `Measured pMTU: <N> Bytes, start_brtt: <N> ms`. |
5095
+ | `datagram_size`, `block_size`, `path_mtu` | `datagram size <N>B, block size <N>B, path MTU <N>B` (no `path_mtu` in old versions). |
5096
+ | `peer_rate_params` | List of `Peer requested rate params adopted` lines, in the order of the log: `time`, `target_rate`, `min_rate` and `transfer_policy` of each change. |
5097
+
5098
+ For example, samples where the calculated rate is lower than the target rate, and sessions with loss of control messages from the receiver:
4264
5099
 
4265
5100
  ```shell
4266
- --transfer=@json:'{"ascp_args":["-DDL-"]}'
5101
+ ascli config ascp logs records samples /path/to/aspera-scp-transfer.log --out.query='[?rate.c < rate.t].{time: time, session: uuid, calculated: rate.c, network: rate.n, lost: bl2.l}'
5102
+ ascli config ascp logs records sessions /path/to/folder --out.query='[?rcvr_ctl.lost_pct > `1`]'
4267
5103
  ```
4268
5104
 
4269
- This is useful to debug if a transfer fails.
5105
+ Command `fields` gives the type and description (with unit) of each field of a kind of record (`samples`, `sessions` or `transfers`), with its path as used in `--out.query` (e.g. `rate.c`):
4270
5106
 
4271
- To store `ascp` logs in file `aspera-scp-transfer.log` in a folder, use `--transfer=@json:'{"ascp_args":["-L","/path/to/folder"]}'`.
5107
+ ```shell
5108
+ ascli config ascp logs fields samples
5109
+ ascli config ascp logs fields sessions
5110
+ ascli config ascp logs fields transfers
5111
+ ```
4272
5112
 
4273
5113
  > [!NOTE]
4274
5114
  > When transfer agent [`direct`](#agent-direct) is used, the list of files to transfer is provided to `ascp` using either `--file-list` or `--file-pair-list` and a temp file list, unless `--file-list` or `--file-pair-list` is already provided via `transfer` parameter `ascp_args`.
@@ -4451,6 +5291,10 @@ So, for example:
4451
5291
 
4452
5292
  #### Agent: Connect Client
4453
5293
 
5294
+ > **Note:** IBM Aspera Connect will be deprecated in 2027.
5295
+ > Use [IBM Aspera for Desktop](#agent-desktop-client) instead: `--transfer=desktop`.
5296
+ > `ascli` displays a warning when the `connect` agent is used.
5297
+
4454
5298
  By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed **IBM Aspera Connect Client**.
4455
5299
  There are no specific parameters for option `transfer`.
4456
5300
 
@@ -4467,7 +5311,7 @@ This is especially useful for direct node-to-node transfers.
4467
5311
  Parameters provided in option `transfer` are:
4468
5312
 
4469
5313
  | Field | Type | Description |
4470
- |----------|--------|---------------------------------------------------------------|
5314
+ | -------- | ------ | ------------------------------------------------------------- |
4471
5315
  | `password` | `String` | Password, secret, or bearer token.<br/>Required. |
4472
5316
  | `root_id` | `String` | Root file ID. Mandatory only when `password` is a bearer token. |
4473
5317
  | `url` | `String` | URL of the Node API.<br/>Required. |
@@ -4499,8 +5343,8 @@ By specifying option: `--transfer=httpgw`, `ascli` will start transfers using th
4499
5343
  Parameters provided in option `transfer` are:
4500
5344
 
4501
5345
  | Field | Type | Description |
4502
- |-------------------|---------|---------------------------------------------|
4503
- | `api_version` | `String` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
5346
+ | ----------------- | ------------ | ------------------------------------------- |
5347
+ | `api_version` | `Enum[String]` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
4504
5348
  | `synchronous` | `Bool` | Wait for acknowledgment after each message.<br/>Default: `false`. |
4505
5349
  | `upload_chunk_size` | `Integer` | Size in bytes of each upload chunk.<br/>Default: `64000`. |
4506
5350
  | `url` | `String` | URL of the HTTP Gateway.<br/>Required. |
@@ -4524,7 +5368,9 @@ Set option `transfer` to `transferd`.
4524
5368
  Options for `transfer` are:
4525
5369
 
4526
5370
  | Field | Type | Description |
4527
- |-------|--------|----------------------------------------------------------------------------------|
5371
+ | ------- | ------ | -------------------------------------------------------------------------------- |
5372
+ | `api_key` | `String` | API key of an existing daemon (`start` is `false`) that has `authentication` enabled in its configuration. It is sent in the metadata `api_key` of each call. |
5373
+ | `ca_file` | `String` | Path to the certificate authority file (PEM) that signed the certificate of an existing daemon (`start` is `false`) that has `tls` enabled in its configuration. A self-signed certificate is its own authority. |
4528
5374
  | `start` | `Bool` | Start a new daemon instance.<br/>Default: `true`. |
4529
5375
  | `stop` | `Bool` | Stop the daemon when `ascli` exits.<br/>Default: `true`. |
4530
5376
  | `url` | `String` | Address and port listened by the daemon (e.g. `:55002`). If port is `0`, the daemon listens on a random available port. If no address is given, `127.0.0.1` is used.<br/>Default: `:0`. |
@@ -4568,6 +5414,165 @@ On Windows the compilation may fail for various reasons (3.1.1):
4568
5414
 
4569
5415
  <!-- spellchecker: enable -->
4570
5416
 
5417
+ #### Transfer Daemon as a system service
5418
+
5419
+ The Transfer Daemon (`transferd`) can run permanently as a `systemd` service, for applications that use an existing daemon (see [Agent: Transfer Daemon](#agent-transfer-daemon), `start` set to `false`).
5420
+ `ascli` installs the SDK, writes the configuration file of the daemon (`/etc/transferd/transferd.json`) and the `systemd` unit, then enables and starts the service.
5421
+
5422
+ Commands are in `transferd service` (plugin [`transferd`](#plugin-transferd-transfer-daemon)):
5423
+
5424
+ | Command | Action |
5425
+ |-------------|--------|
5426
+ | `spec` | Show the schema of the configuration file of the daemon (`transferd.json`). Works on any system. |
5427
+ | `install` | Install the SDK if it is missing, then do `configure`. |
5428
+ | `configure` | Merge the given configuration into the existing file, validate it, write the file and the unit, reload `systemd`, enable and restart the service, and wait until the daemon listens. |
5429
+ | `status` | Show the version, the state of the service, the endpoint and whether it listens. The API key is never shown. |
5430
+ | `uninstall` | Stop and remove the service. With `purge` set to `true` in `service`, also remove the configuration file and the log folder. |
5431
+ | `use` | Switch to an installed version of the SDK and restart the service (see below). |
5432
+ | `versions` | List the installed versions of the SDK (see below). |
5433
+
5434
+ Except `spec` and `versions`, commands take the optional **last** positional argument `CONFIG`: a `Hash` ([Extended Value](#extended-value-syntax)) with two optional sections:
5435
+
5436
+ - `service`: how the service is installed.
5437
+ - `config`: content of `transferd.json`.
5438
+
5439
+ ```json
5440
+ {
5441
+ "service": {
5442
+ "user": "asperadaemon"
5443
+ },
5444
+ "config": {
5445
+ "address": "127.0.0.1",
5446
+ "port": 55002,
5447
+ "log_directory": "/var/log/aspera-transferd",
5448
+ "workers": {"max_concurrent": 10},
5449
+ "authentication": {"enabled": true}
5450
+ }
5451
+ }
5452
+ ```
5453
+
5454
+ Parameters of section `service`:
5455
+
5456
+ | Field | Type | Description |
5457
+ | ----------- | ------------- | -------------------------------------------------------------------------------- |
5458
+ | `after` | `Array[String]` | Units that shall be started before the daemon (`After=` in the unit).<br/>Default: `["network.target"]`. |
5459
+ | `environment` | `Hash` | Environment variables set in the unit. None is set unless given here. `TRANSFERD_ADDRESS`, `TRANSFERD_PORT`, `TRANSFERD_MGMT_PORT` and `TRANSFERD_MGMT_ADDRESS` override the configuration file. |
5460
+ | `group` | `String` | Group that runs the daemon. Defaults to the primary group of `user`. |
5461
+ | `name` | `String` | Name of the service. The unit file is `<name>.service`.<br/>Default: `aspera-transferd`. |
5462
+ | `purge` | `Bool` | Used by `uninstall`. Also remove the configuration file and the log folder.<br/>Default: `false`. |
5463
+ | `unit_dir` | `String` | Folder where the unit file is created.<br/>Default: `/etc/systemd/system`. |
5464
+ | `user` | `String` | Account that runs the daemon. It must exist, it is not created.<br/>Default: `asperadaemon`. |
5465
+ | `version` | `String` | Version of the SDK to install, used by `install` when the SDK folder is named `current` (versions side by side). Defaults to the SDK version of this tool. |
5466
+
5467
+ Section `config` follows the JSON schema of the daemon, displayed with:
5468
+
5469
+ ```shell
5470
+ ascli transferd service spec
5471
+ ```
5472
+
5473
+ | Field | Type | Description |
5474
+ | ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
5475
+ | `$schema` | `String` | Optional URI or path of this schema, used by editors for completion and validation. Ignored by transferd. |
5476
+ | `address` | `String` | IP address or host name on which the gRPC API listens. Use 0.0.0.0 to listen on all IPv4 interfaces (for example in a container); when not listening on a loopback address, consider enabling tls and authentication. Overridden by environment variable TRANSFERD_ADDRESS, and by option --address (-a), which takes precedence.<br/>Default: `127.0.0.1`.<br/>Example: `127.0.0.1`. |
5477
+ | `api_time_settings` | `Hash` | Keepalive and connection lifetime settings of the gRPC API server, in seconds. |
5478
+ | `api_time_settings.max_conn_age` | `Integer` | Maximum lifetime of a client connection, with a random variation of +/-10%; the client must then reconnect. 0 or omitted: no limit.<br/>Default: `0`.<br/>Example: `3600`. |
5479
+ | `api_time_settings.max_conn_age_grace` | `Integer` | Additional time given to ongoing calls once max_conn_age is reached, before the connection is forcibly closed. 0 or omitted: no limit.<br/>Default: `0`.<br/>Example: `10`. |
5480
+ | `api_time_settings.max_conn_idle` | `Integer` | Time after which a client connection with no ongoing call is closed. 0 or omitted: 86400 (24 hours).<br/>Default: `86400`.<br/>Example: `120`. |
5481
+ | `api_time_settings.time` | `Integer` | Time without activity from a client after which the server pings it to check that the connection is still alive. 0 or omitted: 7200 (2 hours).<br/>Default: `7200`.<br/>Example: `60`. |
5482
+ | `api_time_settings.timeout` | `Integer` | Time the server waits for activity after a keepalive ping before closing the connection. 0 or omitted: 20.<br/>Default: `20`.<br/>Example: `3`. |
5483
+ | `authentication` | `Hash` | API key authentication of clients of the gRPC API. |
5484
+ | `authentication.api_key` | `String` | Value that clients must send in gRPC request metadata entry api_key. It is stored in clear text: restrict read access to this file.<br/>Example: `change-me-to-a-long-random-value`. |
5485
+ | `authentication.enabled` | `Bool` | Requires every call to carry the API key; other calls are rejected with status UNAUTHENTICATED. api_key is then required.<br/>Default: `false`. |
5486
+ | `fasp_management` | `Hash` | Management port on which the ascp processes started by transferd report transfer progress. |
5487
+ | `fasp_management.address` | `String` | IP address on which the management server listens. Change it only when ascp must reach transferd through an interface other than loopback. Overridden by environment variable TRANSFERD_MGMT_ADDRESS, and by option --mgmtaddress (-A), which takes precedence.<br/>Default: `127.0.0.1`.<br/>Example: `127.0.0.1`. |
5488
+ | `fasp_management.port` | `Integer` | TCP port of the management server. 0 or omitted: a free port is selected at startup. Overridden by environment variable TRANSFERD_MGMT_PORT, and by option --mgmtport (-P), which takes precedence.<br/>Default: `0`.<br/>Example: `23456`. |
5489
+ | `fasp_management.promiscuous_mode_enabled` | `Bool` | When true, transferd also reports transfers of ascp processes that it did not start. So that those processes find the management port, transferd writes it in file transferd.<port>.optport of directory ../var/run/aspera, relative to the FASP runtime bin directory. Those ascp processes must use the same FASP runtime as transferd (see fasp_runtime).<br/>Default: `false`. |
5490
+ | `fasp_runtime` | `Hash` | FASP runtime (ascp, async, license, aspera.conf) used for transfers. Omitted: the runtime embedded in the SDK is used. When this section is present, set use_embedded explicitly: if it is not true, user_defined is required. |
5491
+ | `fasp_runtime.extra_config` | `Array[Hash]` | Extra command line options added to the executables started for transfers. Does not apply to async. |
5492
+ | `fasp_runtime.extra_config[].command` | `String` | End of the path of the executable to which options are added, for example ascp (ascp.exe on Windows). Only the first matching entry is used.<br/>Required.<br/>Example: `ascp`. |
5493
+ | `fasp_runtime.extra_config[].options` | `Array[String]` | Options added to the command line, one argument per item, before the transfer arguments.<br/>Example: `["--save-before-overwrite"]`. |
5494
+ | `fasp_runtime.force_version` | `String` | Accepted for backward compatibility. Has no effect. |
5495
+ | `fasp_runtime.log` | `Hash` | Default logging of ascp, for transfers whose request configuration does not set localLog or logLevel. Does not apply to async. |
5496
+ | `fasp_runtime.log.dir` | `String` | Directory where ascp writes its log (ascp option -L). Empty or omitted: default location of ascp.<br/>Example: `/var/log/aspera`. |
5497
+ | `fasp_runtime.log.level` | `Integer` | Level of detail of the ascp log: 0 for basic information (files transferred, transfer rate), 1 to 4 for increasingly detailed debug messages (ascp options -D to -DDDD).<br/>Default: `0`. |
5498
+ | `fasp_runtime.use_embedded` | `Bool` | true: use the FASP runtime embedded in the SDK, and ignore user_defined. false: use the runtime located by user_defined. Omitted while the fasp_runtime section is present: false.<br/>Example: `true`. |
5499
+ | `fasp_runtime.user_defined` | `Hash` | Location of a separately installed FASP runtime. Required when use_embedded is not true, ignored otherwise. Both directories must exist at startup. |
5500
+ | `fasp_runtime.user_defined.bin` | `String` | Directory containing the ascp and async executables. A relative path is resolved from the working directory of transferd.<br/>Required.<br/>Example: `/opt/aspera/bin`. |
5501
+ | `fasp_runtime.user_defined.etc` | `String` | Directory containing the license file aspera-license and the configuration file aspera.conf. A relative path is resolved from the working directory of transferd.<br/>Required.<br/>Example: `/opt/aspera/etc`. |
5502
+ | `log_directory` | `String` | Directory of the transferd log file transferd.log (rotated at 10 MiB, 10 files kept). A relative path is resolved from the directory of the transferd executable. The directory is created if missing. Empty or omitted: logs are written to standard output.<br/>Example: `/var/log/aspera`. |
5503
+ | `log_format` | `Enum[String]` | Format of the transferd log: text for human-readable lines, json for one JSON object per line. Any value other than text gives json.<br/>Allowed values: `text`, `json`.<br/>Default: `text`. |
5504
+ | `log_level` | `Enum[String]` | Level of detail of the transferd log, from most (trace) to least (panic) verbose. Omitted or unrecognized value: info.<br/>Allowed values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`.<br/>Default: `info`. |
5505
+ | `port` | `Integer` | TCP port on which the gRPC API listens. 0 or omitted: a free port is selected at startup; it is written in the log and in file transferd.<port>.optport of runtime_dir. The configuration file shipped with the SDK sets 55002. Overridden by environment variable TRANSFERD_PORT, and by option --port (-p), which takes precedence.<br/>Default: `0`.<br/>Example: `55002`. |
5506
+ | `reflection` | `Bool` | Enables the gRPC server reflection service, so that tools such as `grpcurl` or `grpcui` can list and call the API without the transferd.proto file. Useful for debugging; leave disabled otherwise.<br/>Default: `false`. |
5507
+ | `runtime_dir` | `String` | Directory for runtime files. When port is 0, transferd writes the selected port in file transferd.<port>.optport there. Created with owner-only permissions if missing. Omitted: ../var/run/aspera relative to the directory of the transferd executable.<br/>Example: `/var/run/aspera`. |
5508
+ | `tls` | `Hash` | TLS for the gRPC API. When enabled, clients must connect using TLS. |
5509
+ | `tls.certificate` | `String` | Path of the PEM server certificate file, which may include intermediate certificates. A relative path is resolved from the working directory of transferd.<br/>Example: `/etc/transferd/server.crt`. |
5510
+ | `tls.enabled` | `Bool` | Enables TLS. certificate and key are then required.<br/>Default: `false`. |
5511
+ | `tls.key` | `String` | Path of the PEM private key file matching certificate. A relative path is resolved from the working directory of transferd.<br/>Example: `/etc/transferd/server.key`. |
5512
+ | `tls.min_tls_version` | `Enum[String]` | Minimum TLS version accepted from clients. Omitted or other value: TLSv12.<br/>Allowed values: `TLSv12`, `TLSv13`.<br/>Default: `TLSv12`. |
5513
+ | `workers` | `Hash` | Transfer execution and retention. |
5514
+ | `workers.max_concurrent` | `Integer` | Maximum number of transfers running at the same time. Additional transfers wait in a queue until a running one ends. 0 or omitted: 100.<br/>Default: `100`.<br/>Example: `10`. |
5515
+ | `workers.transfer_cleaning_period` | `Integer` | Interval, in seconds, at which transferd removes ended transfers older than transfer_max_age. 0 or omitted: 3600 (1 hour).<br/>Default: `3600`. |
5516
+ | `workers.transfer_max_age` | `Integer` | Time, in seconds, during which an ended transfer remains known to transferd (status queries, events) before it can be removed. Removal happens at the next cleaning, so a transfer may remain up to transfer_max_age + transfer_cleaning_period. 0 or omitted: 7200 (2 hours).<br/>Default: `7200`.<br/>Example: `86400`. |
5517
+
5518
+ The configuration is checked before anything is written:
5519
+
5520
+ - Keys not given keep their value in the existing `transferd.json` (deep merge), and a key set to `null` is removed.
5521
+ - An unknown key, a value of a wrong type, or an inconsistent configuration (for example `tls.enabled` without `certificate` and `key`) is refused, with the name of the key and of the file if the faulty key is in the existing file.
5522
+ The daemon itself ignores unknown keys silently.
5523
+ - The section `fasp_runtime` is computed from the SDK folder, and can be overridden.
5524
+ - If `authentication.enabled` is `true` and no `api_key` is given, the key of the existing file is kept, else a random one is generated.
5525
+ The file is written in clear text with mode `0640`, owner `user:group`.
5526
+ To get the key from the [vault](#secret-vault), write `{"config":{"authentication":{"api_key":"@vault:transferd.api_key@"}}}` in an [Extended Value](#extended-value-syntax) `@json:@extend:'...'`.
5527
+
5528
+ Requirements:
5529
+
5530
+ - `systemd` on Linux only.
5531
+ On other systems, or without `systemctl`, commands fail with a message (only `spec` and `--dry-run` work everywhere).
5532
+ - Run as `root`, except with `--dry-run=yes` (option is a boolean), which shows the actions and the files without any change, and `spec` and `versions`.
5533
+ - The account (`asperadaemon` by default) is **not** created by `ascli`.
5534
+ If it does not exist, the command fails and shows the command to create it:
5535
+ `useradd --system --no-create-home --shell /usr/sbin/nologin asperadaemon`.
5536
+ This is the account used by other Aspera products on the same host, so that files have the same owner.
5537
+ - If the version of the SDK installed is different from the version of the schema, then a warning is displayed (it is not an error).
5538
+
5539
+ Example:
5540
+
5541
+ ```shell
5542
+ sudo ascli transferd service install --sdk-folder=/opt/aspera/transferd/current @json:'{"config":{"port":55002,"authentication":{"enabled":true}}}'
5543
+ ```
5544
+
5545
+ ```shell
5546
+ ascli transferd service configure --dry-run=yes @json:'{"config":{"log_level":"debug"}}'
5547
+ ```
5548
+
5549
+ ```shell
5550
+ sudo ascli transferd service status
5551
+ ```
5552
+
5553
+ ```shell
5554
+ sudo ascli transferd service uninstall @json:'{"service":{"purge":true}}'
5555
+ ```
5556
+
5557
+ ##### Versions side by side and rollback
5558
+
5559
+ If the SDK folder (option `sdk_folder`) is named `current`, e.g. `--sdk-folder=/opt/aspera/transferd/current`, then `ascli` uses the layout `<prefix>/<version>` with a link `current` that points to the version in use:
5560
+
5561
+ ```text
5562
+ /opt/aspera/transferd/1.1.9
5563
+ /opt/aspera/transferd/1.1.10
5564
+ /opt/aspera/transferd/current -> 1.1.10
5565
+ ```
5566
+
5567
+ - `service install` installs the version given in `service.version` (default: version tested with this release of `ascli`) in `<prefix>/<version>`, and sets the link `current`.
5568
+ If the installation fails, then the link is set back to the previous version.
5569
+ - The unit and `transferd.json` refer to `current`: switching the link and restarting the service is enough to change the version.
5570
+ - `service versions` lists the installed versions and the one in use.
5571
+ - `service use <VERSION>` switches the link and restarts the service.
5572
+ If the service does not start, then the link is set back to the previous version and the service is restarted.
5573
+
5574
+ Any other folder name is used as is, with no link.
5575
+
4571
5576
  ### Transfer Specification
4572
5577
 
4573
5578
  Some commands lead to file transfer (upload/download).
@@ -4656,7 +5661,7 @@ The description gives the supported agents, if not all, and the corresponding `a
4656
5661
  #### Transfer Specification Reference
4657
5662
 
4658
5663
  | ID | Name |
4659
- |----|-----------|
5664
+ | -- | --------- |
4660
5665
  | A | Direct |
4661
5666
  | C | Connect |
4662
5667
  | D | Desktop |
@@ -4665,61 +5670,61 @@ The description gives the supported agents, if not all, and the corresponding `a
4665
5670
  | T | Transferd |
4666
5671
 
4667
5672
  | Field | Type | Description |
4668
- |--------------------------------|-----------------|----------------------------------------------------------------------------------|
5673
+ | ------------------------------ | --------------- | -------------------------------------------------------------------------------- |
4669
5674
  | `apply_local_docroot` | `Bool` | Apply local docroot to source paths.<br/>(A, T)<br/>(`--apply-local-docroot`) |
4670
5675
  | `authentication` | `String` | Set to `token` for SSH bypass keys, else password asked if not provided.<br/>(C) |
4671
- | `cipher_allowed` | `String` | Returned by node API. Valid literals include `aes-128` and `none`.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>(C) |
4672
- | `cipher` | `String` | In transit encryption algorithms.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>Default: `none`.<br/>(`-c (conversion){enum}`) |
5676
+ | `cipher` | `Enum[String]` | In transit encryption algorithms.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>Default: `none`.<br/>(`-c (conversion){enum}`) |
5677
+ | `cipher_allowed` | `Enum[String]` | Returned by node API. Valid literals include `aes-128` and `none`.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>(C) |
5678
+ | `content_protection` | `Enum[String]` | Enable client-side content protection (CSEAR, encryption-at-rest).<br/>For uploads, set to `encrypt` to transfer encrypted files and store them on the server with the extension `.aspera-env`. (`aspera.conf` parameter `transfer_encryption_content_protection_extension`). To download and decrypt encrypted files, set to `decrypt`<br/>`content_protection_password` must be specified if this option is set.<br/>Allowed values: `encrypt`, `decrypt`.<br/>(`--file-crypt={enum}`) |
4673
5679
  | `content_protection_password` | `String` | Password for encryption/decryption of transferred assets.<br/>(env:`ASPERA_SCP_FILEPASS`) |
4674
- | `content_protection` | `String` | Enable client-side content protection (CSEAR, encryption-at-rest).<br/>For uploads, set to `encrypt` to transfer encrypted files and store them on the server with the extension `.aspera-env`. (`aspera.conf` parameter `transfer_encryption_content_protection_extension`). To download and decrypt encrypted files, set to `decrypt`<br/>`content_protection_password` must be specified if this option is set.<br/>Allowed values: `encrypt`, `decrypt`.<br/>(`--file-crypt={enum}`) |
4675
5680
  | `cookie` | `String` | Metadata for transfer specified by application.<br/>(env:`ASPERA_SCP_COOKIE`) |
4676
5681
  | `create_dir` | `Bool` | Create target directory if it doesn't already exist.<br/>If **all** the following conditions are met, then the `destination_root` specifies a filename instead of destination folder:<br/>- `create_dir` is `false`<br/>- A single source file is given on **command line**<br/>- The target folder specified by `destination_root` does not exist<br/>In all other cases, `destination_root` specifies a folder, and it is created if it does not already exist. I.e. if **any** of those conditions is met:<br/>- `create_dir` is `true`<br/>- Multiple source files are provided<br/>- List of source files are provided in a file (list or pair), default for Node API and `ascli`.<br/>- The target folder exists<br/>(`-d`) |
4677
5682
  | `delete_before_transfer` | `Bool` | Before transfer, delete files that exist at the destination but not at the source.<br/>The source and destination arguments must be directories that have matching names.<br/>Objects on the destination that have the same name but different type or size as objects on the source are not deleted.<br/>(`--delete-before-transfer`) |
4678
5683
  | `delete_source` | `Bool` | Remove transferred source files after transfer success. Equivalent to `remove_after_transfer` + `remove_empty_directories` + `remove_empty_source_directory`. Take precedence over those.<br/>(A, N, T) |
4679
- | `destination_root_id` | `String` | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(T) |
4680
5684
  | `destination_root` | `String` | Destination root directory.<br/>Required. |
5685
+ | `destination_root_id` | `String` | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(T) |
4681
5686
  | `dgram_size` | `Integer` | UDP datagram size in bytes.<br/>(`-Z {integer}`) |
4682
- | `direction` | `String` | Direction of transfer (on client side).<br/>Required.<br/>Allowed values: `send`, `receive`.<br/>(`--mode=(conversion){enum}`) |
5687
+ | `direction` | `Enum[String]` | Direction of transfer (on client side).<br/>Required.<br/>Allowed values: `send`, `receive`.<br/>(`--mode=(conversion){enum}`) |
4683
5688
  | `exclude_newer_than` | `String` | Exclude files, but not directories, from the transfer if they are newer than the specified number of seconds added to the source computer's epoch.<br/>e.g. `-86400` for newer than a day back.<br/>(`--exclude-newer-than={string}`) |
4684
5689
  | `exclude_older_than` | `String` | Exclude files, but not directories, from the transfer if they are older than the specified number of seconds added to the source computer's epoch.<br/>e.g. `-86400` for older than a day back.<br/>(`--exclude-older-than={string}`) |
4685
5690
  | `fail_bad_filepass` | `Bool` | Fail on bad file decryption passphrase.<br/>(A, T)<br/>(`--fail-bad-filepass`) |
4686
5691
  | `fasp_port` | `Integer` | Specifies fasp (UDP) port.<br/>Default: `33001`.<br/>(`-O {integer}`) |
4687
5692
  | `fasp_proxy` | `Hash` | Proxy for communications between the remote server and the (local) client.<br/>(T) |
4688
- | `file_checksum` | `String` | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: `sha-512`, `sha-384`, `sha-256`, `sha1`, `md5`, `none`.<br/>Default: `none`.<br/>(A, N)<br/>(`--file-checksum={enum}`) |
4689
- | `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
5693
+ | `file_checksum` | `Enum[String]` | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: `sha-512`, `sha-384`, `sha-256`, `sha1`, `md5`, `none`.<br/>Default: `none`.<br/>(A, N)<br/>(`--file-checksum={enum}`) |
4690
5694
  | `http_fallback` | `Bool, String` | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(`-y (conversion){boolean\|string}`) |
5695
+ | `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
4691
5696
  | `https_fallback_port` | `Integer` | Specifies HTTPS port when cipher is used.<br/>(`-t {integer}`) |
4692
5697
  | `icos` | `Hash` | Configuration parameters for IBM Cloud Object Storage (ICOS).<br/>(T) |
4693
5698
  | `keepalive` | `Bool` | The session is running in persistent session mode.<br/>(A, T)<br/>(`--keepalive`) |
4694
- | `lock_min_rate_kbps` | `Bool` | If `true`, lock the minimum transfer rate to the value set for min_rate_kbps.<br/>If `false`, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(C, T) |
4695
5699
  | `lock_min_rate` | `Bool` | n/a<br/>(C) |
5700
+ | `lock_min_rate_kbps` | `Bool` | If `true`, lock the minimum transfer rate to the value set for min_rate_kbps.<br/>If `false`, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(C, T) |
4696
5701
  | `lock_rate_policy` | `Bool` | If `true`, lock the rate policy to the default value.<br/>(C, T) |
4697
- | `lock_target_rate_kbps` | `Bool` | If `true`, lock the target transfer rate to the default value set for `target_rate_kbps`.<br/>If `false`, users can adjust the transfer rate up to the value set for `target_rate_cap_kbps`.<br/>(C, T) |
4698
5702
  | `lock_target_rate` | `Bool` | n/a<br/>(C) |
5703
+ | `lock_target_rate_kbps` | `Bool` | If `true`, lock the target transfer rate to the default value set for `target_rate_kbps`.<br/>If `false`, users can adjust the transfer rate up to the value set for `target_rate_cap_kbps`.<br/>(C, T) |
4699
5704
  | `min_rate_cap_kbps` | `Integer` | The highest minimum rate that an incoming transfer can request, in kilobits per second.<br/>Client minimum rate requests that exceed the minimum rate cap are ignored.<br/>The default value of unlimited applies no cap to the minimum rate. (Default: 0)<br/>(C, T) |
4700
5705
  | `min_rate_kbps` | `Integer` | Set the minimum transfer rate in kilobits per second.<br/>Default: `0`.<br/>(`-m {integer}`) |
4701
5706
  | `move_after_transfer` | `String` | Move source files to the specified `archive-dir` directory after they are transferred correctly.<br/>Available as of 3.8.0. Details in `ascp` manual.<br/>Requires write permissions on the source.<br/>If `src_base` is specified, files are moved to `archive-dir`/`path-relative-to-srcbase`.<br/>`archive-dir` must be in the same file system (or cloud storage account) as the source files being transferred.<br/>`archive-dir` is subject to the same docroot restrictions as source files.<br/>`move_after_transfer` and `remove_after_transfer` are mutually exclusive options.<br/>After files have been moved to the archive, the original source directory structure is left in place. Empty directories are not saved to `archive-dir`. To remove empty source directories after a successful move operation, also set `remove_empty_directories` to `true`. When using `remove_empty_directories`, empty directory removal examination starts at the `srcbase` and proceeds down any subdirectories. If no `srcbase` is used and a file path (as opposed to a directory path) is specified, then only the immediate parent directory is examined and removed if it is empty following the move of the source file.<br/>(A, N, T)<br/>(`--move-after-transfer={string}`) |
4702
- | `multi_session_threshold` | `Integer` | Split files across multiple `ascp` sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(A, N, T)<br/>(`--multi-session-threshold={integer}`) |
4703
5707
  | `multi_session` | `Integer` | Use multi-session transfer. max 128.<br/>Each participant on one host needs an independent UDP (-O) port.<br/>Large files are split between sessions only when transferring with `resume_policy`=`none`.<br/>(special:`-C {integer}`) |
5708
+ | `multi_session_threshold` | `Integer` | Split files across multiple `ascp` sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(A, N, T)<br/>(`--multi-session-threshold={integer}`) |
4704
5709
  | `obfuscate_file_names` | `Bool` | HTTP Gateway obfuscates file names when set to `true`.<br/>(H) |
4705
- | `overwrite` | `String` | Overwrite files at the destination with source files of the same name based on the policy:<br/>- `always` : Always overwrite the file.<br/>- `never` : Never overwrite the file. If the destination contains partial files that are older or the same as the source files and resume is enabled, the partial files resume transfer. Partial files with checksums or sizes that differ from the source files are not overwritten.<br/>- `diff` : (default) Overwrite the file if it is different from the source, depending on the compare method (default is size). If the destination is object storage, `diff` has the same effect as always. If resume is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. If resume is enabled, only partial files with different sizes or checksums from the source are overwritten; otherwise, files resume.<br/>- `diff+older` : Overwrite the file if it is older and different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. If resume is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.<br/>- `older` : Overwrite the file if its timestamp is older than the source timestamp.<br/>If you set an overwrite policy of `diff` or `diff+older`, difference is determined by the value set for `resume_policy`:<br/>`none` : The source and destination files are always considered different and the destination file is always overwritten<br/>`attributes` : The source and destination files are compared based on file attributes <br/>`sparse_checksum` : The source and destination files are compared based on sparse checksums, (currently file size)<br/>`full_checksum` : The source and destination files are compared based on full checksums<br/>Allowed values: `never`, `always`, `diff`, `older`, `diff+older`.<br/>Default: `diff`.<br/>(`--overwrite={enum}`) |
5710
+ | `overwrite` | `Enum[String]` | Overwrite files at the destination with source files of the same name based on the policy:<br/>- `always` : Always overwrite the file.<br/>- `never` : Never overwrite the file. If the destination contains partial files that are older or the same as the source files and resume is enabled, the partial files resume transfer. Partial files with checksums or sizes that differ from the source files are not overwritten.<br/>- `diff` : (default) Overwrite the file if it is different from the source, depending on the compare method (default is size). If the destination is object storage, `diff` has the same effect as always. If resume is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. If resume is enabled, only partial files with different sizes or checksums from the source are overwritten; otherwise, files resume.<br/>- `diff+older` : Overwrite the file if it is older and different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. If resume is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.<br/>- `older` : Overwrite the file if its timestamp is older than the source timestamp.<br/>If you set an overwrite policy of `diff` or `diff+older`, difference is determined by the value set for `resume_policy`:<br/>`none` : The source and destination files are always considered different and the destination file is always overwritten<br/>`attributes` : The source and destination files are compared based on file attributes <br/>`sparse_checksum` : The source and destination files are compared based on sparse checksums, (currently file size)<br/>`full_checksum` : The source and destination files are compared based on full checksums<br/>Allowed values: `never`, `always`, `diff`, `older`, `diff+older`.<br/>Default: `diff`.<br/>(`--overwrite={enum}`) |
4706
5711
  | `password` | `String` | Password for local Windows user when transfer user associated with node API user is not the same as the one running `asperanoded`.<br/>Allows impersonating the transfer user and have access to resources (e.g. network shares).<br/>Windows only, node API only.<br/>(N) |
4707
5712
  | `paths` | `Array` | Array of path to the source (required) and a path to the destination (optional).<br/>Required. |
4708
5713
  | `precalculate_job_size` | `Bool` | Specifies whether to precalculate the job size.<br/>(`--precalculate-job-size / --precalculate-disable`) |
4709
5714
  | `preserve_access_time` | `Bool` | Preserve the source-file access timestamps at the destination.<br/>Because source access times are updated by the transfer operation, the timestamp that is preserved is the one just before to the transfer.<br/>(`--preserve-access-time`) |
4710
- | `preserve_acls` | `String` | Preserve access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-acls={enum}`) |
5715
+ | `preserve_acls` | `Enum[String]` | Preserve access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-acls={enum}`) |
4711
5716
  | `preserve_creation_time` | `Bool` | Preserve source-file creation timestamps at the destination.<br/>Only Windows systems retain information about creation time. If the destination is not a Windows computer, this option is ignored.<br/>(`--preserve-creation-time`) |
4712
- | `preserve_extended_attrs` | `String` | Preserve the extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-xattrs={enum}`) |
5717
+ | `preserve_extended_attrs` | `Enum[String]` | Preserve the extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-xattrs={enum}`) |
4713
5718
  | `preserve_file_owner_gid` | `Bool` | Preserve the group ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-gid`) |
4714
5719
  | `preserve_file_owner_uid` | `Bool` | Preserve the user ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-uid`) |
4715
5720
  | `preserve_modification_time` | `Bool` | Set the modification time, the last time a file or directory was modified (written), of a transferred file to the modification of the source file or directory.<br/>Preserve source-file modification timestamps at the destination.<br/>(`--preserve-modification-time`) |
4716
- | `preserve_remote_acls` | `String` | Preserve remote access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-acls={enum}`) |
4717
- | `preserve_remote_extended_attrs` | `String` | Preserve remote extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-xattrs={enum}`) |
5721
+ | `preserve_remote_acls` | `Enum[String]` | Preserve remote access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-acls={enum}`) |
5722
+ | `preserve_remote_extended_attrs` | `Enum[String]` | Preserve remote extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-xattrs={enum}`) |
4718
5723
  | `preserve_source_access_time` | `Bool` | Preserve the time logged for when the source file was accessed.<br/>(A, T)<br/>(`--preserve-source-access-time`) |
4719
5724
  | `preserve_times` | `Bool` | Preserve file timestamps.<br/>(A, N, T)<br/>(`-p`) |
4720
5725
  | `proxy` | `String` | Specify the address of the Aspera high-speed proxy server.<br/>`dnat(s)://[user[:password]@]server:port`<br/>Default ports for DNAT and DNATS protocols are 9091 and 9092.<br/>Password, if specified here, overrides the value of environment variable `ASPERA_PROXY_PASS`.<br/>(A)<br/>(`--proxy={string}`) |
4721
- | `rate_policy_allowed` | `String` | Specifies most aggressive rate policy that is allowed. Returned by node API.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(C) |
4722
- | `rate_policy` | `String` | The transfer rate policy to use when sharing bandwidth. Allowable values:<br/>- `high` : When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.<br/>- `fair` : (Default) Share bandwidth equally with other traffic.<br/>- `low` : Use only unused bandwidth.<br/>- `fixed` : Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. Aspera recommends that you do not use this setting except under special circumstances, otherwise the destination storage can be damaged.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(`--policy={enum}`) |
5726
+ | `rate_policy` | `Enum[String]` | The transfer rate policy to use when sharing bandwidth. Allowable values:<br/>- `high` : When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.<br/>- `fair` : (Default) Share bandwidth equally with other traffic.<br/>- `low` : Use only unused bandwidth.<br/>- `fixed` : Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. Aspera recommends that you do not use this setting except under special circumstances, otherwise the destination storage can be damaged.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(`--policy={enum}`) |
5727
+ | `rate_policy_allowed` | `Enum[String]` | Specifies most aggressive rate policy that is allowed. Returned by node API.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(C) |
4723
5728
  | `remote_access_key` | `String` | The access key ID of the access key that was used to construct the bearer token that is used to authenticate to the remote node.<br/>(T) |
4724
5729
  | `remote_host` | `String` | IP or fully qualified domain name (FQDN) of the remote server.<br/>Required.<br/>(`--host={string}`) |
4725
5730
  | `remote_password` | `String` | SSH session password.<br/>(env:`ASPERA_SCP_PASS`) |
@@ -4729,27 +5734,27 @@ The description gives the supported agents, if not all, and the corresponding `a
4729
5734
  | `remove_empty_source_dir` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(T) |
4730
5735
  | `remove_empty_source_directory` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(A)<br/>(`--remove-empty-source-directory`) |
4731
5736
  | `remove_skipped` | `Bool` | Must also have `remove_after_transfer` set to `true`. Defaults to `false`. If `true`, skipped files will be removed as well.<br/>(A, C, N)<br/>(`--remove-skipped`) |
4732
- | `resume_policy` | `String` | If a transfer is interrupted or fails to finish, this policy directs the transfer to resume without retransferring the files. Allowable values:<br/>- `none` : Always re-transfer the entire file.<br/>- `attrs` : Compare file attributes and resume if they match, and re-transfer if they do not.<br/>- `sparse_csum` : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.<br/>- `full_csum` : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.<br/>Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.<br/>Allowed values: `none`, `attrs`, `sparse_csum`, `full_csum`.<br/>Default: `faspmgr:none;other:sparse_csum`.<br/>(`-k (conversion){enum}`) |
5737
+ | `resume_policy` | `Enum[String]` | If a transfer is interrupted or fails to finish, this policy directs the transfer to resume without retransferring the files. Allowable values:<br/>- `none` : Always re-transfer the entire file.<br/>- `attrs` : Compare file attributes and resume if they match, and re-transfer if they do not.<br/>- `sparse_csum` : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.<br/>- `full_csum` : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.<br/>Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.<br/>Allowed values: `none`, `attrs`, `sparse_csum`, `full_csum`.<br/>Default: `faspmgr:none;other:sparse_csum`.<br/>(`-k (conversion){enum}`) |
4733
5738
  | `retry_duration` | `Integer, String` | Specifies how long to wait before retrying transfer (e.g. `5min`).<br/>(T) |
4734
5739
  | `save_before_overwrite` | `Bool` | If a transfer would result in an existing file <filename>.<ext> being overwritten, move that file to <filename>.yyyy.mm.dd.hh.mm.ss.index.<ext> (where index is set to 1 at the beginning of each new second and incremented for each file saved in this manner during the same second) in the same directory before writing the new file.<br/>File attributes are maintained in the renamed file.<br/>(A, N, T)<br/>(`--save-before-overwrite`) |
4735
5740
  | `skip_duplicate_check` | `Bool` | Don't check for duplicate files at the destination.<br/>(A, T)<br/>(`--skip-dir-traversal-dupes`) |
4736
5741
  | `skip_special_files` | `Bool` | All assets other than files, directories and symbolic links are considered special. A transfer will fail if the user attempts to transfer special assets. If `true`, `ascp` skips special assets and proceeds with the transfer of all other assets.<br/>(A, T)<br/>(`--skip-special-files`) |
4737
- | `source_root_id` | `String` | The file ID of the source root directory. Required when using Bearer token auth for the source node.<br/>(N, T) |
4738
5742
  | `source_root` | `String` | Path to be prepended to each source path.<br/>This is either a conventional path or it can be a URI but only if there is no root defined.<br/>(`--source-prefix64=(conversion){string}`) |
4739
- | `src_base64` | `String` | The folder name below which the directory structure is preserved (base64 encoded).<br/>(A, T)<br/>(`--src-base64={string}`) |
5743
+ | `source_root_id` | `String` | The file ID of the source root directory. Required when using Bearer token auth for the source node.<br/>(N, T) |
4740
5744
  | `src_base` | `String` | Specify the prefix to be stripped off from each source object.<br/>The remaining portion of the source path is kept intact at the destination.<br/>Special care must be taken when used with cloud storage.<br/>(A, N, T)<br/>(`--src-base64=(conversion){string}`) |
5745
+ | `src_base64` | `String` | The folder name below which the directory structure is preserved (base64 encoded).<br/>(A, T)<br/>(`--src-base64={string}`) |
4741
5746
  | `ssh_args` | `Array` | Add arguments to the command-line arguments passed to the external ssh program (implies -SSH). The arguments are inserted before any key file(s) supplied to `ascp` and before the user/host arguments.<br/>(A, T)<br/>(special:`--ssh-arg={array}`) |
4742
5747
  | `ssh_port` | `Integer` | Specifies SSH (TCP) port.<br/>Default: `direct:22, other:33001`.<br/>(`-P {integer}`) |
5748
+ | `ssh_private_key` | `String` | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----&bsol;nMII...<br/>Note the JSON encoding: &bsol;n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
4743
5749
  | `ssh_private_key_passphrase` | `String` | The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.<br/>(A, T)<br/>(env:`ASPERA_SCP_PASS`) |
4744
5750
  | `ssh_private_key_path` | `String` | Path to private key for SSH.<br/>(A, T)<br/>(`-i {string}`) |
4745
- | `ssh_private_key` | `String` | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----&bsol;nMII...<br/>Note the JSON encoding: &bsol;n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
4746
5751
  | `sshfp` | `String` | Check it against server SSH host key fingerprint.<br/>(`--check-sshfp={string}`) |
4747
- | `symlink_policy` | `String` | Handle source side symbolic links. Refer to HSTS manual for more details.<br/>- `follow`: Follow a symbolic link and transfer the contents of the linked file or directory when the link target is in the user's docroot.<br/>- `copy`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file.<br/>- `skip`: Skip-symbolic links. The link or the file to which it points are not transferred.<br/>- `copy+force`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced.<br/>Allowed values: `follow`, `copy`, `copy+force`, `skip`.<br/>Default: `follow`.<br/>(`--symbolic-links={enum}`) |
4748
- | `tags64` | `String` | Base64 string for `tags`.<br/>(A, T)<br/>(`--tags64={string}`) |
5752
+ | `symlink_policy` | `Enum[String]` | Handle source side symbolic links. Refer to HSTS manual for more details.<br/>- `follow`: Follow a symbolic link and transfer the contents of the linked file or directory when the link target is in the user's docroot.<br/>- `copy`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file.<br/>- `skip`: Skip-symbolic links. The link or the file to which it points are not transferred.<br/>- `copy+force`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced.<br/>Allowed values: `follow`, `copy`, `copy+force`, `skip`.<br/>Default: `follow`.<br/>(`--symbolic-links={enum}`) |
4749
5753
  | `tags` | `Hash` | Metadata for transfer as JSON. Key `aspera` is reserved. Key `aspera.xfer_retry` specifies a "retry timeout" but is not actually used for node API initiated transfers.<br/>(`--tags64=(conversion){object}`) |
5754
+ | `tags64` | `String` | Base64 string for `tags`.<br/>(A, T)<br/>(`--tags64={string}`) |
5755
+ | `target_rate` | `String, Integer` | Pseudo-parameter: desired transfer rate in bps, with an optional unit suffix. Converted to `target_rate_kbps` (rounded down) before the transfer is started, overriding it if both are present. Also applies to `async` (sync). Accepted formats: integer (bps), or integer followed by `k`/`K` (x1000), `m`/`M` (x1000000), `g`/`G` (x1000000000). Examples: `100000000`, `100000k`, `100m`, `1g`. |
4750
5756
  | `target_rate_cap_kbps` | `Integer` | Maximum target rate for incoming transfers, in kilobits per second. Returned by upload/download_setup node API.<br/>(C, T) |
4751
5757
  | `target_rate_kbps` | `Integer` | Specifies desired speed for the transfer.<br/>(`-l {integer}`) |
4752
- | `target_rate` | `String, Integer` | Pseudo-parameter: desired transfer rate in bps, with an optional unit suffix. Converted to `target_rate_kbps` (rounded down) before the transfer is started, overriding it if both are present. Also applies to `async` (sync). Accepted formats: integer (bps), or integer followed by `k`/`K` (x1000), `m`/`M` (x1000000), `g`/`G` (x1000000000). Examples: `100000000`, `100000k`, `100m`, `1g`. |
4753
5758
  | `title` | `String` | Title of the transfer.<br/>(C, N, T) |
4754
5759
  | `token` | `String` | Authorization token. Type is Bearer, Basic or ATM.<br/>(env:`ASPERA_SCP_TOKEN`) |
4755
5760
  | `use_ascp4` | `Bool` | Specify version of protocol. `ascp4` will be deprecated.<br/>Default: `false`.<br/>(A, N, T) |
@@ -5563,7 +6568,7 @@ If the transfer user has no docroot and the transfer does not use a token, you c
5563
6568
  ```text
5564
6569
  ascli -h
5565
6570
  NAME
5566
- ascli -- a command line tool for Aspera Applications (v4.28.0)
6571
+ ascli -- a command line tool for Aspera Applications (v4.29.1)
5567
6572
 
5568
6573
  SYNOPSIS
5569
6574
  ascli [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
@@ -5574,6 +6579,7 @@ DESCRIPTION
5574
6579
  execute: ascli conf doc
5575
6580
  or visit: https://ibm.biz/ascli-doc
5576
6581
  source repo: https://github.com/IBM/aspera-cli
6582
+ AI assistants: ascli config commands, https://ibm.github.io/aspera-cli/llms.txt
5577
6583
 
5578
6584
  ENVIRONMENT VARIABLES
5579
6585
  Any option can be set as an environment variable, refer to the manual
@@ -5619,7 +6625,7 @@ OPTIONS: global
5619
6625
  -h, --help Show this message
5620
6626
  --show-config Display parameters used for the provided action
5621
6627
  -v, --version Display version
5622
- --ui=HASH User interface (dot-notation: mode, command)
6628
+ --ui=HASH User interface (dot-notation: mode, web_auth, hidden_silent, command)
5623
6629
  --invalid-characters=VALUE Replacement character and invalid filename characters
5624
6630
  --log-level=ENUM Log level
5625
6631
  --log-format=VALUE Log formatter
@@ -5628,6 +6634,7 @@ OPTIONS: global
5628
6634
  --security=HASH Security restrictions (dot-notation: level, allowed_paths)
5629
6635
  --lock-port=INT Prevent dual execution of a command, e.g. in cron
5630
6636
  --once-only=yes|no Process only new items (some commands)
6637
+ --dry-run=yes|no Do not perform changes, only show what would be done
5631
6638
  --log-secrets=yes|no Show passwords in logs
5632
6639
  --temp=HASH Temporary files (dot-notation: folder, clean, expiry)
5633
6640
  --clean-temp=yes|no Cleanup temporary files on exit (deprecated after 4.27.5: use --temp.clean)
@@ -5643,6 +6650,7 @@ OPTIONS: global
5643
6650
  --fpac=VALUE Proxy auto configuration script
5644
6651
  --proxy-credentials=LIST HTTP proxy credentials for fpac: user, password
5645
6652
  --sql=VALUE SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)
6653
+ --ascp-logs=HASH Ascp: log analysis (dot-notation: period, zero_bytes, mtu, resolve, thresholds, timezone, health_minutes, remote_max_size)
5646
6654
  -P, --preset=VALUE Load the named option preset from current config file
5647
6655
  --version-check-days=INT Period in days to check new version (zero to disable)
5648
6656
  --plugin-folder=VALUE Folder where to find additional plugins
@@ -5655,9 +6663,6 @@ OPTIONS: global
5655
6663
  --cache-tokens=yes|no Save and reuse OAuth tokens
5656
6664
  --expand-mounts=yes|no Commands: list commands of sub-trees provided by another plugin
5657
6665
  -N, --no-default Do not load default configuration for plugin
5658
- --override=yes|no Wizard: override existing value
5659
- --default=yes|no Wizard: set as default configuration for specified plugin (also: update)
5660
- --key-path=VALUE Wizard: path to private key for JWT
5661
6666
  --insecure=yes|no HTTP/S: Do not validate any certificate
5662
6667
  --ignore-certificate=LIST HTTP/S: Do not validate certificate for these URLs
5663
6668
  --warn-insecure=yes|no HTTP/S: Issue a warning if certificate is ignored
@@ -5667,6 +6672,7 @@ OPTIONS: global
5667
6672
  --query=HASH Additional filter for for some commands (list/delete)
5668
6673
  --bulk=yes|no Bulk operation (only some)
5669
6674
  --bfail=yes|no Bulk operation error handling
6675
+ --poll=HASH Repeat a read-only command (dot-notation: interval, max, timeout, until, show, errors)
5670
6676
  --ts=HASH Override transfer spec values
5671
6677
  --to-folder=VALUE Destination folder for transferred files
5672
6678
  --sources=VALUE How list of transferred files is provided (@args,@ts,Array)
@@ -5689,6 +6695,7 @@ PLUGINS
5689
6695
  preview Preview
5690
6696
  server HSTS Fasp/SSH
5691
6697
  shares Shares
6698
+ transferd Transfer Daemon
5692
6699
 
5693
6700
 
5694
6701
  ```
@@ -5699,25 +6706,6 @@ Bulk creation and deletion of resources are possible using option `bulk` (`yes`,
5699
6706
  In that case, the operation expects an `Array` of `Hash` instead of a simple `Hash` using the [Extended Value](#extended-value-syntax) syntax.
5700
6707
  This option is available only for some resources: if you need it, try and see if the entities you create or delete support this option.
5701
6708
 
5702
- ### Option: `query`
5703
-
5704
- The `query` option can generally be used to add URL parameters to commands that list resources.
5705
- It takes a `Hash`, corresponding to key/value pairs that appear in the query part of the request.
5706
-
5707
- For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
5708
-
5709
- If the same parameter needs to be provided several times, then it is also possible to provide an `Array`.
5710
-
5711
- For example: `--query=@json:'{"p":["v1","v2"]}'` leads to query: `?p=v1&p=v2`.
5712
-
5713
- If PHP-style arrays are expected in the API, add `[]` to the name of the parameter.
5714
-
5715
- For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=v2`.
5716
-
5717
- > [!TIP]
5718
- > Use `--query=help` on any `list` command to display the available query parameters and their types, as documented in the API.
5719
- > For example: `ascli faspex5 admin accounts list --query=help`
5720
-
5721
6709
  ### Plugins
5722
6710
 
5723
6711
  `ascli` uses a plugin mechanism.
@@ -5761,11 +6749,82 @@ ascli config plugins create foo .
5761
6749
  Created ./foo.rb
5762
6750
  ```
5763
6751
 
5764
-
5765
6752
  ```shell
5766
6753
  ascli --plugin-folder=. foo
5767
6754
  ```
5768
6755
 
6756
+ #### Writing a plugin
6757
+
6758
+ A plugin is a Ruby file in a plugin folder (option `plugin_folder`, or folder `plugins` of the configuration folder).
6759
+
6760
+ - **Name**: the file name is the plugin name, which is the first command, e.g. file `my_app.rb` for command `my_app`.
6761
+ The file defines class `Aspera::Cli::Plugins::<Class>`, the name in CamelCase (`MyApp`), subclass of:
6762
+ - `Base`: no common option.
6763
+ - `BasicAuth` (`aspera/cli/plugins/basic_auth`): options `url`, `username`, `password`, method `basic_auth_api` returns a REST client with HTTP Basic authentication.
6764
+ - `Oauth` (`aspera/cli/plugins/oauth`): options of `BasicAuth`, and `auth` (default `jwt`), `client_id`, `client_secret`, `redirect_uri`, `private_key`, `passphrase`.
6765
+ - **Requires**: the plugin requires the files of the gem that it uses, e.g. `require 'aspera/cli/plugins/base'` (the `lib` folder of the gem is in the Ruby load path).
6766
+ Built-in plugins load only what they use: a class of the gem (for example `Plugins::Oauth`, `Rest::Client`) may not be loaded yet when the plugin is read (`NameError: uninitialized constant`).
6767
+ - **Options**: `option :<name>, description: '...'` (optional: `default:`, `allowed:` a type or a list of values), value read with `options.get_option(:<name>)` (`mandatory: true` to require it).
6768
+ `use_options <Module>` adds the options of a module, e.g. `use_options OauthWebOptions` (`client_id`, `client_secret`, `redirect_uri`) for the OAuth web flow only, without the other options of `Oauth`.
6769
+ - **Commands**: `command :<name>, description: '...'`, inside `commands_under :<name> do ... end` for sub-commands.
6770
+ Positional arguments: `arguments: [{name: :<name>, description: '...'}]` (optional: `mandatory: false`, `default:`, `type: Hash`, `multiple: true`).
6771
+ `read_only: true` for a command that changes nothing (allowed with option `poll`).
6772
+ - **Actions**: the method `action_<command path>`, e.g. `action_item_show` for `item show`, receives the arguments as keyword arguments (and `**` for others).
6773
+ It returns a result, displayed according to option `format`: `Result::SingleObject.new(<Hash>)`, `Result::ObjectList.new(<Array of Hash>)`, `Result::Status.new('<text>')`, `Result::Nothing.new`.
6774
+ - **REST**: `Rest::Client.new(base_url:, auth:)` (`aspera/rest`), methods `read`, `create`, `update`, `delete` (JSON), and `call` for other cases:
6775
+ - `auth`: `{type: :basic, username:, password:}`, or `{type: :oauth2, grant_method: :web, client_id:, ...}` (see `lib/aspera/oauth/client`).
6776
+ Parameters `path_authorize` and `path_token` are paths from `base_url`, or absolute URLs, when the token is created on another host than the authorization page.
6777
+ Parameter `token_field` is the field of the token in the answer (default `access_token`), or a dot-separated path of a nested field, e.g. `authed_user.access_token` for a Slack user token.
6778
+ - Raw body, e.g. binary, sent as is: `call(operation: 'PUT', body: <String or IO>, headers: {'Content-Type' => '<MIME_TYPE>'})`.
6779
+ An `IO` (e.g. `File.open(path, 'rb')`) is streamed from its current position, without loading the file in memory.
6780
+ - **Errors**: raise `Cli::BadArgument` (wrong argument or option) or `Cli::Error`.
6781
+ For any other error, the location in the plugin (file and line) is logged at level `info`.
6782
+ - **Security**: a plugin is code: plugins from other folders than the gem are loaded at [Security Level](#security-level) `low` only.
6783
+
6784
+ Example: plugin `my_app` for a REST API with Basic authentication: `my_app info`, `my_app item list`, `my_app item show <ID>`.
6785
+
6786
+ ```ruby
6787
+ # Plugin `my_app`, file `my_app.rb` in a plugin folder, class `MyApp`
6788
+ # Files of the gem used by the plugin (its `lib` folder is in the load path)
6789
+ require 'aspera/cli/plugins/basic_auth'
6790
+
6791
+ module Aspera
6792
+ module Cli
6793
+ module Plugins
6794
+ # Options `url`, `username` and `password` of `BasicAuth`
6795
+ class MyApp < BasicAuth
6796
+ application_name 'My Application'
6797
+ option :page_size, description: 'Number of items per page', allowed: Integer, default: 100
6798
+
6799
+ command :info, description: 'Show application information', read_only: true
6800
+ commands_under :item, description: 'Manage items' do
6801
+ command :list, description: 'List items', read_only: true
6802
+ command :show, description: 'Show an item', arguments: [{name: :id, description: 'Item identifier'}], read_only: true
6803
+ end
6804
+
6805
+ # Command `info`
6806
+ def action_info(**) = Result::SingleObject.new(api.read('info'))
6807
+
6808
+ # Command `item list`
6809
+ def action_item_list(**) = Result::ObjectList.new(api.read('items', {limit: options.get_option(:page_size)}))
6810
+
6811
+ # Command `item show <ID>`, with arguments as keyword arguments
6812
+ def action_item_show(id:, **) = Result::SingleObject.new(api.read("items/#{id}"))
6813
+
6814
+ private
6815
+
6816
+ # REST client of the application, with Basic authentication
6817
+ def api = @api ||= basic_auth_api
6818
+ end
6819
+ end
6820
+ end
6821
+ end
6822
+ ```
6823
+
6824
+ ```shell
6825
+ ascli --plugin-folder=<FOLDER> my_app item list --url=https://app.example.com/api --username=<USERNAME> --password=<PASSWORD> --page-size=10
6826
+ ```
6827
+
5769
6828
  ### Plugins vs Transfer Agents
5770
6829
 
5771
6830
  Plugins typically represent a specific remote application on which `ascli` can operate, while transfer agents are the underlying components that handle the actual data transfer.
@@ -5834,7 +6893,7 @@ It's up to the program to split arguments:
5834
6893
 
5835
6894
  `ascli` is a Ruby program, so Ruby parses the command line (received with `GetCommandLineW`) into arguments and provides them to the Ruby code (`$0` and `ARGV`).
5836
6895
  Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
5837
- (See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)): <!--cspell:disable-line-->
6896
+ (See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)):
5838
6897
 
5839
6898
  - Space characters: split arguments (space, tab, newline)
5840
6899
  - Backslash: `\` escapes a single special character
@@ -6144,11 +7203,13 @@ To complete the setup, you must have:
6144
7203
 
6145
7204
  #### Wizard Invocation
6146
7205
 
6147
- The wizard accepts two optional positional arguments:
7206
+ The wizard accepts an optional argument, a `Hash` with keys:
7207
+
7208
+ - `url`: The organization name or the full FQDN.
6148
7209
 
6149
- - **Organization/URL**: The organization name or the full FQDN.
7210
+ - `plugin`: Specify `aoc` to bypass automatic application detection.
6150
7211
 
6151
- - **Plugin Name**: Specify `aoc` to bypass automatic application detection.
7212
+ - `preset`: Name of the preset to create.
6152
7213
 
6153
7214
  If the URL is omitted, the wizard will prompt for it interactively.
6154
7215
 
@@ -6165,8 +7226,8 @@ Once saved in the UI, return to the terminal and press Enter.
6165
7226
  ```console
6166
7227
  $ ascli config wizard
6167
7228
  Using: Aspera on Cloud at https://<ORG_NAME>.ibmaspera.com
6168
- Path to private RSA key (leave empty to generate):
6169
- option: key_path>
7229
+ Private RSA key, e.g. @file:<path> (leave empty to generate):
7230
+ option: private_key>
6170
7231
  Using existing key:
6171
7232
  /home/john/.aspera/ascli/<PKEY_NAME>.pem
6172
7233
  Please Log in as user john@example.com at: https://<ORG_NAME>.ibmaspera.com
@@ -6191,12 +7252,12 @@ Saving config file.
6191
7252
 
6192
7253
  - **Custom Client Identification**:
6193
7254
  By default, `ascli` uses a pre-registered global client ID.
6194
- To create and use an organization-specific integration, use the `--use-generic-client=no` flag.
7255
+ To create and use an organization-specific integration, give the option `--use-generic-client=no` of plugin `aoc` to the wizard command.
6195
7256
 
6196
7257
  - **Direct Plugin Targeting**: To limit detection to the `aoc` plugin and skip discovery, provide both the URL and plugin name:
6197
7258
 
6198
7259
  ```shell
6199
- ascli config wizard <ORG_NAME> aoc
7260
+ ascli config wizard @: url=<ORG_NAME> plugin=aoc
6200
7261
  ```
6201
7262
 
6202
7263
  #### Verifying the Configuration
@@ -6262,6 +7323,7 @@ To register with web-based authentication (auth=web):
6262
7323
 
6263
7324
  > [!NOTE]
6264
7325
  > For web based authentication, `ascli` listens on a local port (for example, specified by the `redirect_uri` parameter, in this example: `12345`), and the browser will provide the OAuth code there.
7326
+ > See [Web login flow](#web-login-flow).
6265
7327
  > For `ascli`, HTTP is required, and `12345` is the default port.
6266
7328
  > The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
6267
7329
 
@@ -6284,7 +7346,7 @@ updated: <AOC_ORG>
6284
7346
  > [!NOTE]
6285
7347
  > In above example, replace `https://<ORG_NAME>.ibmaspera.com` with your actual AoC URL.
6286
7348
 
6287
- (This can also be done in one line using the command `config preset update <AOC_ORG> --url=...`)
7349
+ (This can also be done in one line using the command `config preset set <AOC_ORG> @: url=...`)
6288
7350
 
6289
7351
  Define this [Option Preset](#option-preset) as default configuration for the `aoc` plugin:
6290
7352
 
@@ -6398,7 +7460,7 @@ To activate default use of JWT authentication for `ascli` using the [Option Pres
6398
7460
  Execute:
6399
7461
 
6400
7462
  ```shell
6401
- ascli config preset update <AOC_ORG> --auth=jwt --private-key=@val:@file:~/.aspera/ascli/<PKEY_NAME> --username=someuser@example.com
7463
+ ascli config preset set <AOC_ORG> @: auth=jwt private_key=@val:@file:~/.aspera/ascli/<PKEY_NAME> username=someuser@example.com
6402
7464
  ```
6403
7465
 
6404
7466
  > [!NOTE]
@@ -6518,7 +7580,7 @@ The following parameters are supported:
6518
7580
  | other | Native | Other specific parameters depending on resource type. |
6519
7581
 
6520
7582
  > [!NOTE]
6521
- > Both `max` and `pmax` are processed internally in `ascli`, not included in actual API call and limit the number of successive pages requested to API.
7583
+ > Both `max` and `pmax` are processed by `ascli` (see [option `--query`](#option---query-parameters-of-the-api)).
6522
7584
  > `ascli` will return all values using paging if not provided.
6523
7585
  > `page` and `per_page` are normally added by `ascli` to build successive API calls to get all values if there are more than 1000
6524
7586
  > (AoC allows a maximum page size of 1000).
@@ -6529,7 +7591,7 @@ The following parameters are supported:
6529
7591
  > For example: `ascli aoc admin user list --query=help`
6530
7592
 
6531
7593
  > [!TIP]
6532
- > The option `select` can also be used to further refine selection, refer to [section earlier](#option-select).
7594
+ > Options `--out.query` and `--out.select` can also be used to further refine selection, refer to [Filtering results](#filtering-results).
6533
7595
 
6534
7596
  Examples:
6535
7597
 
@@ -6785,7 +7847,7 @@ ascli aoc user settings modify <ID> @json:'{"value":"..."}'
6785
7847
  > - **Application identity**: derived from the `client_id` used during authentication.
6786
7848
  >
6787
7849
  > This means that settings stored by one client application (for example, the AoC web UI) are not visible to another (for example, `ascli` using a different `client_id`).
6788
- > By default, `ascli` uses the pre-registered global `client_id` (see `--use-generic-client`).
7850
+ > By default, `ascli` uses the pre-registered global `client_id` (see option `--use-generic-client` of plugin `aoc`).
6789
7851
 
6790
7852
  #### Example: Create a sub access key in a `node`
6791
7853
 
@@ -6954,7 +8016,7 @@ In this example, a user has access to a workspace where two shared folders are l
6954
8016
  First, set up the environment (skip if already done), see [AoC configuration: Using Wizard](#aoc-configuration-using-wizard):
6955
8017
 
6956
8018
  ```shell
6957
- ascli config wizard https://sedemo.ibmaspera.com aoc aoc_sedemo --username=someuser@example.com
8019
+ ascli config wizard @: url=https://sedemo.ibmaspera.com plugin=aoc preset=aoc_sedemo --username=someuser@example.com
6958
8020
  ```
6959
8021
 
6960
8022
  This creates the option preset `aoc_sedemo` to allow seamless command line access and sets it as default for Aspera on Cloud.
@@ -7241,7 +8303,7 @@ The `package_folder` option (`Hash`) controls how downloaded packages are organi
7241
8303
  **Supported Fields**:
7242
8304
 
7243
8305
  | Field | Type | Description |
7244
- |-------|---------------|----------------------------------------------------------------------------------|
8306
+ | ----- | ------------- | -------------------------------------------------------------------------------- |
7245
8307
  | `fld` | `Array[String]` | List of package fields (up to 2) used to build the subfolder name. Field values are joined with `.`.<br/>Example: `["name", "id"]`. |
7246
8308
  | `inf` | `Bool` | If `true`, creates a `<ID>.info.json` sidecar file inside the folder containing package metadata.<br/>Default: `false`. |
7247
8309
  | `opt` | `Bool` | If `false` (default), all fields in `fld` are always used. If `true`, the first field is used unless the folder already exists.<br/>Default: `false`. |
@@ -7723,7 +8785,7 @@ For instructions, refer to section `find` for plugin `node`.
7723
8785
 
7724
8786
  ```shell
7725
8787
  admin analytics application_events
7726
- admin analytics files organization '' <id>
8788
+ admin analytics files organization '' <ID>
7727
8789
  admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive","limit":2}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
7728
8790
  admin analytics transfers users --once-only=yes
7729
8791
  admin application instance list
@@ -7731,8 +8793,8 @@ admin application instance list --query.aspera_app_type=files
7731
8793
  admin application instance list --query.organization_apps=true
7732
8794
  admin application membership list
7733
8795
  admin application types
7734
- admin ats access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws_aoc","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
7735
- admin ats access_key create --cloud=softlayer --region=my_region @: id=ak1ibmcloud secret=<SECRET> 'name="my test key"' storage.type=ibm-s3 storage.bucket=my_bucket storage.credentials.access_key_id=my_access_key storage.credentials.secret_access_key=my_secret_key storage.path=/
8796
+ admin ats access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws_aoc","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
8797
+ admin ats access_key create --cloud=softlayer --region=my_region @: id=ak1ibmcloud secret=<SECRET> 'name="my test key"' storage.type=ibm-s3 storage.bucket=my_bucket storage.credentials.access_key_id=<ACCESS_KEY> storage.credentials.secret_access_key=<SECRET_KEY> storage.path=/
7736
8798
  admin ats access_key delete ak1ibmcloud
7737
8799
  admin ats access_key list --fields=name,id
7738
8800
  admin ats access_key node ak1ibmcloud --secret=<SECRET> browse /
@@ -7745,10 +8807,10 @@ admin bearer_token --out.level=data --out.secrets=yes
7745
8807
  admin client list
7746
8808
  admin client_access_key list
7747
8809
  admin client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
7748
- admin client_registration_token delete <id>
8810
+ admin client_registration_token delete <ID>
7749
8811
  admin client_registration_token list
7750
8812
  admin configuration_policy list
7751
- admin configuration_policy show <id>
8813
+ admin configuration_policy show <ID>
7752
8814
  admin contact list
7753
8815
  admin dropbox list
7754
8816
  admin dropbox_membership list
@@ -7756,7 +8818,7 @@ admin group list
7756
8818
  admin group_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
7757
8819
  admin kms_profile list
7758
8820
  admin network_policy list
7759
- admin network_policy show <id>
8821
+ admin network_policy show <ID>
7760
8822
  admin node bearer_token %name:my_node_name user:all
7761
8823
  admin node do %name:my_node_name --secret=<AK_SECRET> browse /
7762
8824
  admin node do %name:my_node_name --secret=<AK_SECRET> browse /folder_sub --node-api.cache=false
@@ -7764,8 +8826,8 @@ admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder1
7764
8826
  admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder_sub
7765
8827
  admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder1
7766
8828
  admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder_sub
7767
- admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder_sub"}}'
7768
- admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete testsub1
8829
+ admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"test-sub-1","storage":{"path":"/folder_sub"}}'
8830
+ admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete test-sub-1
7769
8831
  admin node do %name:my_node_name --secret=<AK_SECRET> v3 events
7770
8832
  admin node do %name:my_node_name delete test_shared_folder
7771
8833
  admin node do %name:my_node_name mkdir test_shared_folder
@@ -7790,12 +8852,15 @@ admin user preferences %name:my_user_email show
7790
8852
  admin workspace dropbox %name:my_other_workspace list
7791
8853
  admin workspace list
7792
8854
  admin workspace shared_folder %name:my_other_workspace list
7793
- admin workspace shared_folder %name:my_other_workspace member <id> list
8855
+ admin workspace shared_folder %name:my_other_workspace member <ID> list
8856
+ admin workspace shared_folder %name:my_other_workspace node <ID> browse /
7794
8857
  admin workspace_membership list
7795
8858
  admin workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
7796
- automation workflow action <id> create @: name=toto
8859
+ automation workflow action <ID> create @: name=toto
7797
8860
  automation workflow create @: name=test_workflow
7798
- automation workflow delete <id>
8861
+ automation workflow delete <ID>
8862
+ automation workflow details <ID>
8863
+ automation workflow export <ID>
7799
8864
  automation workflow list
7800
8865
  automation workflow list --query.show_org_workflows=@val:true
7801
8866
  automation workflow list --select.name=test_workflow --fields=id
@@ -7803,65 +8868,66 @@ bearer_token --out.level=data --out.secrets=yes
7803
8868
  files bearer /
7804
8869
  files bearer_token_node / --cache-tokens=no
7805
8870
  files browse /
7806
- files browse / --url=my_private_link_shared_folder
7807
- files browse / --url=my_public_link_folder_no_pass
7808
- files browse / --url=my_public_link_folder_with_pass --password=<PUBLIC_LINK_FOLDER_PASSWORD>
8871
+ files browse / --url=<PRIVATE_LINK_SHARED_FOLDER>
8872
+ files browse / --url=<PUBLIC_LINK_FOLDER_NO_PASS>
8873
+ files browse / --url=<PUBLIC_LINK_FOLDER_WITH_PASS> --password=<PUBLIC_LINK_FOLDER_PASSWORD>
7809
8874
  files browse my_remote_file
7810
8875
  files browse my_remote_folder
7811
8876
  files browse my_remote_folder/
7812
- files cat testdst/test_file.bin
7813
- files delete /testsrc
7814
- files download --to-folder=. testdst/test_file.bin testdst/test_file.bin
7815
- files download --transfer.agent=connect testdst/test_file.bin
7816
- files download --transfer.agent=desktop testdst/test_file.bin
8877
+ files cat test-dst/test_file.bin
8878
+ files delete /test-src
8879
+ files download --to-folder=. test-dst/test_file.bin test-dst/test_file.bin
8880
+ files download --transfer.agent=connect test-dst/test_file.bin
8881
+ files download --transfer.agent=desktop test-dst/test_file.bin
7817
8882
  files find /sample_video
7818
8883
  files find /sample_video '\.partial$'
7819
8884
  files find /sample_video @ruby:'->(f){f["type"].eql?("file")}'
7820
- files mkdir /testsrc
8885
+ files mkdir /test-src
7821
8886
  files modify /some_folder @: mount_point=false
7822
8887
  files permission my_test_folder list
7823
- files rename /some_folder testdst
7824
- files short_link /testdst private create
7825
- files short_link /testdst private list
7826
- files short_link /testdst public create @: access_levels.0=mkdir access_levels.1=write --fields=id
7827
- files short_link /testdst public modify <aoc_short_link_pub_create> @: access_levels=edit
7828
- files show %id:<id>
8888
+ files rename /some_folder test-dst
8889
+ files short_link /test-dst private create
8890
+ files short_link /test-dst private list
8891
+ files short_link /test-dst public create @: access_levels.0=mkdir access_levels.1=write --fields=id
8892
+ files short_link /test-dst public modify <AOC_SHORT_LINK_PUB_CREATE> @: access_levels=edit
8893
+ files show %id:<ID>
7829
8894
  files show /
7830
- files show testdst/test_file.bin
8895
+ files show test-dst/test_file.bin
7831
8896
  files sync admin status /data/local_sync
7832
- files sync pull /testdst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
8897
+ files sync pull /test-dst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
7833
8898
  files thumbnail my_test_folder/video_file.mpg
7834
8899
  files thumbnail my_test_folder/video_file.mpg --query.text=true --query.double=true
7835
- files transfer push /testsrc --to-folder=/testdst test_file.bin
7836
- files upload --to-folder=/ test_file.bin --url=my_public_link_folder_no_pass
7837
- files upload --to-folder=/testsrc test_file.bin
7838
- files upload --to-folder=/testsrc test_file.bin test_file.bin
8900
+ files transfer push /test-src --to-folder=/test-dst test_file.bin
8901
+ files upload --to-folder=/ test_file.bin --url=<PUBLIC_LINK_FOLDER_NO_PASS>
8902
+ files upload --to-folder=/test-src test_file.bin
8903
+ files upload --to-folder=/test-src test_file.bin test_file.bin
7839
8904
  files v3 info
7840
8905
  gateway @: url=https://localhost:12347/aspera/faspex
7841
8906
  organization
7842
8907
  organization --format=image --fields=background_image_url --ui=text
7843
- organization --url=my_public_link_recv_from_aoc_user
7844
- packages browse <id> /
8908
+ organization --url=<PUBLIC_LINK_RECV_FROM_AOC_USER>
8909
+ packages browse <ID> /
7845
8910
  packages list
7846
8911
  packages list --query=@json:'{"dropbox_name":"my_shared_inbox_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
7847
- packages receive <id> --to-folder=.
7848
- packages receive <id> --to-folder=. /
8912
+ packages receive <ID> --to-folder=.
8913
+ packages receive <ID> --to-folder=. /
7849
8914
  packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --package-folder.fld.0=name --package-folder.fld.1=id --package-folder.opt=true
7850
8915
  packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --query=@json:'{"dropbox_name":"my_shared_inbox_name","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'
8916
+ packages receive ALL --url=<PUBLIC_LINK_RECV_FROM_AOC_USER> --to-folder=.
7851
8917
  packages receive INIT --once-only=yes --query.dropbox_name=my_shared_inbox_name
7852
8918
  packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' test_file.bin
7853
8919
  packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
7854
8920
  packages send --workspace=my_workspace_shared_inbox @json:'{"name":"package title","recipients":["my_shared_inbox_name"]}' test_file.bin
7855
- packages send @: 'name=package title' END test_file.bin --url=my_public_link_send_aoc_user --password=<PUBLIC_LINK_SEND_USE_PASS>
7856
- packages send @: 'name=package title' END test_file.bin --url=my_public_link_send_shared_inbox
8921
+ packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_AOC_USER> --password=<PUBLIC_LINK_SEND_USE_PASS>
8922
+ packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_SHARED_INBOX>
7857
8923
  packages send @: 'name=package title' recipients.0=my_username 'note=some notes' END test_file.bin
7858
8924
  packages send @json:'{"name":"package title","recipients":["my_email_external"]}' --new-user-option.package_contact=true test_file.bin
7859
8925
  packages shared_inboxes list
7860
8926
  packages shared_inboxes short_link public %name:my_shared_inbox_name create --fields=id
7861
- packages shared_inboxes short_link public %name:my_shared_inbox_name delete <aoc_shared_inbox_short_link_create>
8927
+ packages shared_inboxes short_link public %name:my_shared_inbox_name delete <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
7862
8928
  packages shared_inboxes short_link public %name:my_shared_inbox_name list
7863
- packages shared_inboxes short_link public %name:my_shared_inbox_name modify <aoc_shared_inbox_short_link_create> @: password=<PUBLIC_LINK_FOLDER_PASSWORD>
7864
- packages shared_inboxes short_link public %name:my_shared_inbox_name show <aoc_shared_inbox_short_link_create>
8929
+ packages shared_inboxes short_link public %name:my_shared_inbox_name modify <AOC_SHARED_INBOX_SHORT_LINK_CREATE> @: password=<PUBLIC_LINK_FOLDER_PASSWORD>
8930
+ packages shared_inboxes short_link public %name:my_shared_inbox_name show <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
7865
8931
  packages shared_inboxes show %name:my_shared_inbox_name
7866
8932
  packages show '%name:package title'
7867
8933
  remind --username=my_user_email --url=https://aoc.example.com/path
@@ -7925,7 +8991,7 @@ Then, to register the key by default for the `ats` plugin, create a preset.
7925
8991
  Execute:
7926
8992
 
7927
8993
  ```shell
7928
- ascli config preset update <PRESET_NAME> --ibm-api-key=<API_KEY>
8994
+ ascli config preset set <PRESET_NAME> @: ibm_api_key=<API_KEY>
7929
8995
  ```
7930
8996
 
7931
8997
  ```shell
@@ -7941,7 +9007,7 @@ aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
7941
9007
  ```
7942
9008
 
7943
9009
  ```shell
7944
- ascli config preset update <PRESET_NAME> --instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
9010
+ ascli config preset set <PRESET_NAME> @: instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
7945
9011
  ```
7946
9012
 
7947
9013
  ```shell
@@ -7958,7 +9024,7 @@ ascli ats api_key create --out.secrets=yes
7958
9024
  ```
7959
9025
 
7960
9026
  ```shell
7961
- ascli config preset update <PRESET_NAME> --ats-key=<ATS_KEY> --ats-secret=<ATS_SECRET>
9027
+ ascli config preset set <PRESET_NAME> @: ats_key=<ATS_KEY> ats_secret=<ATS_SECRET>
7962
9028
  ```
7963
9029
 
7964
9030
  ### ATS Access key creation parameters
@@ -8011,8 +9077,8 @@ The parameters provided to ATS for access key creation are the ones of [ATS API]
8011
9077
 
8012
9078
  ```shell
8013
9079
  access_key cluster ak2ibmcloud --secret=<SECRET>
8014
- access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
8015
- access_key create --cloud=softlayer --region=my_region @json:'{"id":"ak2ibmcloud","secret":"<SECRET>","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
9080
+ access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
9081
+ access_key create --cloud=softlayer --region=my_region @json:'{"id":"ak2ibmcloud","secret":"<SECRET>","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
8016
9082
  access_key delete ak2ibmcloud
8017
9083
  access_key entitlement ak2ibmcloud
8018
9084
  access_key list --fields=name,id
@@ -8059,7 +9125,7 @@ ascli server --url=ssh://hsts.example.com:33001 --username=john --ssh-keys=~/.ss
8059
9125
 
8060
9126
  ```shell
8061
9127
  browse /
8062
- browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<serv_key_path>
9128
+ browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<SERV_KEY_PATH>
8063
9129
  browse my_inside_folder/test_file.bin
8064
9130
  browse my_upload_folder/target_hot
8065
9131
  cp my_inside_folder/test_file.bin my_upload_folder/200KB.2
@@ -8084,6 +9150,7 @@ sync admin status /data/local_sync
8084
9150
  sync pull my_inside_folder --to-folder=/data/local_sync @: name=serv_sync_pull_conf
8085
9151
  sync pull my_inside_folder --to-folder=/data/local_sync @json:'{"name":"serv_sync_pull_conf","reset":true,"transport":{"target_rate":my_bps}}'
8086
9152
  upload 'faux:///test.bin?1k' --to-folder=my_upload_folder
9153
+ upload 'faux:///test.bin?1m' --to-folder=my_upload_folder --ts.target_rate=500m
8087
9154
  upload --sources=@ts --transfer.ascp_args=@list:,--file-list,file_list.txt --to-folder=my_inside_folder
8088
9155
  upload --sources=@ts --transfer.ascp_args=@list:,--file-pair-list,file_pair_list.txt
8089
9156
  upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer.agent=transferd
@@ -8169,6 +9236,23 @@ ascli server --ssh-options=@json:'{"use_agent": false}' ...
8169
9236
  If one of the SSH private keys is passphrase-protected, then option `passphrase` can be used.
8170
9237
  It is equivalent to setting both options `ssh_options.passphrase` and `ts.ssh_private_key_passphrase`.
8171
9238
 
9239
+ ### Analyze `ascp` logs of the server
9240
+
9241
+ Command `logs` analyzes the `ascp` log files of the server (`ascp` 4.0 and later), instead of those of the local machine: the files are read over the SSH connection of the plugin (same `url`, `username`, `password` or `ssh_keys`, and `ssh_options`), then analyzed like with [`config ascp logs`](#agent-direct-transfer). It has the same sub-commands (`summary`, `sessions`, `diagnostics`, `health`, `records`, ...) and the same option `ascp_logs`.
9242
+ Paths of the files on the server are mandatory: there is no default location, as it depends on the installation (e.g. a syslog file such as `/var/log/aspera.log` or `/var/log/messages`, or a file of the folder given with `ascp -L`).
9243
+ Files compressed with gzip (rotations) are supported. A folder is not read, give its files.
9244
+
9245
+ ```shell
9246
+ ascli server --url=ssh://<SERVER_ADDRESS>:33001 --username=root --ssh-keys=~/.ssh/id_rsa logs summary /var/log/aspera.log
9247
+ ascli server ... logs sessions /var/log/aspera.log /var/log/aspera.log-20261101.gz --select=@json:'{"status":"failed"}'
9248
+ ```
9249
+
9250
+ The user must be allowed to read the files (log files are often readable by `root` only), and the server shall provide a shell with `head` (and `stat`).
9251
+ The files are copied to a temporary folder, removed after the analysis.
9252
+ The size of the files is limited (total of 256 MB by default), to avoid reading huge logs in memory: the limit is the key `remote_max_size` (in bytes) of option `ascp_logs`, e.g. `--ascp-logs.remote_max_size=1000000000`.
9253
+ The modification date of each file is kept, as the year of syslog lines is deduced from it.
9254
+ Not available with `--url=local:` and `https`.
9255
+
8172
9256
  ### Other session channels for `server`
8173
9257
 
8174
9258
  URL schemes `local` and `https` are also supported (mainly for testing purposes).
@@ -8655,7 +9739,8 @@ ascli node -N --url=https://... --password="Bearer $(cat bearer.txt)" --root-id=
8655
9739
  ```shell
8656
9740
  --url=http://localhost:12348 --username=sim --password=<PASSWORD> browse / --fields=path --format=csv --select=@json:'{"basename":"test_file.bin"}'
8657
9741
  --url=http://localhost:12348 --username=sim --password=<PASSWORD> transfer list --fields=status
8658
- --url=https://tst.example.com/path --password 'Bearer <nd_bearer_token>' --root-id=<id> access_key do self browse /
9742
+ --url=https://node.example.com:9092 --username=user1 --password=<PASSWORD> --ui=text asperabrowser
9743
+ --url=https://tst.example.com/path --password 'Bearer <ND_BEARER_TOKEN>' --root-id=<ID> access_key do self browse /
8659
9744
  access_key create @json:'{"id":"my_username","secret":"<PASSWORD>","storage":{"type":"local","path":"/"}}'
8660
9745
  access_key delete my_username
8661
9746
  access_key do my_ak_name browse / --secret=<AK_SECRET>
@@ -8673,15 +9758,14 @@ access_key do my_ak_name node_info / --secret=<AK_SECRET>
8673
9758
  access_key do my_ak_name rename /tst_nd_ak test_nd_ak2 --secret=<AK_SECRET>
8674
9759
  access_key do my_ak_name show %id:1 --secret=<AK_SECRET>
8675
9760
  access_key do my_ak_name upload 'faux:///test_nd_ak3?100k' --node-api.standard_ports=false --secret=<AK_SECRET>
8676
- access_key do self permission %id:<id> create @json:'{"access_type":"user","access_id":"666"}'
9761
+ access_key do self permission %id:<ID> create @json:'{"access_type":"user","access_id":"666"}'
8677
9762
  access_key do self permission / delete 1
8678
9763
  access_key do self permission / modify 1 @: 'access_levels=@list: read list'
8679
9764
  access_key do self permission / show 1
8680
9765
  access_key list
8681
- access_key set_bearer_key self @file:my_private_key
9766
+ access_key set_bearer_key self @file:<PRIVATE_KEY_FILE>
8682
9767
  access_key show %id:self
8683
9768
  api_details
8684
- asperabrowser
8685
9769
  async bandwidth %name:my_sync_session_name
8686
9770
  async counters %name:my_sync_session_name
8687
9771
  async delete ALL
@@ -8730,12 +9814,12 @@ sync admin status /data/local_sync
8730
9814
  sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @: reset=true
8731
9815
  sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @json:'{"name":"my_sync_session_name","reset":true}'
8732
9816
  transfer bandwidth_average
8733
- transfer cancel <id>
9817
+ transfer cancel <ID>
8734
9818
  transfer list --query.active_only=true
8735
9819
  transfer list --query.reset=true --once-only=yes
8736
- transfer modify <id> @: target_rate_kbps=10000
9820
+ transfer modify <ID> @: target_rate_kbps=10000
8737
9821
  transfer sessions
8738
- transfer show <id>
9822
+ transfer show <ID>
8739
9823
  transport
8740
9824
  upload 'faux:///testfile1?1m' --to-folder=my_local_path
8741
9825
  upload --to-folder=my_upload_folder --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer.agent=node --transfer.url=https://node.example.com/path --transfer.username=my_username --transfer.password=<PASSWORD>
@@ -8767,7 +9851,7 @@ Identify the region and the endpoint URL will be `https://otlp-[region]-saas.ins
8767
9851
  For convenience, those parameters can be provided in a preset, for example, named `otel_default`.
8768
9852
 
8769
9853
  ```shell
8770
- ascli config preset initialize otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","key":"<KEY>","interval":1.1}'
9854
+ ascli config preset set otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","key":"<KEY>","interval":1.1}'
8771
9855
  ```
8772
9856
 
8773
9857
  Then it is invoked like this (assuming a default node is configured):
@@ -8797,13 +9881,13 @@ The emulator starts its own `transferd`, and stops it on exit.
8797
9881
  It takes an optional `Hash` argument with the following parameters:
8798
9882
 
8799
9883
  | Field | Type | Description |
8800
- |-------------------|---------|----------------------------------------------------------------------------------|
9884
+ | ----------------- | ------- | -------------------------------------------------------------------------------- |
8801
9885
  | `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
8802
9886
  | `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
8803
9887
  | `docroot` | `String` | Local folder of the node files. Paths of `/files/browse` and local paths of transfers (sources of `send`, destination of `receive`) are relative to it, and confined in it. Defaults to the current working directory.<br/>Example: `/data/aspera`. |
8804
9888
  | `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
9889
+ | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `<PASSWORD>`. |
8805
9890
  | `password_min_bits` | `Integer` | Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
8806
- | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `my_password`. |
8807
9891
  | `retention_sec` | `Integer` | Time in seconds a transfer stays in the list of transfers after it ended (completed, failed or canceled, and no more retried).<br/>Default: `86400`. |
8808
9892
  | `url` | `String` | Address and port the emulator listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
8809
9893
  | `username` | `String` | Username expected from clients in HTTP Basic authentication. Set together with `password`. When not set, requests are accepted without authentication. Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).<br/>Example: `node_user`. |
@@ -8822,7 +9906,7 @@ ascli node emulator @json:'{"url":"http://localhost:12348","username":"sim","pas
8822
9906
 
8823
9907
  Generate the password with `openssl rand -hex 32`.
8824
9908
  A weak password is refused at startup: its strength is estimated in bits, and shall be at least `password_min_bits`.
8825
- `username` and `password` are mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`): anyone reaching the emulator could send the files of the `docroot` to any host.
9909
+ `username` and `password` are mandatory when `url` is not a loopback address (see [Web service](#web-service)): anyone reaching the emulator could send the files of the `docroot` to any host.
8826
9910
 
8827
9911
  Then, in another terminal, use it as a node, for example, to list the files in `/data`:
8828
9912
 
@@ -8903,13 +9987,13 @@ Multiple applications detected:
8903
9987
  product> faspex5
8904
9988
  ```
8905
9989
 
8906
- When Faspex is detected, the wizard asks for the path to a private key.
9990
+ When Faspex is detected, the wizard asks for a private key (a value like `@file:<path>`).
8907
9991
  If you do not have a private key, leave that field blank, and one will be generated or a previously generated key will be used.
8908
9992
 
8909
9993
  ```text
8910
9994
  Using: Faspex at https://faspex5.example.com/aspera/faspex
8911
- Please provide the path to your private RSA key, or nothing to generate one:
8912
- option: key_path>
9995
+ Private RSA key, e.g. @file:<path> (leave empty to generate):
9996
+ option: private_key>
8913
9997
  Using existing key:
8914
9998
  /Users/someuser/.aspera/ascli/my_key
8915
9999
  ```
@@ -9004,7 +10088,7 @@ Typically, users create a preset so they don't have to enter these options each
9004
10088
  Example:
9005
10089
 
9006
10090
  ```shell
9007
- ascli config preset update <F5_PRESET> --auth=jwt --client-id=<CLIENT_ID> --client-secret=<SECRET> --username=<USERNAME> --private-key=@file:.../path/to/key.pem
10091
+ ascli config preset set <F5_PRESET> @: auth=jwt client_id=<CLIENT_ID> client_secret=<SECRET> username=<USERNAME> private_key=@file:.../path/to/key.pem
9008
10092
 
9009
10093
  ascli config preset set default faspex5 <F5_PRESET>
9010
10094
 
@@ -9019,9 +10103,9 @@ For web-based authentication, the administrator must create an **API client** in
9019
10103
  - Do not Activate JWT
9020
10104
  - Set **Redirect URI** to `https://127.0.0.1:8888`
9021
10105
  - Click **Create**
9022
- - Take note of the Client Id (and Client Secret, but not used in current version)
10106
+ - Take note of the Client Id, and of the Client Secret if HTTP basic authentication is enabled on the API client
9023
10107
 
9024
- The user will use the following options:
10108
+ The user will use the following options (`client_secret` only if HTTP basic authentication is enabled on the API client):
9025
10109
 
9026
10110
  ```text
9027
10111
  --auth=web
@@ -9030,6 +10114,9 @@ The user will use the following options:
9030
10114
  --redirect-uri=https://127.0.0.1:8888
9031
10115
  ```
9032
10116
 
10117
+ `ascli` uses PKCE (RFC 7636, method `S256`): the authorization code can be exchanged for a token only by the `ascli` process that requested it.
10118
+ Faspex checks it since version 5.0.16, earlier versions ignore it.
10119
+
9033
10120
  ### Faspex 5 public link authentication
9034
10121
 
9035
10122
  If all you have is a public link received by email or other, you can still do authorized actions with it.
@@ -9052,7 +10139,7 @@ For `boot` method: (will be removed in future)
9052
10139
  Use this token as password and use `--auth=boot`.
9053
10140
 
9054
10141
  ```shell
9055
- ascli config preset update f5boot --url=https://localhost/aspera/faspex --auth=boot --password=<TOKEN>
10142
+ ascli config preset set f5boot @: url=https://localhost/aspera/faspex auth=boot password=<TOKEN>
9056
10143
  ```
9057
10144
 
9058
10145
  ### Tested commands for `faspex5`
@@ -9102,33 +10189,36 @@ gateway @: url=https://localhost:12346/aspera/faspex
9102
10189
  health --url=https://f5.example.com/path
9103
10190
  invitation list
9104
10191
  invitations create @: email_address=aspera.user1+u@gmail.com
9105
- packages browse --url=my_public_link_recv_fr_user /
9106
- packages browse <id> --query.recursive=true
9107
- packages delete <id>
10192
+ packages browse --url=<PUBLIC_LINK_RECV_FR_USER> /
10193
+ packages browse <ID> --query.recursive=true
10194
+ packages delete <ID>
9108
10195
  packages list --box=ALL
9109
10196
  packages list --box=my_shared_box_name
9110
10197
  packages list --box=my_workgroup --group-type=workgroups
9111
10198
  packages list --box=outbox --fields=DEF,sender.email,recipients.0.recipient_type
9112
10199
  packages list --query=@json:'{"mailbox":"inbox","status":"completed"}'
9113
- packages receive --box=my_shared_box_name <id> --to-folder=.
9114
- packages receive --box=my_workgroup --group-type=workgroups <id> --to-folder=.
9115
- packages receive --url=my_public_link_recv_fr_user --to-folder=.
9116
- packages receive --url=my_public_link_recv_fr_user ALL --to-folder=.
9117
- packages receive <id> --to-folder=. --ts.content_protection_password=<PASSWORD>
9118
- packages receive <id> <f5_pack_first_file> --to-folder=. --ts.content_protection_password=<PASSWORD>
9119
- packages receive ALL --once-only=yes --to-folder=. --query.max=5
10200
+ packages receive --box=my_shared_box_name <ID> --to-folder=.
10201
+ packages receive --box=my_workgroup --group-type=workgroups <ID> --to-folder=.
10202
+ packages receive --url=<PUBLIC_LINK_RECV_FR_USER> --to-folder=.
10203
+ packages receive --url=<PUBLIC_LINK_RECV_FR_USER> ALL --to-folder=.
10204
+ packages receive <ID> --to-folder=. --ts.content_protection_password=<PASSWORD>
10205
+ packages receive <ID> <F5_PACK_FIRST_FILE> --to-folder=. --ts.content_protection_password=<PASSWORD>
10206
+ packages receive ALL --once-only=yes --to-folder=.
10207
+ packages receive ALL --once-only=yes --to-folder=. --query.max=5 --ts.content_protection_password=<PASSWORD>
9120
10208
  packages receive INIT --once-only=yes
9121
- packages send --url=my_public_link_send_shared_box @json:'{"title":"test title"}' test_file.bin
9122
- packages send --url=my_public_link_send_to_user @json:'{"title":"test title"}' test_file.bin
10209
+ packages send --url=<PUBLIC_LINK_SEND_SHARED_BOX> @json:'{"title":"test title"}' test_file.bin
10210
+ packages send --url=<PUBLIC_LINK_SEND_TO_USER> @json:'{"title":"test title"}' test_file.bin
9123
10211
  packages send @: 'title=for shared inbox' recipients.0=my_shared_box_name metadata.Options=Opt1 'metadata.TextInput=example text' END test_file.bin
10212
+ packages send @: 'title=test ear' recipients.0.name=my_username END test_file.bin --ts.content_protection=encrypt --ts.content_protection_password=<PASSWORD>
10213
+ packages send @: 'title=test recipient types' recipients.0=my_username recipient_types.0=user END test_file.bin
9124
10214
  packages send @: 'title=test title' recipients.0.name=my_username END test_file.bin --ts.content_protection_password=<PASSWORD>
9125
10215
  packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
9126
10216
  packages send @json:'{"title":"test_webhook_ascli","recipients":["my_shared_box_name"]}' 'faux:///test1?1m'
9127
- packages show --box=my_shared_box_name <id>
9128
- packages show --box=my_workgroup --group-type=workgroups <id>
9129
- packages show <id>
9130
- packages status <f5_pack_send_shared> @list:,failed,completed
9131
- packages status <id>
10217
+ packages show --box=my_shared_box_name <ID>
10218
+ packages show --box=my_workgroup --group-type=workgroups <ID>
10219
+ packages show <ID>
10220
+ packages status <F5_PACK_SEND_SHARED> @list:,failed,completed
10221
+ packages status <ID>
9132
10222
  postprocessing @: url=https://localhost:8553/asclihook script_folder=/path/to/scripts cert=.../localhost.p12 key=<PASSWORD>
9133
10223
  shared browse %name:my_shared_folder_name
9134
10224
  shared list
@@ -9533,15 +10623,15 @@ ascli faspex5 postprocessing
9533
10623
  An optional positional parameter can be provided as [Extended Value](#extended-value-syntax) `Hash`:
9534
10624
 
9535
10625
  | Field | Type | Description |
9536
- |-----------------------|-----------------------|----------------------------------------------------------------------------------|
10626
+ | --------------------- | --------------------- | -------------------------------------------------------------------------------- |
9537
10627
  | `allowed_ips` | `String, Array[String]` | IP address or network (CIDR, e.g. `10.89.0.0/24`), or list of them, allowed to call the listener. Requests from any other source IP are rejected with HTTP 403. When not set, no IP restriction is applied. This parameter or `secret_token` is required when `url` is not a local address. |
9538
10628
  | `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
9539
10629
  | `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
9540
10630
  | `fail_on_error` | `Bool` | When `true`, return HTTP 500 if the script exits with a non-zero status code. When `false` (default), the exit code is reported in the response body but HTTP 200 is returned.<br/>Default: `false`. |
9541
10631
  | `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
9542
10632
  | `script_folder` | `String` | Folder containing the post-processing scripts. The URL path (after the base path) is appended to this folder to locate the script to execute.<br/>Default: `.`.<br/>Example: `/opt/faspex/scripts`. |
9543
- | `secret_token_min_bits` | `Integer` | Minimum estimated strength of `secret_token`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random token of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
9544
10633
  | `secret_token` | `String` | Shared secret for webhook authentication. When set, every incoming request must include `?token=<value>` in the URL; requests without the correct token are rejected with HTTP 401. Configure the Faspex webhook URL as `http://host:port/path/script.sh?token=<value>`. This parameter or `allowed_ips` is required when `url` is not a local address. Generate it with `openssl rand -hex 32`: a weak token is refused (see `secret_token_min_bits`). |
10634
+ | `secret_token_min_bits` | `Integer` | Minimum estimated strength of `secret_token`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random token of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
9545
10635
  | `timeout_seconds` | `Integer` | Maximum time in seconds to wait for the script to complete before killing it.<br/>Default: `60`. |
9546
10636
  | `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
9547
10637
 
@@ -9574,8 +10664,8 @@ Instead, one can specify the **IP address of the host** or `host.containers.inte
9574
10664
  So, `ascli` shall listen on an address reachable from the containers: the IP address of the host, or `0.0.0.0` for all interfaces.
9575
10665
 
9576
10666
  > [!NOTE]
9577
- > **Security**: by default the listener binds to loopback (`localhost`) and is not reachable from outside the host.
9578
- > When `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`), at least one of the following protections is required:
10667
+ > **Security**: by default the listener binds to loopback (`localhost`) and is not reachable from outside the host (see [Web service](#web-service)).
10668
+ > When `url` is not a loopback address, at least one of the following protections is required:
9579
10669
  >
9580
10670
  > - **`secret_token`**: include the token in the Faspex webhook URL: `http://host:8080/processing/script1.sh?token=<TOKEN>`. Requests without the correct token are rejected with HTTP 401.
9581
10671
  > - **`allowed_ips`**: restrict the listener to the known Faspex container IPs or network, e.g. `@json:'{"allowed_ips":["192.168.1.10","10.89.0.0/24"]}'`. Requests from other IPs are rejected with HTTP 403.
@@ -9608,15 +10698,17 @@ For legacy Faspex client applications that use the `send` API (only) of Faspex v
9608
10698
  It takes an optional `Hash` argument:
9609
10699
 
9610
10700
  | Field | Type | Description |
9611
- |-------------------|---------|----------------------------------------------------------------------------------|
10701
+ | ----------------- | ------- | -------------------------------------------------------------------------------- |
9612
10702
  | `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
9613
10703
  | `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
9614
10704
  | `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
10705
+ | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `<PASSWORD>`. |
9615
10706
  | `password_min_bits` | `Integer` | Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
9616
- | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `my_password`. |
9617
10707
  | `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
9618
10708
  | `username` | `String` | Username expected from clients in HTTP Basic authentication. Set together with `password`. When not set, requests are accepted without authentication. Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).<br/>Example: `fx4_user`. |
9619
10709
 
10710
+ For details on `url` and HTTPS (`cert`, `key`, `chain`), see [Web service](#web-service).
10711
+
9620
10712
  Example:
9621
10713
 
9622
10714
  ```shell
@@ -9626,7 +10718,7 @@ ascli faspex5 gateway @json:'{"url":"https://localhost:12345/aspera/faspex","use
9626
10718
  Clients authenticate with HTTP Basic, as on Faspex 4, with the `username` and `password` of the gateway.
9627
10719
  Generate the password with `openssl rand -hex 32`.
9628
10720
  A weak password is refused at startup: its strength is estimated in bits, and shall be at least `password_min_bits`.
9629
- `username` and `password` are mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`): anyone reaching the gateway could send packages to anyone, as the Faspex 5 user.
10721
+ `username` and `password` are mandatory when `url` is not a loopback address (see [Web service](#web-service)): anyone reaching the gateway could send packages to anyone, as the Faspex 5 user.
9630
10722
  When they are not set, requests are accepted without authentication.
9631
10723
 
9632
10724
  There are many limitations:
@@ -9704,6 +10796,45 @@ ascli shares admin user all share_permissions %username:john@example.com list --
9704
10796
  done
9705
10797
  ```
9706
10798
 
10799
+ ### Authentication of SAML users
10800
+
10801
+ By default, `shares` authenticates with `username` and `password`.
10802
+ A user that has only a SAML identity (no local password) can authenticate with a web browser: `--auth=web`.
10803
+
10804
+ ```shell
10805
+ ascli shares --url=https://shares.example.com --auth=web files browse /
10806
+ ```
10807
+
10808
+ Option `ui.web_auth` selects how the result of the login is received (see [Web login flow](#web-login-flow)):
10809
+
10810
+ - `port` (default): automatic when the browser runs on the same system as `ascli`.
10811
+ `ascli` listens on a local port (`--redirect-uri`, default: `http://localhost:12345`), opens the SAML login page of Shares (`/auth/saml`) in the browser with this URL in `RelayState`, and receives the OAuth tokens there.
10812
+ The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
10813
+ - `paste`: the browser may run on another system than `ascli` (for example, `ascli` runs on a server accessed with SSH), without tunnel.
10814
+ No local port is opened and `--redirect-uri` is not used.
10815
+ `ascli` generates a random `state` and opens the SAML login page with `RelayState` `aspera://device-code?state=<state>`.
10816
+ After login, Shares displays a code (a long text of letters, digits, `-` and `_`), and tells how long the code and the session token are valid. The user copies the code and pastes it in the prompt of `ascli` ([hidden](#hidden-input), as the code contains a token).
10817
+ The mark of the prompt becomes `✓` if the code is valid, else `✗`. A code that is not valid is asked again.
10818
+ If standard input is not a terminal, the code is read from it.
10819
+ `ascli` checks that the `state` of the code is the one it generated.
10820
+ The code is valid for **15 to 30 minutes** after its display: it is encrypted with a key derived from the `state` and from the current time in slots of 15 minutes (the previous and the next slot are also accepted).
10821
+ So the clocks of the Shares server and of the system that runs `ascli` shall be correct (less than 15 minutes apart), and the code shall be pasted soon after the login, otherwise `ascli` reports an expired code or a wrong clock, and the login shall be done again.
10822
+ The code is also protected against typing errors and modification.
10823
+
10824
+ The token is saved, and renewed with its refresh token: the browser is opened again only if this fails.
10825
+ Shares gives a token and a refresh token that both expire after 24 hours: then a new login is needed, unless the token is refreshed before (see `token_refresh_max_age` in [HTTP socket parameters](#http-socket-parameters)).
10826
+ Option `username` is optional: with it, the token is saved for this user.
10827
+
10828
+ > [!IMPORTANT]
10829
+ > Shares does not have the OAuth authorization code grant: both ways require a specific patch of Shares, which returns the tokens when `RelayState` is a loopback URL (`port`) or `aspera://device-code?state=<state>` (`paste`).
10830
+ > The patch is the file [`docs/shares/zz_saml_cli_relay_state.rb`](shares/zz_saml_cli_relay_state.rb) of the GitHub repository.
10831
+ > It is temporary code, provided until an equivalent function is officially released in Shares.
10832
+ > It modifies no file of Shares: to install it, copy it to `<shares_rails_root>/config/initializers/` on the Shares server and restart Shares; to remove it, delete the file and restart Shares.
10833
+ > With a Shares without the patch, `ascli` reports that no token was received.
10834
+ > This feature works only with this patch: it is not a standard function of Shares, and it has not been validated on a released version of Shares yet.
10835
+ > It may change with the final implementation in Shares: the `RelayState` values, the format of the code (and so its validity and its encryption) and the returned fields can differ, and `ascli` will then be adapted. Do not rely on the current format outside of `ascli`.
10836
+ > The tokens given by Shares go through the browser (in the URL, or in the code): `ascli` immediately exchanges the refresh token for a new token, so that the tokens that were visible are not valid any more.
10837
+
9707
10838
  ### Tested commands for `shares`
9708
10839
 
9709
10840
  > [!NOTE]
@@ -9737,7 +10868,7 @@ files download --to-folder=. my_share_folder/test_file.bin my_share_folder/test_
9737
10868
  files mkdir my_share_folder/new_folder
9738
10869
  files sync push /data/local_sync --to-folder=my_share_folder/synctst
9739
10870
  files sync push /data/local_sync --to-folder=my_share_folder/synctst @: reset=true
9740
- files upload 'faux:///testfile?1m' --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
10871
+ files upload 'faux:///test-file?1m' --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
9741
10872
  files upload --to-folder=my_share_folder test_file.bin
9742
10873
  files upload --to-folder=my_share_folder test_file.bin --transfer.agent=httpgw --transfer.url=https://tst.example.com/path
9743
10874
  files upload send_folder --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
@@ -9767,40 +10898,41 @@ In addition, it is possible to place a single `query` parameter in the request t
9767
10898
  endpoint list
9768
10899
  health
9769
10900
  ssh_key list
9770
- transfer current files <id>
10901
+ transfer current files <ID>
9771
10902
  transfer current list --query.filter='(transfer_name contain aoc)'
9772
10903
  transfer current list --query=@json:'{"filter1":"transfer_name","comp1":"contain","val1":"aoc"}'
9773
- transfer current show <id>
10904
+ transfer current show <ID>
9774
10905
  transfer smart list
9775
- transfer smart sub my_smart_id @: source.paths.0=my_smart_file source_type=user_selected
10906
+ transfer smart sub <SMART_ID> @: source.paths.0=my_smart_file source_type=user_selected
9776
10907
  ```
9777
10908
 
9778
10909
  ## Plugin: `orchestrator`: IBM Aspera Orchestrator
9779
10910
 
9780
- To write workflow files without the designer, refer to the [Workflow Authoring Guide](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/workflow-authoring-guide.md): file format, graph, execution, examples and REST API.
10911
+ To write workflow files without the designer, refer to the [Aspera Orchestrator Development Guide](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/orchestrator-development-guide.md): file format, graph, execution, examples and REST API.
9781
10912
 
9782
- Command `workflows development` displays the documentation for workflow development, read from GitHub: this guide (`authoring`), or the [Action Template Reference](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/action-template-reference.md) (`templates`).
9783
- With `toc`, it lists the sections of the document, and with the anchor of a section, it displays only that section.
10913
+ Command `workflows development` gives access to the documentation for workflow development, read from GitHub.
10914
+ Without argument, it lists the documents: the guide (`guide`), the [Action Template Reference](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/action-template-reference.md) (`templates`) and the Plugin Manual (`manual`).
10915
+ After the name of a document: `toc` lists its sections, `full` displays the whole document, and `section <anchor>` displays only one section: the guide and the manual are large, use `toc` first.
9784
10916
  It does not require access to Orchestrator.
9785
10917
  The [MCP server](#plugin-mcp-model-context-protocol-server) instructs AI assistants to read it before writing or modifying a workflow.
9786
10918
 
9787
10919
  ```shell
9788
- ascli orchestrator workflows development authoring toc
9789
- ascli orchestrator workflows development templates customruby
10920
+ ascli orchestrator workflows development guide toc
10921
+ ascli orchestrator workflows development templates section customruby
9790
10922
  ```
9791
10923
 
9792
- Command `plugins spec` displays the specifications of action plugins, read from GitHub: [plugins.yml](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/plugins.yml).
10924
+ Commands `plugins spec` display the specifications of action plugins, read from GitHub: [plugins.yml](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/plugins.yml).
9793
10925
  For each plugin: template attributes (label, allowed values, defaults), and inputs and outputs of its steps, with the template settings they depend on.
9794
- The fields are described in section [Plugin specifications](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/workflow-authoring-guide.md#plugin-specifications) of the guide.
9795
- Without argument, it lists the plugins.
9796
- With a plugin name (class name, case insensitive), it displays its specification, or one section: `attributes`, `inputs` or `outputs`.
10926
+ The fields are described in section [Plugin specifications](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/orchestrator-development-guide.md#plugin-specifications) of the guide.
10927
+ `toc` lists the plugins, with the anchor of their section in the Plugin Manual (`manual_anchor`, for `workflows development manual section`).
10928
+ `show` with a plugin name (class name, case insensitive) displays its specification, or one section: `attributes`, `inputs` or `outputs`.
9797
10929
  It does not require access to Orchestrator.
9798
10930
  Option `plugin_specs` gives another URL or path of the file, for example for another version of Orchestrator.
9799
10931
 
9800
10932
  ```shell
9801
- ascli orchestrator plugins spec --select=@json:'{"category":"Triggers"}'
9802
- ascli orchestrator plugins spec AmazonS3Operation --format=yaml
9803
- ascli orchestrator plugins spec ascpclient inputs
10933
+ ascli orchestrator plugins spec toc --select=@json:'{"category":"Triggers"}'
10934
+ ascli orchestrator plugins spec show AmazonS3Operation --format=yaml
10935
+ ascli orchestrator plugins spec show ascpclient inputs
9804
10936
  ```
9805
10937
 
9806
10938
  ### Authentication
@@ -9811,9 +10943,9 @@ The Orchestrator plugin supports different credentials and authentication styles
9811
10943
  - `--auth_style=token` (default): Exchanges credentials for a JWT Bearer token via `/api/login`.
9812
10944
  - `--auth_style=basic`: Standard HTTP Basic Authentication.
9813
10945
  - `--auth_style=query`: Passes credentials in URL query parameters (`?login=...&password=...`).
9814
- - **API Key** (`--apikey`):
10946
+ - **Username / API Key** (`--username` and `--apikey`): the API key is the one of the user, so the user name is required.
9815
10947
  - `--auth_style=token` (default): Exchanges the API key for a JWT Bearer token via `/api/login`.
9816
- - `--auth_style=query`: Passes the API key in URL query parameter (`?apikey=...`).
10948
+ - `--auth_style=query`: Passes the API key in URL query parameters (`?login=...&api_key=...`).
9817
10949
 
9818
10950
  ### Start a workflow
9819
10951
 
@@ -9888,6 +11020,7 @@ ascli orchestrator workflows check_import my_workflow.yml
9888
11020
  ```
9889
11021
 
9890
11022
  It displays one line per issue, or `no problem found`.
11023
+ The file is read as `@file:`: at [Security Level](#security-level) `medium`, only in `allowed_paths`, and not at level `high`.
9891
11024
  An issue has these fields:
9892
11025
 
9893
11026
  | Field | Description |
@@ -9900,7 +11033,9 @@ An issue has these fields:
9900
11033
 
9901
11034
  Checked: format of the file (YAML, number of elements, plain format layout), attributes, `error_free`, action template keys, XML of the graph, `Start`, `End`, `Fail` and `Error` nodes, unique step names, step template, prerequisites, `Synch_factor`, steps that have no output or no prerequisite, references to outputs and parameters.
9902
11035
 
9903
- With the specifications of plugins (see `plugins spec`), it also checks action templates and the inputs of steps, for the settings of each template:
11036
+ A package (`.wkf`) whose files exceed 256 MiB once decompressed is not checked: it is reported as an issue (`package.too_large`).
11037
+
11038
+ With the specifications of plugins (see `plugins spec show`), it also checks action templates and the inputs of steps, for the settings of each template:
9904
11039
 
9905
11040
  - plugin class name, attributes of the template, and their values (type, allowed values),
9906
11041
  - required inputs not mapped (`step.input_missing`),
@@ -9946,39 +11081,45 @@ Orchestrator does not refuse an incomplete resolution: `workflows import_with_co
9946
11081
  ```shell
9947
11082
  --auth_style=query workflow list
9948
11083
  --auth_style=token workflow list
11084
+ alerts list
9949
11085
  health
9950
11086
  info
9951
11087
  journal files journal --query=@json:'{"details":"false"}'
9952
11088
  monitors list node
9953
11089
  monitors snapshot
9954
11090
  plugins list
9955
- plugins spec --select=@json:'{"category":"Triggers"}'
9956
- plugins spec AmazonS3Operation --format=yaml
9957
- plugins spec ascpclient inputs
11091
+ plugins spec show AmazonS3Operation --format=yaml
11092
+ plugins spec show ascpclient inputs
11093
+ plugins spec toc --select=@json:'{"category":"Triggers"}'
11094
+ portlets list
9958
11095
  processes
9959
11096
  queues list
11097
+ queues stats
11098
+ tasks list
9960
11099
  workflow check_import orch_wf_check.yml
9961
- workflow details my_workflow_id
9962
- workflow export my_workflow_id
9963
- workflow inputs my_workflow_id
11100
+ workflow details <WORKFLOW_ID>
11101
+ workflow export <WORKFLOW_ID>
11102
+ workflow inputs <WORKFLOW_ID>
9964
11103
  workflow list
9965
- workflow outputs my_workflow_id
9966
- workflow start my_sleep_workflow_id --fields=work_order.id
9967
- workflow start my_workflow_id @: 'Param=world !'
9968
- workflow start my_workflow_id @: 'Param=world !' END @: step=ResultStep variable=Complete_status_message
11104
+ workflow outputs <WORKFLOW_ID>
11105
+ workflow start <SLEEP_WORKFLOW_ID> --fields=work_order.id
11106
+ workflow start <WORKFLOW_ID> @: 'Param=world !'
11107
+ workflow start <WORKFLOW_ID> @: 'Param=world !' END @: step=ResultStep variable=Complete_status_message
11108
+ workflow status <WORKFLOW_ID>
9969
11109
  workflow status ALL
9970
- workflow status my_workflow_id
9971
- workflow workorders my_workflow_id
9972
- workflow workorders my_workflow_id --fields=id --query.max_results=1
9973
- workflows development authoring toc
9974
- workflows development templates customruby
9975
- workorder cancel <id>
9976
- workorder output <id>
9977
- workorder reset <id>
9978
- workorder status <id>
9979
- workorder status <orch_wf_start_sleep> --fields=status_details
9980
- workstep cancel <id>
9981
- workstep status <id>
11110
+ workflow workorders <WORKFLOW_ID>
11111
+ workflow workorders <WORKFLOW_ID> --fields=id --query.max_results=1
11112
+ workflows development guide toc
11113
+ workflows development templates section customruby
11114
+ workorder cancel <ID>
11115
+ workorder output <ID>
11116
+ workorder reset <ID>
11117
+ workorder status <ID>
11118
+ workorders stats
11119
+ workorders worksteps <ORCH_WF_START_SLEEP> --select.status='In Progress' --fields=id
11120
+ worksteps cancel <ID>
11121
+ worksteps stats
11122
+ worksteps status <ID>
9982
11123
  ```
9983
11124
 
9984
11125
  ## Plugin: `cos`: IBM Cloud Object Storage
@@ -10010,7 +11151,7 @@ If you already have these parameters, provide the following options to `ascli`:
10010
11151
  Example: Create a Default Configuration
10011
11152
 
10012
11153
  ```shell
10013
- ascli config preset update <COS_PRESET_NAME> --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=<API_KEY> --crn=<CRN>
11154
+ ascli config preset set <COS_PRESET_NAME> @: bucket=mybucket endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud apikey=<API_KEY> crn=<CRN>
10014
11155
  ascli config preset set default cos <COS_PRESET_NAME>
10015
11156
  ```
10016
11157
 
@@ -10080,7 +11221,7 @@ The required options for this method are:
10080
11221
  Example: Create a Default Configuration
10081
11222
 
10082
11223
  ```shell
10083
- ascli config preset update <COS_PRESET_NAME> --bucket=mybucket --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
11224
+ ascli config preset set <COS_PRESET_NAME> @: bucket=mybucket service_credentials=@val:@json:@file:~/service_creds.json region=us-south
10084
11225
  ascli config preset set default cos <COS_PRESET_NAME>
10085
11226
  ```
10086
11227
 
@@ -10104,8 +11245,8 @@ ascli cos node upload 'faux:///sample1G?1g'
10104
11245
 
10105
11246
  ```shell
10106
11247
  node download test_file.bin --to-folder=.
10107
- node info --bucket=my_bucket --endpoint=my_endpoint --apikey=my_api_key --crn=my_resource_instance_id
10108
- node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:my_cos_svc_cred
11248
+ node info --bucket=my_bucket --endpoint=my_endpoint --apikey=<API_KEY> --crn=<RESOURCE_INSTANCE_ID>
11249
+ node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:<COS_SVC_CRED_FILE>
10109
11250
  node info --log-level=trace2
10110
11251
  node upload test_file.bin
10111
11252
  ```
@@ -10122,6 +11263,47 @@ health
10122
11263
  info
10123
11264
  ```
10124
11265
 
11266
+ ## Plugin: `transferd`: Transfer Daemon
11267
+
11268
+ Plugin `transferd` installs the IBM Aspera Transfer Daemon (`transferd`, which includes `ascp`) and runs it as a system service.
11269
+ See [Installing `ascp` through `transferd`](#installing-ascp-through-transferd) and [Transfer Daemon as a system service](#transfer-daemon-as-a-system-service).
11270
+
11271
+ The plugin also has client commands for a running daemon (for example one installed with `transferd service install`):
11272
+
11273
+ | Command | Action |
11274
+ |---------------------------------|---------------------------------------------------------------------|
11275
+ | `info` | Version of the API and information on the instance of the daemon. |
11276
+ | `transfers show <transfer_id>` | Status of a transfer: the daemon keeps it for some time after its end. |
11277
+ | `transfers cancel <transfer_id>`| Stop a transfer. |
11278
+
11279
+ They use the options `url` (mandatory, endpoint of the daemon, e.g. `127.0.0.1:55002`), `api_key` (if the daemon enables `authentication`) and `ca_file` (if the daemon enables `tls`).
11280
+ If a key is not given, it is taken from the same key of the option `--transfer`, when its agent is `transferd` (e.g. a preset used for transfers).
11281
+ The options of the plugin have priority.
11282
+ The daemon has no call to list the transfers.
11283
+ These commands require the gem `grpc`: it is loaded only when one of them runs, so that the other commands do not need it.
11284
+ If it is missing: `gem install grpc`.
11285
+
11286
+ ```bash
11287
+ ascli transferd info --url=127.0.0.1:55002 --api-key=@vault:transferd.api_key
11288
+ ```
11289
+
11290
+ > [!NOTE]
11291
+ > Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
11292
+
11293
+ ### Tested commands for `transferd`
11294
+
11295
+ > [!NOTE]
11296
+ > Add `ascli transferd` in front of the following commands:
11297
+
11298
+ ```shell
11299
+ install
11300
+ install --sdk-folder=sdk_test_dir
11301
+ install 1.1.3
11302
+ list
11303
+ service configure --dry-run=yes @json:'{"service":{"user":"aspweb"},"config":{"port":55002}}'
11304
+ service spec
11305
+ ```
11306
+
10125
11307
  ## Plugin: `faspio`: Faspio Gateway
10126
11308
 
10127
11309
  IBM Aspera faspio Gateway is a high-performance proxy that bridges traditional TCP/UDP applications with the Aspera FASP protocol, enabling secure, ultra-fast transfers over any network, even with high latency or packet loss.
@@ -10135,7 +11317,7 @@ Using `ascli`, you can remotely create and manage bridges on faspio Gateway, sim
10135
11317
 
10136
11318
  ```shell
10137
11319
  bridges create @json:'{"name":"test1","local":{"protocol":"tcp","tls_enabled":false,"port":"3000","bind_address":"127.0.0.1"},"forward":{"protocol":"fasp","tls_enabled":false,"port":"3994","bind_address":"127.0.0.1","host":["10.0.0.1"]}}'
10138
- bridges delete --bulk=yes @json:<faspio_bclean_list>
11320
+ bridges delete --bulk=yes @json:<FASPIO_BCLEAN_LIST>
10139
11321
  bridges list
10140
11322
  bridges show 1
10141
11323
  health
@@ -10338,7 +11520,7 @@ For example:
10338
11520
  ```shell
10339
11521
  su -s /bin/bash - xfer
10340
11522
 
10341
- ascli config preset update <PREVIEW_PRESET_NAME> --url=https://localhost:9092 --username=<ACCESS_KEY> --password=<SECRET> --skip-types=office --lock-port=12346
11523
+ ascli config preset set <PREVIEW_PRESET_NAME> @: url=https://localhost:9092 username=<ACCESS_KEY> password=<SECRET> skip_types=office lock_port=12346
10342
11524
 
10343
11525
  ascli config preset set default preview <PREVIEW_PRESET_NAME>
10344
11526
  ```
@@ -10359,7 +11541,7 @@ This shall list the contents of the storage root of the access key.
10359
11541
  When generating preview files, the following options can be modified on command line (or in a preset):
10360
11542
 
10361
11543
  | Field | Type | Description |
10362
- |---------------------|---------|----------------------------------------------------------------------------------|
11544
+ | ------------------- | ------------ | -------------------------------------------------------------------------------- |
10363
11545
  | `blend_fps` | `Integer` | MP4 video preview (`blend`): frames per second.<br/>Default: `15`. |
10364
11546
  | `blend_keyframes` | `Integer` | MP4 video preview (`blend`): number of key frames.<br/>Default: `30`. |
10365
11547
  | `blend_pauseframes` | `Integer` | MP4 video preview (`blend`): number of pause frames (repetitions of each key frame).<br/>Default: `3`. |
@@ -10367,17 +11549,17 @@ When generating preview files, the following options can be modified on command
10367
11549
  | `clips_count` | `Integer` | MP4 video preview (`clips`): number of clips.<br/>Default: `5`. |
10368
11550
  | `clips_length` | `Integer` | Video: length (in seconds) of each clip of MP4 video preview (`clips`), and of `animated` PNG thumbnail.<br/>Default: `5`. |
10369
11551
  | `max_size` | `Integer` | Maximum size (in bytes) of a preview file: a warning is logged if exceeded.<br/>Default: `16777216`. |
10370
- | `office_conversion` | `String` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
11552
+ | `office_conversion` | `Enum[String]` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
11553
+ | `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
10371
11554
  | `reencode_ffmpeg.in` | `Array` | Input options. |
10372
11555
  | `reencode_ffmpeg.out` | `Array` | Output options. |
10373
- | `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
10374
11556
  | `thumb_img_size` | `Integer` | PNG thumbnail of image, PDF, office document or text: size (in pixels).<br/>Default: `800`. |
10375
11557
  | `thumb_text_font` | `String` | PNG thumbnail of text: font name, as listed by `magick identify -list font`.<br/>Default: `Courier`. |
10376
11558
  | `thumb_vid_fraction` | `Number` | PNG thumbnail of video (`fixed`): position of the snapshot, as a fraction of the video duration.<br/>Default: `0.1`. |
10377
11559
  | `thumb_vid_scale` | `String` | PNG thumbnail of video: frame size, as `ffmpeg` scale filter argument.<br/>Default: `-1:min(ih,100)`. |
10378
11560
  | `video_codec` | `String` | MP4 video preview (`reencode`): `ffmpeg` video codec, e.g. `libx264`, `h264_videotoolbox`, `h264_nvenc`. Default: first available H.264 encoder. |
10379
- | `video_conversion` | `String` | MP4 video preview: generation method. `reencode`: re-encode the beginning of the video, `blend`: key frames with transitions, `clips`: concatenation of short clips.<br/>Allowed values: `reencode`, `blend`, `clips`.<br/>Default: `reencode`. |
10380
- | `video_png_conv` | `String` | PNG thumbnail of video: generation method. `fixed`: single frame, `animated`: animated PNG.<br/>Allowed values: `fixed`, `animated`.<br/>Default: `fixed`. |
11561
+ | `video_conversion` | `Enum[String]` | MP4 video preview: generation method. `reencode`: re-encode the beginning of the video, `blend`: key frames with transitions, `clips`: concatenation of short clips.<br/>Allowed values: `reencode`, `blend`, `clips`.<br/>Default: `reencode`. |
11562
+ | `video_png_conv` | `Enum[String]` | PNG thumbnail of video: generation method. `fixed`: single frame, `animated`: animated PNG.<br/>Allowed values: `fixed`, `animated`.<br/>Default: `fixed`. |
10381
11563
  | `video_scale` | `String` | MP4 video preview: frame size, as `ffmpeg` scale filter argument.<br/>Default: `min(iw,360):-2`. |
10382
11564
  | `video_start_sec` | `Integer` | Video: start offset (in seconds) of MP4 video preview and of `animated` PNG thumbnail.<br/>Default: `10`. |
10383
11565
 
@@ -10539,10 +11721,6 @@ trevents --once-only=yes --skip-types=office --log-level=info
10539
11721
 
10540
11722
  ## Plugin: `mcp`: Model Context Protocol server
10541
11723
 
10542
- > [!WARNING]
10543
- > This plugin is **experimental**.
10544
- > The interface, options, and behavior may change in future releases without notice.
10545
-
10546
11724
  The `mcp` plugin starts a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes `ascli` to AI assistants and LLM-based tools.
10547
11725
  The server registers a single tool, `execute_ascli_command`, which executes any `ascli` command in-process and returns the result as text.
10548
11726
 
@@ -10613,6 +11791,8 @@ Keys of a transport are refused with the other transport.
10613
11791
  > [!NOTE]
10614
11792
  > `port` and `bind` are deprecated: use `url`, for example, `url=http://0.0.0.0:8080` instead of `port=8080 bind=0.0.0.0`.
10615
11793
 
11794
+ For the addresses the server listens on, and HTTPS, see [Web service](#web-service).
11795
+
10616
11796
  ### Security
10617
11797
 
10618
11798
  > [!WARNING]
@@ -10623,7 +11803,7 @@ With the `http` transport:
10623
11803
 
10624
11804
  - With `oauth`, the consent page asks for `auth_token` as access code, else anyone reaching the server could approve its own client.
10625
11805
  It shows where the authorization is sent (origin of `redirect_uri`): allow only if it is the expected AI client, for example `http://127.0.0.1:<port>`.
10626
- - For local-only deployments (hosts of `url` and `public_url` are loopback: `localhost`, `127.0.0.0/8`, `::1`), `auth_token` and `oauth` are optional but recommended.
11806
+ - For local-only deployments (hosts of `url` and `public_url` are loopback, see [Web service](#web-service)), `auth_token` and `oauth` are optional but recommended: on a host shared with other users, they can also reach the server.
10627
11807
  Without `auth_token`, the consent page only asks to click **Allow**.
10628
11808
  - `auth_token` and `oauth` can coexist: a request is accepted if it carries a valid static token **or** a valid OAuth access token.
10629
11809
  - A weak `auth_token` is refused at startup (see `auth_token_min_bits`): generate it with `openssl rand -hex 32`.
@@ -10636,9 +11816,12 @@ With both transports:
10636
11816
  - Extended value `@stdin:` is refused.
10637
11817
  - `@secret:` is entered by the user on a web page, see [Secrets entered in a web page](#secrets-entered-in-a-web-page).
10638
11818
  - Secrets are hidden in responses, also a value shorter than 8 characters as a word in a text (for example, a short password in an error message).
10639
- - The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:`, `@uri:`, and `@env:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
11819
+ - The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:` (also in the parameters of stores of option `vault`), `@uri:`, `@env:`, and `@zlib:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
10640
11820
  It applies to commands sent by the client, and to presets, because the client can modify presets.
10641
11821
  Commands sent by the client cannot change option `security`.
11822
+ Features that execute code, such as option `notify_template` or command `config plugins create`, plugins, and writing to a file chosen by the client (option `out.file`), are refused, see [Security Level](#security-level).
11823
+ Files can be written (for example by `config download`, or by a transfer that receives files) only in `writable_paths`, none by default: without it, the client cannot download files.
11824
+ It applies to files written on the system that runs the server: not to a transfer with agent `node` (`--transfer=node`), which writes on the node.
10642
11825
 
10643
11826
  To use another level, set option `security` when starting the server, for example:
10644
11827
 
@@ -10646,12 +11829,20 @@ To use another level, set option `security` when starting the server, for exampl
10646
11829
  ascli mcp server --security.level=medium --security.allowed_paths.0=$HOME/.aspera/ascli/my_private_key
10647
11830
  ```
10648
11831
 
11832
+ To let the client download files in a folder, keep the level `high` and give the folder:
11833
+
11834
+ ```shell
11835
+ ascli mcp server --security.writable_paths.0=$HOME/Downloads/ascli
11836
+ ```
11837
+
10649
11838
  > [!NOTE]
10650
11839
  > A level set by option also applies to the parameters of the `server` command: for example, `auth_token=@env:MCP_TOKEN` requires level `low`.
10651
11840
  > Without option `security`, the parameters of the `server` command are not restricted.
10652
11841
  >
10653
11842
  > A preset created by `aoc wizard` or `faspex5 wizard` reads the private key with `@file:`.
10654
11843
  > With level `high`, either store the key in the preset (`ascli config preset set <AOC_ORG> private_key @file:<PATH>`, without `@val:`), or use level `medium` with the key in `allowed_paths`.
11844
+ >
11845
+ > In the same way, a secret of a vault read from a file (for example, `token` of HashiCorp Vault: `@file:<path>`) requires level `medium` with the file in `allowed_paths`.
10655
11846
 
10656
11847
  ### HTTP endpoints
10657
11848
 
@@ -10873,7 +12064,7 @@ For [**IBM Bob**](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob), ad
10873
12064
  }
10874
12065
  ```
10875
12066
 
10876
- For other clients (Claude Desktop, VS Code, and so on), the configuration is identical.
12067
+ Most other clients (Claude Desktop, Cursor, and so on) use the same `mcpServers` format, VS Code uses `servers` (see below).
10877
12068
 
10878
12069
  ##### Claude Desktop `stdio`
10879
12070
 
@@ -10893,6 +12084,47 @@ Place this section in `mcpServers`:
10893
12084
  }
10894
12085
  ```
10895
12086
 
12087
+ ##### Claude Code `stdio`
12088
+
12089
+ For [**Claude Code**](https://code.claude.com/docs/en/mcp), register the server with the command line (option `--scope user` for all projects):
12090
+
12091
+ ```shell
12092
+ claude mcp add ascli -- ascli mcp server
12093
+ ```
12094
+
12095
+ In a shell, Claude Code can also execute `ascli` directly: install the agent skill instead (see [Leveraging AI Assistance](#leveraging-ai-assistance)).
12096
+
12097
+ ##### VS Code `stdio`
12098
+
12099
+ For **VS Code** (GitHub Copilot agent mode), add to `.vscode/mcp.json` in your workspace (or run command **MCP: Add Server**):
12100
+
12101
+ ```json
12102
+ {
12103
+ "servers": {
12104
+ "ascli": {
12105
+ "type": "stdio",
12106
+ "command": "ascli",
12107
+ "args": ["mcp", "server"]
12108
+ }
12109
+ }
12110
+ }
12111
+ ```
12112
+
12113
+ ##### Cursor `stdio`
12114
+
12115
+ For **Cursor**, add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global configuration):
12116
+
12117
+ ```json
12118
+ {
12119
+ "mcpServers": {
12120
+ "ascli": {
12121
+ "command": "ascli",
12122
+ "args": ["mcp", "server"]
12123
+ }
12124
+ }
12125
+ }
12126
+ ```
12127
+
10896
12128
  ##### Development mode for `stdio`
10897
12129
 
10898
12130
  If the `ascli` gem is not installed and you are running directly from the source tree, Ruby will not find the `lib/` directory automatically.
@@ -11131,10 +12363,10 @@ ascli config sync spec
11131
12363
  > The options listed in the **Description** column correspond to the equivalent parameters used by the low-level `async` command.
11132
12364
 
11133
12365
  | Field | Type | Description |
11134
- |------------------------------------------|---------------|----------------------------------------------------------------------------------|
12366
+ | ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
11135
12367
  | `ascp_dir` | `String` | Directory containing ascp executable to use. |
11136
12368
  | `assume_no_mods` | `Bool` | Assume that the directory structure has not been modified.<br/>Default: `false`.<br/>(`--assume-no-mods`) |
11137
- | `checksum` | `String` | Use the specified checksum type. Default is none on cloud storage.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`.<br/>Default: `sha1_sparse`.<br/>(`--checksum={enum}`)(-k) |
12369
+ | `checksum` | `Enum[String]` | Use the specified checksum type. Default is none on cloud storage.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`.<br/>Default: `sha1_sparse`.<br/>(`--checksum={enum}`)(-k) |
11138
12370
  | `clean_excluded` | `Bool` | Removes any existing entries in the snapshot database for excluded paths<br/>Default: `false`.<br/>(`--clean-excluded`) |
11139
12371
  | `cookie` | `String` | User-defined identification string.<br/>(`--cookie={string}`) |
11140
12372
  | `cooloff_max_seconds` | `Integer` | Wait up to the specified time for a file to stop changing before skipping synchronization of the file. 0 for disabled<br/>Default: `0`.<br/>(`--cooloff-max={integer}`) |
@@ -11143,19 +12375,20 @@ ascli config sync spec
11143
12375
  | `db_cache_size` | `Integer` | Specify DB cache size.<br/>Default: `16000`. |
11144
12376
  | `db_journal_off` | `Bool` | Turn off DB journal.<br/>Default: `false`. |
11145
12377
  | `db_sync_on` | `Bool` | Enable synchronous write in DB.<br/>Default: `false`. |
11146
- | `dedup` | `String` | Take the specified action when async detects duplicate files on the source.<br/>Allowed values: `copy`, `inode`, `hardlink`, `none`.<br/>Default: `none`.<br/>(`--dedup={enum}`) |
12378
+ | `dedup` | `Enum[String]` | Take the specified action when async detects duplicate files on the source.<br/>Allowed values: `copy`, `inode`, `hardlink`, `none`.<br/>Default: `none`.<br/>(`--dedup={enum}`) |
11147
12379
  | `delete_before` | `Bool` | Schedule deletes before transfers.<br/>Default: `false`.<br/>(`--delete-before`) |
11148
12380
  | `delete_delay` | `Bool` | Delay actual deletes until the end of the synchronization.<br/>Default: `false`.<br/>(`--delete-delay`) |
11149
- | `direction` | `String` | The direction of replication relative to the local.<br/>Allowed values: `bidi`, `pull`, `push`.<br/>Default: `push`.<br/>(`--direction={enum}`)(-K) |
12381
+ | `direction` | `Enum[String]` | The direction of replication relative to the local.<br/>Allowed values: `bidi`, `pull`, `push`.<br/>Default: `push`.<br/>(`--direction={enum}`)(-K) |
12382
+ | `exclude_dirs_older_than` | `Hash` | Don't scan directories with a recursive modified time older than absolute or async start time - relative_seconds |
11150
12383
  | `exclude_dirs_older_than.absolute` | `String` | UTC timestamp. Empty value for disabled. |
11151
12384
  | `exclude_dirs_older_than.relative_seconds` | `Integer` | Relative to async start time. `-1` for disabled.<br/>Default: `-1`. |
11152
- | `exclude_dirs_older_than` | `Hash` | Don't scan directories with a recursive modified time older than absolute or async start time - relative_seconds |
11153
- | `filters[].rule` | `String` | The rule for the filter.<br/>Required.<br/>Allowed values: `include`, `exclude`, `include_from`, `exclude_from`. |
11154
- | `filters[].value` | `String` | On include or exclude, the filter's pattern. On include_from or exclude_from, the path containing filter specifications<br/>Required. |
11155
12385
  | `filters` | `Array[Hash]` | The filters allow to further specify which files have to be excluded and included from the transfer list. Each filter is defined by a rule and a value. Order of filters matters |
12386
+ | `filters[].rule` | `Enum[String]` | The rule for the filter.<br/>Required.<br/>Allowed values: `include`, `exclude`, `include_from`, `exclude_from`. |
12387
+ | `filters[].value` | `String` | On include or exclude, the filter's pattern. On include_from or exclude_from, the path containing filter specifications<br/>Required. |
11156
12388
  | `ignore_delete` | `Bool` | Do not copy removals to the peer.<br/>Default: `false`.<br/>(`--ignore-delete`) |
11157
12389
  | `ignore_mode` | `Bool` | Source files that have had their mode changed after the initial transfer will not update the destination file mode.<br/>Default: `false`.<br/>(`--ignore-mode`) |
11158
12390
  | `ignore_remote_host_sync_name` | `Bool` | Do not check that the remote host being used for the current transfer matches the host used when the local database was created<br/>Default: `false`. |
12391
+ | `local` | `Hash` | Required. |
11159
12392
  | `local.pass` | `String` | Authenticate the local async with the specified password. |
11160
12393
  | `local.path` | `String` | The directory to be synchronized on the local host.<br/>Required.<br/>(`--local-dir={string}`)(-d) |
11161
12394
  | `local_apply_docroot` | `Bool` | Prepend the docroot to the directory on the local host.<br/>Default: `false`.<br/>(`--apply-local-docroot`) |
@@ -11167,26 +12400,25 @@ ascli config sync spec
11167
12400
  | `local_keep_dir` | `String` | Move deleted files into the specified directory on the local host.<br/>(`--keep-dir-local={string}`) |
11168
12401
  | `local_mount_signature` | `String` | Verify that the file system is mounted by the existence of this file on the local host.<br/>(`--local-mount-signature={string}`) |
11169
12402
  | `local_move_cache_timeout_seconds` | `Integer` | Delay in seconds before aborting moving a file from local cache to final destination. `-1` for disabled.<br/>Default: `-1`.<br/>(`--local-move-cache-timeout={integer}`) |
11170
- | `local_preserve_acls` | `String` | Preserve access control lists on the local host.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-acls={enum}`) |
11171
- | `local_preserve_xattrs` | `String` | Preserve extended attributes on the local.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-xattrs={enum}`) |
12403
+ | `local_preserve_acls` | `Enum[String]` | Preserve access control lists on the local host.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-acls={enum}`) |
12404
+ | `local_preserve_xattrs` | `Enum[String]` | Preserve extended attributes on the local.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-xattrs={enum}`) |
11172
12405
  | `local_scan_interval_milliseconds` | `Integer` | Enable periodic scans on the local host during a continuous sync. `-1` for disabled. On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`. A plain number is in seconds. Stored in milliseconds.<br/>Default: `-1`.<br/>(`--scan-interval={integer}`) |
11173
12406
  | `local_scan_threads` | `Integer` | Number of directory scanning threads on the local host. Value must be between 1 and 99<br/>Default: `1`.<br/>(`--scan-threads={integer}`) |
11174
12407
  | `local_stat_cache_size` | `Integer` | Set stat cache size on the local host. 0 for disabled.<br/>Default: `0`. |
11175
- | `local` | `Hash` | Required. |
11176
- | `log.level` | `String` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
12408
+ | `log` | `Hash` | |
12409
+ | `log.level` | `Enum[String]` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
11177
12410
  | `log.local_dir` | `String` | Use the specified logging directory on the local host.<br/>(`--alt-logdir={string}`)(-L) |
11178
12411
  | `log.remote_dir` | `String` | Use the specified logging directory on the remote host.<br/>(`--remote-logdir={string}`)(-R) |
11179
- | `log` | `Hash` | |
11180
12412
  | `manifest_path` | `String` | A directory path where ascp will create manifest TEXT files (passed to ascp as --file-manifest-path) |
11181
12413
  | `mirror` | `Bool` | Force the pulling side to be exactly like the pushing side, removing files on the destination that don't exist on the source and resending source files that don't have an exact match on the destination. Cannot be used in bi-directional mode.<br/>Default: `false`.<br/>(`--mirror`) |
11182
- | `mode` | `String` | Specify whether async runs continuously or not. In `one_time` mode, async stops after the first full synchronization. `continuous` supported only if the source is Windows or Linux.<br/>Allowed values: `one_time`, `continuous`.<br/>Default: `one_time`.<br/>(special:`--continuous`)(-C) |
12414
+ | `mode` | `Enum[String]` | Specify whether async runs continuously or not. In `one_time` mode, async stops after the first full synchronization. `continuous` supported only if the source is Windows or Linux.<br/>Allowed values: `one_time`, `continuous`.<br/>Default: `one_time`.<br/>(special:`--continuous`)(-C) |
11183
12415
  | `monitor_buffer_size` | `Integer` | Bytes to allocate for the change monitor buffer. Applies to any Windows machine on either side. `-1` to use the computed value.<br/>Default: `-1`. |
11184
12416
  | `name` | `String` | Name of the synchronization pair.<br/>Required.<br/>(`--name={string}`)(-N) |
11185
12417
  | `no_log` | `String` | Suppress log messages for ITEM. The only currently supported ITEM is 'stats', which suppresses both STATS and PROG log messages.<br/>(`--no-log={string}`) |
11186
12418
  | `no_preserve_root_attrs` | `Bool` | Disable the preservation of attributes on the Sync root.<br/>Default: `false`.<br/>(`--no-preserve-root-attrs`) |
11187
12419
  | `no_scan` | `Bool` | Skip initial scanning.<br/>Default: `false`.<br/>(`--no-scan`) |
11188
12420
  | `notifications_sharing_retry_max` | `Integer` | Retry processing filesystem notifications up to the specified maximum number after a sharing violation.<br/>Default: `3`. |
11189
- | `overwrite` | `String` | Overwrite files according to the specified policy. Default is determined by the direction: `conflict` for `bidi`, otherwise `always`.<br/>Allowed values: `always`, `older`, `conflict`.<br/>(`--overwrite={enum}`)(-o) |
12421
+ | `overwrite` | `Enum[String]` | Overwrite files according to the specified policy. Default is determined by the direction: `conflict` for `bidi`, otherwise `always`.<br/>Allowed values: `always`, `older`, `conflict`.<br/>(`--overwrite={enum}`)(-o) |
11190
12422
  | `pending_max` | `Integer` | Allow the maximum number of files that are pending transfer to be no more than the specified number.<br/>Default: `2000`.<br/>(`--pending-max={integer}`) |
11191
12423
  | `preserve_access_time` | `Bool` | Preserve file access time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-access-time`) |
11192
12424
  | `preserve_creation_time` | `Bool` | Preserve file creation time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-creation-time`) |
@@ -11197,21 +12429,22 @@ ascli config sync spec
11197
12429
  | `preserve_object_metadata` | `Bool` | Preserve object metadata from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-object-metadata`) |
11198
12430
  | `preserve_uid` | `Bool` | Preserve the file owner's UID.<br/>Default: `false`.<br/>(`--preserve-uid`)(-u) |
11199
12431
  | `quiet` | `Bool` | Disable progress display.<br/>Default: `true`.<br/>(`--quiet`)(-q) |
11200
- | `remote.connect_mode` | `String` | Define how to connect to the remote.<br/>Allowed values: `ssh`, `ws`.<br/>Default: `ssh`.<br/>(special:`--ws-connect`) |
12432
+ | `remote` | `Hash` | Required. |
12433
+ | `remote.connect_mode` | `Enum[String]` | Define how to connect to the remote.<br/>Allowed values: `ssh`, `ws`.<br/>Default: `ssh`.<br/>(special:`--ws-connect`) |
11201
12434
  | `remote.fingerprint` | `String` | Check it against server SSH host key fingerprint. |
11202
12435
  | `remote.host` | `String` | Use the specified host name or address of the remote host.<br/>Required.<br/>(`--host={string}`) |
11203
12436
  | `remote.pass` | `String` | Authenticate the transfer with the specified password.<br/>(`--pass={string}`)(-w) |
11204
12437
  | `remote.path` | `String` | Synchronize the specified directory on the remote host.<br/>Required.<br/>(`--remote-dir={string}`)(-r) |
11205
12438
  | `remote.port` | `Integer` | Use the specified TCP port for SSH. Used when connect_mode is `ssh`<br/>Default: `22`.<br/>(`--tcp-port={integer}`)(-P) |
11206
12439
  | `remote.private_key_paths` | `Array[String]` | Authenticate with the specified SSH private key file.<br/>(`--private-key-path={array}`)(-i) |
12440
+ | `remote.proxy` | `Hash` | Specify the address of the Aspera high-speed proxy server.<br/>(special:`--proxy={object}`) |
11207
12441
  | `remote.proxy.host` | `String` | Use the specified host name or address of the proxy. |
11208
12442
  | `remote.proxy.pass` | `String` | Authenticate to the proxy with the specified password. |
11209
12443
  | `remote.proxy.port` | `Integer` | Use the specified port. Default is 9091 for dnat, 9092 for dnats. |
11210
- | `remote.proxy.protocol` | `String` | The protocol to be used.<br/>Allowed values: `none`, `dnat`, `dnats`.<br/>Default: `none`. |
12444
+ | `remote.proxy.protocol` | `Enum[String]` | The protocol to be used.<br/>Allowed values: `none`, `dnat`, `dnats`.<br/>Default: `none`. |
11211
12445
  | `remote.proxy.user` | `String` | Authenticate to the proxy with the specified username. |
11212
- | `remote.proxy` | `Hash` | Specify the address of the Aspera high-speed proxy server.<br/>(special:`--proxy={object}`) |
11213
- | `remote.token_node_user` | `String` | Node API user identity associated with the token. Required for node user bearer tokens |
11214
12446
  | `remote.token` | `String` | Token string passed to server's authentication service. |
12447
+ | `remote.token_node_user` | `String` | Node API user identity associated with the token. Required for node user bearer tokens |
11215
12448
  | `remote.user` | `String` | Authenticate the transfer with the specified username.<br/>Required.<br/>(`--user={string}`) |
11216
12449
  | `remote.ws_port` | `Integer` | Use the specified port for Websocket. Used when connect_mode is `ws`.<br/>Default: `9093`. |
11217
12450
  | `remote_checksum_threads` | `Integer` | Maximum number of threads to do checksum on the remote host. Value must be between 1 and 99<br/>Default: `4`.<br/>(`--remote-checksum-threads={integer}`) |
@@ -11222,46 +12455,45 @@ ascli config sync spec
11222
12455
  | `remote_keep_dir` | `String` | Move deleted files into the specified directory on the remote host.<br/>(`--keep-dir-remote={string}`) |
11223
12456
  | `remote_mount_signature` | `String` | Verify that the file system is mounted by the existence of this file on the remote host.<br/>(`--remote-mount-signature={string}`) |
11224
12457
  | `remote_move_cache_timeout_seconds` | `Integer` | Delay in seconds before aborting moving a file from remote cache to final destination. `-1` for disabled.<br/>Default: `-1`.<br/>(`--remote-move-cache-timeout={integer}`) |
11225
- | `remote_preserve_acls` | `String` | Preserve access control lists on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_acls`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-acls={enum}`) |
11226
- | `remote_preserve_xattrs` | `String` | Preserve extended attributes on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_xattrs`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-xattrs={enum}`) |
12458
+ | `remote_preserve_acls` | `Enum[String]` | Preserve access control lists on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_acls`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-acls={enum}`) |
12459
+ | `remote_preserve_xattrs` | `Enum[String]` | Preserve extended attributes on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_xattrs`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-xattrs={enum}`) |
11227
12460
  | `remote_scan_interval_milliseconds` | `Integer` | Enable periodic scans on the remote host. `-1` for disabled. On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`. A plain number is in seconds. Stored in milliseconds.<br/>Default: `-1`.<br/>(special:`--remote-scan-interval={integer}`) |
11228
12461
  | `remote_scan_threads` | `Integer` | Number of directory scanning threads on the remote host. Value must be between 1 and 99.<br/>Default: `1`.<br/>(`--remote-scan-threads={integer}`) |
11229
12462
  | `remote_stat_cache_size` | `Integer` | Set stat cache size on the remote host. 0 for disabled.<br/>Default: `0`. |
11230
- | `remote` | `Hash` | Required. |
11231
12463
  | `remove_after_transfer` | `Bool` | Remove source files after they are successfully synchronized.<br/>Default: `false`.<br/>(`--remove-after-transfer`) |
11232
12464
  | `reset` | `Bool` | Clear the snapshot database and rescan the synchronized directories and files to create a fresh snapshot<br/>Default: `false`.<br/>(`--reset`)(-x) |
12465
+ | `resume` | `Hash` | Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early. Note that transfer resumption can only happen if the `reset` option is disabled. If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that session will be resumable, but only if async is then restarted with 'reset' disabled. |
11233
12466
  | `resume.enabled` | `Bool` | Enable the possibility of resuming individual file transfers between async sessions.<br/>Default: `false`. |
11234
12467
  | `resume.max_age` | `Integer` | Sets the age limit in days for temporary files that will be preserved on cleanup (usually at async's start and stop) for potential transfer resume. Temp files older than the given value will be removed regardless of whether they might be resumable.<br/>Default: `5`.<br/>(`--resume-age-days={integer}`) |
11235
12468
  | `resume.min_size` | `Integer` | This field specifies the minimum size of files that will be allowed to resume.<br/>Default: `1048576`.<br/>(`--support-resume={integer}`) |
11236
12469
  | `resume_scan` | `Bool` | Resume the scan from where the previous execution left off.<br/>Default: `false`.<br/>(`--resume-scan`) |
11237
- | `resume` | `Hash` | Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early. Note that transfer resumption can only happen if the `reset` option is disabled. If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that session will be resumable, but only if async is then restarted with 'reset' disabled. |
11238
12470
  | `scan_dir_rename` | `Bool` | Enable the detection of renamed directories and files compared to the previous scan, based on matching inodes<br/>Default: `false`.<br/>(`--scan-dir-rename`) |
11239
12471
  | `scan_file_rename` | `Bool` | Enable the detection of renamed files compared to the previous scan, based on matching inodes.<br/>Default: `false`.<br/>(`--scan-file-rename`) |
11240
- | `scan_intensity` | `String` | Scan at the set intensity. `vlow` minimizes system activity. `vhigh` maximizes system activity by continuously scanning files without rest.<br/>Allowed values: `vlow`, `low`, `medium`, `high`, `vhigh`.<br/>Default: `medium`.<br/>(`--scan-intensity={enum}`)(-H) |
12472
+ | `scan_intensity` | `Enum[String]` | Scan at the set intensity. `vlow` minimizes system activity. `vhigh` maximizes system activity by continuously scanning files without rest.<br/>Allowed values: `vlow`, `low`, `medium`, `high`, `vhigh`.<br/>Default: `medium`.<br/>(`--scan-intensity={enum}`)(-H) |
11241
12473
  | `sharing_retry_max` | `Integer` | Retry synchronizations up to the specified maximum number after a sharing violation.<br/>Default: `3`.<br/>(`--sharing-retry-max={integer}`) |
11242
12474
  | `store_metadata_records` | `Bool` | Store the acls or xattrs in the snapshot database.<br/>Default: `false`.<br/>(`--store-metadata-records`) |
11243
- | `symbolic_links` | `String` | Handle symbolic links with the specified method. Default is `skip` on windows, `copy` otherwise.<br/>Allowed values: `copy`, `skip`, `follow`.<br/>(`--symbolic-links={enum}`)(-n) |
12475
+ | `symbolic_links` | `Enum[String]` | Handle symbolic links with the specified method. Default is `skip` on windows, `copy` otherwise.<br/>Allowed values: `copy`, `skip`, `follow`.<br/>(`--symbolic-links={enum}`)(-n) |
11244
12476
  | `tags` | `Hash` | User-defined metadata tags.<br/>(special:`--tags64={object}`) |
12477
+ | `transfer_threads` | `Array[Hash]` | Use the specified number of dedicated transfer threads to process files smaller or equal to the specified size<br/>(special:`--transfer-threads={array}`) |
11245
12478
  | `transfer_threads[].size` | `Integer` | Upper limit. `-1` for infinity.<br/>Default: `-1`. |
11246
12479
  | `transfer_threads[].threads` | `Integer` | The number of threads.<br/>Required. |
11247
- | `transfer_threads` | `Array[Hash]` | Use the specified number of dedicated transfer threads to process files smaller or equal to the specified size<br/>(special:`--transfer-threads={array}`) |
11248
- | `transport.cipher` | `String` | Specify encryption algorithm for file data.<br/>Allowed values: `none`, `aes128`, `aes192`, `aes256`, `aes128cfb`, `aes192cfb`, `aes256cfb`, `aes128gcm`, `aes192gcm`, `aes256gcm`.<br/>Default: `aes128`.<br/>(`--cipher={enum}`)(-c) |
11249
- | `transport.compression` | `String` | Compress a file before transfer using the specified MODE.<br/>Allowed values: `none`, `zlib`.<br/>Default: `none`.<br/>(`--compression={enum}`) |
12480
+ | `transport` | `Hash` | |
12481
+ | `transport.cipher` | `Enum[String]` | Specify encryption algorithm for file data.<br/>Allowed values: `none`, `aes128`, `aes192`, `aes256`, `aes128cfb`, `aes192cfb`, `aes256cfb`, `aes128gcm`, `aes192gcm`, `aes256gcm`.<br/>Default: `aes128`.<br/>(`--cipher={enum}`)(-c) |
12482
+ | `transport.compression` | `Enum[String]` | Compress a file before transfer using the specified MODE.<br/>Allowed values: `none`, `zlib`.<br/>Default: `none`.<br/>(`--compression={enum}`) |
11250
12483
  | `transport.datagram_size` | `Integer` | Specify the datagram size (MTU) for FASP. By default it uses the detected path MTU.<br/>(`--datagram-size={integer}`)(-Z) |
11251
12484
  | `transport.min_rate` | `Integer` | Attempt to transfer no slower than the specified rate (in bps).<br/>Default: `0`.<br/>(`--min-rate={integer}`)(-m) |
11252
- | `transport.rate_policy` | `String` | Defines how `ascp` will manage the bandwidth.<br/>Allowed values: `fair`, `fixed`, `high`, `low`.<br/>Default: `fair`.<br/>(`--rate-policy={enum}`)(-a) |
12485
+ | `transport.rate_policy` | `Enum[String]` | Defines how `ascp` will manage the bandwidth.<br/>Allowed values: `fair`, `fixed`, `high`, `low`.<br/>Default: `fair`.<br/>(`--rate-policy={enum}`)(-a) |
11253
12486
  | `transport.raw_options` | `Array[String]` | Pass arbitrary arguments to `ascp`.<br/>(special:`--raw-options={array}`) |
11254
12487
  | `transport.read_block_size` | `Integer` | Use the specified block size (in bytes) for reading. Default is determined by `aspera.conf`.<br/>(`--read-block-size={integer}`)(-g) |
11255
12488
  | `transport.rexmsg_size` | `Integer` | Use the specified size (in bytes) for a retransmission request. Default is determined by `aspera.conf`.<br/>(`--rexmsg-size={integer}`)(-X) |
11256
12489
  | `transport.target_rate` | `Integer` | Transfer no faster than the specified rate (in bps). A string with suffix `k`, `m` or `g` is converted to bps by `ascli` (e.g. `100m`).<br/>Default: `10000000`.<br/>(`--target-rate={integer}`)(-l) |
11257
12490
  | `transport.udp_port` | `Integer` | Use the specified UDP port for FASP data transfer.<br/>Default: `33001`.<br/>(`--udp-port={integer}`)(-O) |
11258
12491
  | `transport.write_block_size` | `Integer` | Use the specified block size (in bytes) for writing. Default is determined by `aspera.conf`.<br/>(`--write-block-size={integer}`)(-G) |
11259
- | `transport` | `Hash` | |
11260
- | `watchd.datastore` | `String` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
12492
+ | `watchd` | `Hash` | When connection is configured, `asperawatchd` is used to detect the changes on the source directory.<br/>(special:`--watchd={object}`) |
12493
+ | `watchd.datastore` | `Enum[String]` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
11261
12494
  | `watchd.domain` | `String` | Specify the domain. Default is the current username. |
11262
12495
  | `watchd.host` | `String` | Use the specified host name or address to connect to the datastore. |
11263
12496
  | `watchd.port` | `Integer` | Use the specified port.<br/>Default: `31415`. |
11264
- | `watchd` | `Hash` | When connection is configured, `asperawatchd` is used to detect the changes on the source directory.<br/>(special:`--watchd={object}`) |
11265
12497
  | `write_gid` | `String` | Try to write files as the specified group.<br/>(`--write-gid={string}`) |
11266
12498
  | `write_uid` | `String` | Try to write files as the specified user.<br/>(`--write-uid={string}`) |
11267
12499
 
@@ -11338,16 +12570,16 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11338
12570
  **`sync_snapmeta_table`** - one row per session, written at start and updated at stop:
11339
12571
 
11340
12572
  | Field | Type | Description |
11341
- |-------------------------|---------|----------------------------------------------------------------------------------|
12573
+ | ----------------------- | ------------ | -------------------------------------------------------------------------------- |
11342
12574
  | `ascp_sids` | `String` | Last known FASP (ascp) session IDs. |
11343
12575
  | `byte_peerxfer` | `Integer` | Number of bytes transferred by the peer. |
11344
12576
  | `byte_synced` | `Integer` | Number of bytes successfully synchronized. |
11345
12577
  | `byte_xferres` | `Integer` | Number of bytes for which transfer was resumed. |
11346
- | `checksum` | `String` | Checksum algorithm.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`. |
12578
+ | `checksum` | `Enum[String]` | Checksum algorithm.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`. |
11347
12579
  | `cip_true_val` | `Integer` | Candidate-in-progress counter true value (internal). |
11348
- | `condition` | `String` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
12580
+ | `condition` | `Enum[String]` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
11349
12581
  | `dbversion` | `String` | Database schema version. |
11350
- | `direction` | `String` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
12582
+ | `direction` | `Enum[String]` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
11351
12583
  | `exclude_dirs_older_than` | `Integer` | Exclude directories with modification time older than this epoch value (0 = disabled). |
11352
12584
  | `file_peerxfer` | `Integer` | Number of files transferred by the peer. |
11353
12585
  | `file_synced` | `Integer` | Number of files successfully synchronized. |
@@ -11371,7 +12603,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11371
12603
  **`sync_snap_counters_table`** - one row, updated live during a session:
11372
12604
 
11373
12605
  | Field | Type | Description |
11374
- |--------------------------|---------|--------------------------------------------------|
12606
+ | ------------------------ | ------- | ------------------------------------------------ |
11375
12607
  | `conflict` | `Integer` | Number of paths in the `Conflict` state. |
11376
12608
  | `error` | `Integer` | Number of paths in the `Error` state. |
11377
12609
  | `files_conflict` | `Integer` | Number of files in the `Conflict` state. |
@@ -11387,7 +12619,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11387
12619
  **`sync_snapdb_table`** - one row per tracked file or directory:
11388
12620
 
11389
12621
  | Field | Type | Description |
11390
- |------------------------|---------|----------------------------------------------------------------------------------|
12622
+ | ---------------------- | ------- | -------------------------------------------------------------------------------- |
11391
12623
  | `c_cont_csum` | `String` | Current content — checksum. |
11392
12624
  | `c_cont_mtime` | `Integer` | Current content — modification time (epoch). |
11393
12625
  | `c_cont_size` | `Integer` | Current content — file size in bytes. |
@@ -11405,8 +12637,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11405
12637
  | `c_meta_path` | `String` | Current metadata — file path as known to the snapshot. |
11406
12638
  | `c_meta_type` | `Integer` | Current metadata — file type (file, directory, …). |
11407
12639
  | `c_meta_uid` | `Integer` | Current metadata — user ID (Unix). |
11408
- | `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
11409
12640
  | `c_meta_xattrs` | `Integer` | Current metadata — extended attributes (not used). |
12641
+ | `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
11410
12642
  | `candidate_in_prog` | `Integer` | Set to 1 when this record is currently in the candidate transfer list. |
11411
12643
  | `commit_version` | `Integer` | Local commit version for this entry. |
11412
12644
  | `f_cont_csum` | `String` | Filesystem content — checksum. |
@@ -11426,8 +12658,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11426
12658
  | `f_meta_path` | `String` | Filesystem metadata — file path as seen on disk (displayed by `file_info`). |
11427
12659
  | `f_meta_type` | `Integer` | Filesystem metadata — file type. |
11428
12660
  | `f_meta_uid` | `Integer` | Filesystem metadata — user ID (Unix). |
11429
- | `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
11430
12661
  | `f_meta_xattrs` | `Integer` | Filesystem metadata — extended attributes (not used). |
12662
+ | `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
11431
12663
  | `message` | `String` | Error or status message associated with this entry. |
11432
12664
  | `meta_lastreq_no` | `Integer` | Sequence number of the last metadata request sent. |
11433
12665
  | `meta_lastresp_no` | `Integer` | Sequence number of the last metadata response received. |
@@ -11588,11 +12820,11 @@ To do so, set up the SMTP configuration with option `smtp`.
11588
12820
  The `smtp` option is a `Hash` ([Extended Value](#extended-value-syntax)) with the following fields:
11589
12821
 
11590
12822
  | Field | Type | Description |
11591
- |------------|---------|----------------------------------------------------------------------------------|
12823
+ | ---------- | ------- | -------------------------------------------------------------------------------- |
11592
12824
  | `domain` | `String` | Email domain of the user. Defaults to the domain part of `server`.<br/>Example: `gmail.com`. |
11593
12825
  | `from_email` | `String` | Sender address (used in `From:` header and as reply-to). Defaults to `username` when defined.<br/>Example: `johnny@example.com`. |
11594
12826
  | `from_name` | `String` | Display name of the sender. Defaults to the local-part of `from_email`.<br/>Example: `John Wayne`. |
11595
- | `password` | `String` | Password for the above `username`.<br/>Example: `my_password`. |
12827
+ | `password` | `String` | Password for the above `username`.<br/>Example: `<PASSWORD>`. |
11596
12828
  | `port` | `Integer` | Port for the SMTP service.<br/>Defaults: `587` (TLS), `465` (SSL), `25` (plain).<br/>Example: `587`. |
11597
12829
  | `server` | `String` | SMTP server address.<br/>Required.<br/>Example: `smtp.gmail.com`. |
11598
12830
  | `ssl` | `Bool` | Enable `TLS/SSL` (port 465).<br/>Default: `false`. |
@@ -11610,14 +12842,13 @@ ascli config preset set smtp_google password <PASSWORD>
11610
12842
  or
11611
12843
 
11612
12844
  ```shell
11613
- ascli config preset initialize smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"<PASSWORD>"}'
12845
+ ascli config preset set smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"<PASSWORD>"}'
11614
12846
  ```
11615
12847
 
11616
12848
  or
11617
12849
 
11618
-
11619
12850
  ```shell
11620
- ascli config preset update smtp_google --server=smtp.google.com --username=john@gmail.com --password=<PASSWORD>
12851
+ ascli config preset set smtp_google @: server=smtp.google.com username=john@gmail.com password=<PASSWORD>
11621
12852
  ```
11622
12853
 
11623
12854
  Set this configuration as global default, for instance:
@@ -11821,28 +13052,26 @@ This also requires Ruby header files.
11821
13052
  If Ruby was installed as a Linux package, then also install the Ruby development package:
11822
13053
  `ruby-dev` or `ruby-devel`, depending on distribution.
11823
13054
 
11824
- ### Private key type: `ed25519` not supported by default
11825
-
11826
- There are a few aspects concerning ED25519 keys.
13055
+ ### Private key type: `ed25519`
11827
13056
 
11828
- By default, the `aspera-cli` gem does not depend on the `ed25519` gem because it requires compilation of native code which can cause problems and prevent the installation of `ascli`, especially when using JRuby.
11829
- See [net-ssh issue 565](https://github.com/net-ssh/net-ssh/issues/565).
11830
- If you want to use `ed25519` keys, then install the required gems:
13057
+ Keys of type `ed25519` and keys in the OpenSSH format are supported by `net-ssh` using the Ruby `openssl` gem (>= 3.2.0): the `ed25519` gem is not needed.
13058
+ Only OpenSSH private keys protected by a passphrase require the `bcrypt_pbkdf` gem, which requires compilation of native code:
11831
13059
 
11832
13060
  ```shell
11833
- gem install ed25519 bcrypt_pbkdf
13061
+ gem install bcrypt_pbkdf
11834
13062
  ```
11835
13063
 
11836
- In addition, if those two gems are not installed, and if you are using Private Keys encoded using the OpenSSH format, the following message is displayed:
13064
+ If the gem is missing, then loading such a key fails with an error mentioning `bcrypt_pbkdf`.
13065
+
13066
+ If the OpenSSL backend does not support Ed25519, then the following message is displayed:
11837
13067
 
11838
13068
  ```text
11839
13069
  OpenSSH keys only supported if ED25519 is available (NotImplementedError)
11840
- net-ssh requires the following gems for ed25519 support:
11841
- * ed25519 (>= 1.2, < 2.0)
11842
- * bcrypt_pbkdf (>= 1.0, < 2.0)
11843
- See https://github.com/net-ssh/net-ssh/issues/565 for more information
13070
+ net-ssh requires openssl >= 3.2.0 and a crypto backend with Ed25519 enabled for ed25519 support.
11844
13071
  ```
11845
13072
 
13073
+ To ignore the `ed25519` keys of the default identities (`~/.ssh/id_ed25519`), set env var `ASCLI_ENABLE_ED25519` to `false`.
13074
+
11846
13075
  In addition, if **JRuby** is used, host keys of type: `ecdsa-sha2` and `ecdh-sha2` are also deactivated by default.
11847
13076
  To activate, set env var `ASCLI_ENABLE_ECDSHA2` to `true`.
11848
13077
 
@@ -11878,7 +13107,7 @@ This happens on Linux x86 if you try to install `transferd` on a Linux version t
11878
13107
  Workaround: Install an older version of `transferd`:
11879
13108
 
11880
13109
  ```shell
11881
- ascli config transferd install 1.1.2
13110
+ ascli transferd install 1.1.2
11882
13111
  ```
11883
13112
 
11884
13113
  See [Single file executable](#single-file-executable).
@@ -11919,11 +13148,45 @@ Another possibility is to add this option: `--transfer=@json:'{"ascp_args":["--p
11919
13148
  > If one relies on `--lock-port` when using containers to avoid parallel transfers in a cron job, this may be the cause, as `lock_port` does not lock across containers.
11920
13149
  > Use `flock` instead.
11921
13150
 
13151
+ ## Security and Trust
13152
+
13153
+ This section is for security and compliance reviewers who evaluate `ascli` before its use in an organization.
13154
+ It summarizes how `ascli` protects credentials, communications and the system that runs it, and how the project is developed and released.
13155
+ The detailed reasoning is in the [Security Assurance Case](ASSURANCE_CASE.md).
13156
+
13157
+ ### Protection by area
13158
+
13159
+ | Area | How `ascli` protects it | Details |
13160
+ | ---- | ------------------------ | ------- |
13161
+ | Credentials | Secret values are hidden in logs, results and error messages. Secrets can be kept in a vault instead of the configuration file: encrypted file, HashiCorp Vault, Keeper, 1Password, macOS keychain, Linux Secret Service. The configuration folder is readable only by the current user. | [Secret Vault](#secret-vault) |
13162
+ | Communications | API calls use HTTPS, and the certificate of the server is verified by default (disabled only with `--insecure=yes`). | [SSL CA certificate bundle](#configuring-the-ssl-ca-certificate-bundle) |
13163
+ | File transfers | Transfers use the IBM Aspera transfer engine (`ascp`), with the encryption in transit and at rest defined by the server and the transfer specification. | [Transfer Specification](#transfer-specification) |
13164
+ | Execution by a client that is not fully trusted (AI assistant, program that builds commands) | A security level restricts what commands can do: reading local files, executing code, writing files. The MCP server uses level `high` by default, and the client cannot change it. | [Security Level](#security-level) |
13165
+ | AI assistants (MCP server) | The AI client cannot execute code, cannot write files outside the folders that the user allows, and never sees secrets. Over HTTP, a token is mandatory when the server is not on the loopback address, and OAuth 2.0 with PKCE is supported. | [MCP server security](#security) |
13166
+ | Local web servers (login, MCP over HTTP) | They listen on the loopback address by default, with authentication and protection against cross-site requests. | [Web service](#web-service) |
13167
+ | Usage data | `ascli` sends no usage data (no telemetry). It connects to the servers given in commands and presets, and to public IBM and GitHub locations only for the commands that download from them (for example `transferd install`, development guides). Every 7 days by default, it checks RubyGems for a new version (option `version_check_days`, `0` to disable). | [Configuration](#plugin-config-configuration) |
13168
+
13169
+ ### Supply chain
13170
+
13171
+ - The gem is signed: its signature can be verified at installation, see [Verifying gem installation signature](#verifying-gem-installation-signature).
13172
+ - Publishing the gem on RubyGems requires multi-factor authentication.
13173
+ - Release packages (gem, single executable, portable packages, container image) are built by GitHub Actions from the repository.
13174
+ - Dependencies are gems, updated with Renovate.
13175
+ - The source code is analyzed by CodeQL and RuboCop in continuous integration, and tested by unit and integration tests, including tests of the security levels (coverage is shown in the README badge).
13176
+
13177
+ ### Project practices
13178
+
13179
+ - Open source, Apache 2.0 license, developed in the [IBM GitHub organization](https://github.com/IBM/aspera-cli).
13180
+ - [OpenSSF Best Practices](https://www.bestpractices.dev/projects/5861): silver badge.
13181
+ - Vulnerabilities are reported and handled as described in [SECURITY.md](../SECURITY.md).
13182
+ - Roles, decisions and continuity of the project: [GOVERNANCE.md](../GOVERNANCE.md).
13183
+ - Structure of the code: [ARCHITECTURE.md](ARCHITECTURE.md).
13184
+
11922
13185
  ## About
11923
13186
 
11924
13187
  ### Hootput, the mascot
11925
13188
 
11926
- ![Hootput the Owl](mascot.svg)
13189
+ ![Hootput the Owl](art/mascot.svg)
11927
13190
 
11928
13191
  Hootput lives in the terminal, watching over every command with wide, unblinking eyes.
11929
13192
  Known for concise output and sharp insight, this owl thrives where others get lost in the dark.