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
@@ -1,8 +1,11 @@
1
- openapi: 3.0.0
1
+ openapi: 3.1.0
2
2
  info:
3
3
  title: Aspera CLI Options Schema
4
4
  version: 1.0.0
5
5
  description: Schema definitions for Aspera CLI options
6
+ license:
7
+ name: Apache-2.0
8
+ identifier: Apache-2.0
6
9
  paths: {}
7
10
  components:
8
11
  schemas:
@@ -39,10 +42,15 @@ components:
39
42
  mode:
40
43
  type: string
41
44
  description: >-
42
- `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`.
43
- `terminal`: URLs and files to open are displayed on terminal, and secrets are entered on terminal.
44
- `browser`: a browser opens URLs, secrets are entered on a web page, and a text editor opens files.
45
+ - `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`.
46
+
47
+ - `terminal`: URLs to open are displayed on terminal, and secrets are entered on terminal.
48
+
49
+ - `browser`: a browser opens URLs, and secrets are entered on a web page.
50
+
45
51
  `text` is an alias for `terminal`, and `graphical` is an alias for `browser`.
52
+
53
+ Files to edit are always opened with a text editor, whatever the `mode`.
46
54
  enum:
47
55
  - auto
48
56
  - terminal
@@ -50,11 +58,33 @@ components:
50
58
  - text
51
59
  - graphical
52
60
  default: auto
61
+ web_auth:
62
+ type: string
63
+ description: >-
64
+ How the result of a web login (`--auth=web`, SSO) is received.
65
+
66
+ - `port`: `ascli` listens on the loopback port of `redirect_uri`, the browser is redirected to it.
67
+
68
+ - `paste`: no port is opened. After login, the browser shows a connection error on `redirect_uri`:
69
+ copy the full URL from the address bar of the browser and paste it in the terminal.
70
+ Use it when the browser cannot reach the host that runs `ascli` and a SSH tunnel is not possible.
71
+ For `shares`, Shares displays a code (a long text of letters, digits, `-` and `_`) instead: paste it in the terminal.
72
+ enum:
73
+ - port
74
+ - paste
75
+ default: port
76
+ hidden_silent:
77
+ type: boolean
78
+ description: >-
79
+ Secrets typed or pasted on a terminal are read without any feedback (no echo, no mark), as `getpass`.
80
+ By default, a mark shows whether something was typed or pasted, without revealing the length.
81
+ default: false
53
82
  command:
54
83
  type: array
84
+ x-security: low
55
85
  description: >-
56
86
  Command that opens a URL, instead of the system default.
57
- First item is the executable, then its arguments. The URL is added as last argument.
87
+ 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.
58
88
  When set, it is used to open URLs, whatever the `mode`.
59
89
  items:
60
90
  type: string
@@ -69,9 +99,13 @@ components:
69
99
  level:
70
100
  type: string
71
101
  description: >-
72
- `low`: no restriction.
73
- `medium`: `@file:` reads only files in `allowed_paths`, `@ruby:`, `@uri:` and `@env:` are refused.
74
- `high`: `@ruby:`, `@file:`, `@uri:` and `@env:` are refused.
102
+ - `low`: no restriction.
103
+
104
+ - `medium`: `@file:` reads only files in `allowed_paths`, `@ruby:`, `@uri:`, `@env:` and `@zlib:` are refused, files are written only in `writable_paths`.
105
+
106
+ - `high`: `@ruby:`, `@file:`, `@uri:`, `@env:` and `@zlib:` are refused, files are written only in `writable_paths`.
107
+
108
+ Features that execute code, load plugins, or write a file chosen by the client (e.g. `--out.file`) are available only at level `low`.
75
109
  enum:
76
110
  - low
77
111
  - medium
@@ -83,6 +117,13 @@ components:
83
117
  A symbolic link leading outside of them is refused.
84
118
  items:
85
119
  type: string
120
+ writable_paths:
121
+ type: array
122
+ description: >-
123
+ With levels `medium` and `high`: folders where files can be written (downloaded files, results of `config download`), none by default.
124
+ A symbolic link leading outside of them is refused.
125
+ items:
126
+ type: string
86
127
  TempOptions:
87
128
  type: object
88
129
  description: >-
@@ -92,10 +133,13 @@ components:
92
133
  properties:
93
134
  folder:
94
135
  type: string
136
+ x-cli-complete: folder
95
137
  description: >-
96
138
  Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd`.
97
- `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`).
98
- `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).
139
+
140
+ - `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`).
141
+
142
+ - `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).
99
143
  default: '@sys'
100
144
  clean:
101
145
  type: boolean
@@ -273,12 +317,10 @@ components:
273
317
  default: []
274
318
  spawn_timeout_sec:
275
319
  type: number
276
- format: float
277
320
  description: Multi session - Maximum time (in seconds) to verify that `ascp` is running.
278
321
  default: 2
279
322
  spawn_delay_sec:
280
323
  type: number
281
- format: float
282
324
  description: Multi session - Delay (in seconds) between starting each `ascp` session.
283
325
  default: 2
284
326
  multi_incr_udp:
@@ -390,6 +432,16 @@ components:
390
432
  type: boolean
391
433
  description: Stop the daemon when `ascli` exits.
392
434
  default: true
435
+ api_key:
436
+ type: string
437
+ description: >-
438
+ API key of an existing daemon (`start` is `false`) that has `authentication` enabled in its configuration.
439
+ It is sent in the metadata `api_key` of each call.
440
+ ca_file:
441
+ type: string
442
+ description: >-
443
+ Path to the certificate authority file (PEM) that signed the certificate of an existing daemon (`start` is `false`)
444
+ that has `tls` enabled in its configuration. A self-signed certificate is its own authority.
393
445
  TransferAgentOptions:
394
446
  description: >-
395
447
  Transfer agent selector and agent-specific parameters.
@@ -420,7 +472,8 @@ components:
420
472
  server:
421
473
  type: string
422
474
  description: SMTP server address.
423
- example: smtp.gmail.com
475
+ examples:
476
+ - smtp.gmail.com
424
477
  tls:
425
478
  type: boolean
426
479
  description: Enable `STARTTLS` (port 587).
@@ -435,29 +488,102 @@ components:
435
488
  Port for the SMTP service.
436
489
 
437
490
  Defaults: `587` (TLS), `465` (SSL), `25` (plain).
438
- example: 587
491
+ examples:
492
+ - 587
439
493
  domain:
440
494
  type: string
441
495
  description: Email domain of the user. Defaults to the domain part of `server`.
442
- example: gmail.com
496
+ examples:
497
+ - gmail.com
443
498
  username:
444
499
  type: string
445
500
  description: >-
446
501
  User to authenticate on the SMTP server.
447
502
  Leave empty for open (unauthenticated) relay.
448
- example: john@example.com
503
+ examples:
504
+ - john@example.com
449
505
  password:
450
506
  type: string
451
507
  description: Password for the above `username`.
452
- example: my_password
508
+ examples:
509
+ - "<PASSWORD>"
453
510
  from_email:
454
511
  type: string
455
512
  description: Sender address (used in `From:` header and as reply-to). Defaults to `username` when defined.
456
- example: johnny@example.com
513
+ examples:
514
+ - johnny@example.com
457
515
  from_name:
458
516
  type: string
459
517
  description: Display name of the sender. Defaults to the local-part of `from_email`.
460
- example: John Wayne
518
+ examples:
519
+ - John Wayne
520
+ ServiceOptions:
521
+ type: object
522
+ description: >-
523
+ Installation parameters of the transfer daemon (`transferd`) as a system service.
524
+ The content of the daemon configuration file is described by its own schema.
525
+ additionalProperties: false
526
+ properties:
527
+ name:
528
+ type: string
529
+ description: >-
530
+ Name of the service.
531
+ The unit file is `<name>.service`.
532
+ default: aspera-transferd
533
+ minLength: 1
534
+ user:
535
+ type: string
536
+ description: >-
537
+ Account that runs the daemon.
538
+ It must exist, it is not created.
539
+ default: asperadaemon
540
+ minLength: 1
541
+ group:
542
+ type: string
543
+ description: Group that runs the daemon. Defaults to the primary group of `user`.
544
+ minLength: 1
545
+ unit_dir:
546
+ type: string
547
+ description: Folder where the unit file is created.
548
+ default: /etc/systemd/system
549
+ minLength: 1
550
+ after:
551
+ type: array
552
+ description: Units that shall be started before the daemon (`After=` in the unit).
553
+ items:
554
+ type: string
555
+ default:
556
+ - network.target
557
+ environment:
558
+ type: object
559
+ description: >-
560
+ Environment variables set in the unit.
561
+ None is set unless given here.
562
+ `TRANSFERD_ADDRESS`, `TRANSFERD_PORT`, `TRANSFERD_MGMT_PORT` and `TRANSFERD_MGMT_ADDRESS` override the configuration file.
563
+ additionalProperties:
564
+ type: string
565
+ version:
566
+ type: string
567
+ description: >-
568
+ Version of the SDK to install, used by `install` when the SDK folder is named `current` (versions side by side).
569
+ Defaults to the SDK version of this tool.
570
+ pattern: '^\d+(\.\d+)*$'
571
+ purge:
572
+ type: boolean
573
+ description: Used by `uninstall`. Also remove the configuration file and the log folder.
574
+ default: false
575
+ TransferdServiceConfig:
576
+ type: object
577
+ description: >-
578
+ Configuration of the transfer daemon (`transferd`) as a system service.
579
+ additionalProperties: false
580
+ properties:
581
+ service:
582
+ $ref: "#/components/schemas/ServiceOptions"
583
+ config:
584
+ type: object
585
+ description: >-
586
+ Content of `transferd.json`, validated against the transfer daemon configuration schema.
461
587
  HttpOptions:
462
588
  type: object
463
589
  description: >-
@@ -465,26 +591,46 @@ components:
465
591
 
466
592
  Keys are dispatched at startup to three targets:
467
593
  `Rest::Parameters` (`user_agent`, `download_partial_suffix`, `retry_*`),
468
- `SSL` (`ssl_options`), and `OAuth` (`token_cache_max_age`, `token_refresh_threshold`).
594
+ `SSL` (`ssl_options`), and `OAuth` (`token_*`, `jwt_*`).
469
595
  Any remaining key is forwarded as a setter to the `Net::HTTP` session
470
596
  (e.g. `ca_file`, `verify_mode`) — the list below covers the common ones.
471
597
  additionalProperties: true
472
598
  properties:
473
599
  read_timeout:
474
- type: number
475
- description: Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)
600
+ oneOf:
601
+ - type: string
602
+ - type: number
603
+ minimum: 0
604
+ description: >-
605
+ Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)
606
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
476
607
  default: 60
477
608
  write_timeout:
478
- type: number
479
- description: Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)
609
+ oneOf:
610
+ - type: string
611
+ - type: number
612
+ minimum: 0
613
+ description: >-
614
+ Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)
615
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
480
616
  default: 60
481
617
  open_timeout:
482
- type: number
483
- description: Maximum time in seconds to wait for a connection to be established. (Net::HTTP)
618
+ oneOf:
619
+ - type: string
620
+ - type: number
621
+ minimum: 0
622
+ description: >-
623
+ Maximum time in seconds to wait for a connection to be established. (Net::HTTP)
624
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
484
625
  default: 60
485
626
  keep_alive_timeout:
486
- type: number
487
- description: Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)
627
+ oneOf:
628
+ - type: string
629
+ - type: number
630
+ minimum: 0
631
+ description: >-
632
+ Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)
633
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
488
634
  default: 2
489
635
  ssl_options:
490
636
  type: array
@@ -515,20 +661,67 @@ components:
515
661
  description: Maximum number of retry attempts. (Rest)
516
662
  default: 1
517
663
  retry_sleep:
518
- type: integer
519
- description: Delay in seconds between retry attempts. (Rest)
664
+ oneOf:
665
+ - type: string
666
+ - type: number
667
+ minimum: 0
668
+ description: >-
669
+ Delay in seconds between retry attempts. (Rest)
670
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
520
671
  default: 4
521
672
  token_cache_max_age:
522
- type: integer
523
- description: Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)
673
+ oneOf:
674
+ - type: string
675
+ - type: number
676
+ minimum: 0
677
+ description: >-
678
+ Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)
679
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
524
680
  default: 1800
525
681
  token_refresh_threshold:
526
- type: integer
527
- description: Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)
682
+ oneOf:
683
+ - type: string
684
+ - type: number
685
+ minimum: 0
686
+ description: >-
687
+ Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)
688
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
528
689
  default: 120
690
+ token_refresh_max_age:
691
+ oneOf:
692
+ - type: string
693
+ - type: number
694
+ minimum: 0
695
+ description: >-
696
+ Age in seconds (since it was obtained) above which the token is proactively refreshed, `0` for no limit.
697
+ E.g. keeps a session alive when the refresh token expires at the same time as the token (Shares). (OAuth)
698
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
699
+ default: 0
700
+ jwt_accepted_offset_sec:
701
+ oneOf:
702
+ - type: string
703
+ - type: number
704
+ minimum: 0
705
+ description: >-
706
+ Tolerance of clock difference with the server: a generated JWT is valid since this duration in the past (`nbf`). (OAuth)
707
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
708
+ default: 300
709
+ jwt_expiry_offset_sec:
710
+ oneOf:
711
+ - type: string
712
+ - type: number
713
+ minimum: 0
714
+ description: >-
715
+ Validity of a generated JWT, used to request a token. (OAuth)
716
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
717
+ default: 3600
529
718
  VaultHashicorpOptions:
530
719
  type: object
531
- description: IBM HashiCorp Vault secret store.
720
+ description: >-
721
+ IBM HashiCorp Vault secret store.
722
+ Labels of `config vault` and `@vault:<label>.<field>` are in mount `secret` (KV v2).
723
+ Reference `@vault://<store>/<mount>/<path>#<field>` (field required) in any KV v2 mount, options `version=<n>`, `mount=<mount>` (when the mount contains `/`).
724
+ additionalProperties: false
532
725
  required:
533
726
  - type
534
727
  - url
@@ -540,14 +733,49 @@ components:
540
733
  url:
541
734
  type: string
542
735
  description: URL of the HashiCorp Vault server.
543
- example: "http://127.0.0.1:8200"
736
+ examples:
737
+ - "http://127.0.0.1:8200"
544
738
  token:
545
739
  type: string
546
- description: Authentication token. Defaults to the value of `vault_password`.
547
- example: dev-only-token
740
+ description: >-
741
+ The authentication token. Its value, or `@file:<path>` (e.g. written and renewed by Vault Agent), read again when modified.
742
+ One of `token` or `approle` is required.
743
+ For the default store, defaults to the value of `vault_password`, unless `approle` is set.
744
+ examples:
745
+ - "<TOKEN>"
746
+ approle:
747
+ type: object
748
+ description: >-
749
+ AppRole authentication: the token is obtained by login, renewed, and obtained again when refused.
750
+ properties:
751
+ role_id:
752
+ type: string
753
+ description: Role ID.
754
+ secret_id:
755
+ type: string
756
+ description: "Secret ID (if the role requires one): the value, or `@file:<path>`."
757
+ mount:
758
+ type: string
759
+ description: Mount path of the AppRole auth method.
760
+ default: approle
761
+ required:
762
+ - role_id
763
+ namespace:
764
+ type: string
765
+ description: Namespace (Vault Enterprise).
766
+ ca_file:
767
+ type: string
768
+ x-cli-complete: file
769
+ description: File with the CA certificates that verify the certificate of the server (HTTPS).
770
+ allowed_prefixes:
771
+ type: array
772
+ description: "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."
773
+ items:
774
+ type: string
548
775
  VaultSystemOptions:
549
776
  type: object
550
777
  description: macOS system keychain secret store.
778
+ additionalProperties: false
551
779
  required:
552
780
  - type
553
781
  properties:
@@ -559,9 +787,25 @@ components:
559
787
  type: string
560
788
  description: Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).
561
789
  default: ascli
790
+ VaultSecretServiceOptions:
791
+ type: object
792
+ description: Linux Secret Service secret store (GNOME Keyring, KWallet, KeePassXC...), using `secret-tool`.
793
+ additionalProperties: false
794
+ required:
795
+ - type
796
+ properties:
797
+ type:
798
+ type: string
799
+ description: Vault type selector.
800
+ enum: [secret_service]
801
+ name:
802
+ type: string
803
+ description: Name of the group of secrets (attribute `service` of the items).
804
+ default: ascli
562
805
  VaultOnePasswordOptions:
563
806
  type: object
564
807
  description: 1Password secret store (Connect REST API or CLI).
808
+ additionalProperties: false
565
809
  required:
566
810
  - type
567
811
  - source
@@ -578,22 +822,46 @@ components:
578
822
  url:
579
823
  type: string
580
824
  description: Base URL of the 1Password Connect server (required when `source` is `api`).
581
- example: "http://localhost:8080"
825
+ examples:
826
+ - "http://localhost:8080"
582
827
  vault_id:
583
828
  type: string
584
829
  description: ID of the 1Password vault to use (required when `source` is `api`).
585
830
  token:
586
831
  type: string
587
- description: Bearer token for the Connect API (required when `source` is `api`). Defaults to the value of `vault_password`.
832
+ description: Bearer token for the Connect API (required when `source` is `api`). For the default store, defaults to the value of `vault_password`.
588
833
  vault:
589
834
  type: string
590
835
  description: Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted.
591
836
  account:
592
837
  type: string
593
838
  description: Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted.
839
+ VaultKeeperOptions:
840
+ type: object
841
+ description: >-
842
+ Keeper Secrets Manager secret store (Keeper Vault), using gem `keeper_secrets_manager`.
843
+ A secret is a record shared with the application: its label is its title or its UID.
844
+ Reference `@vault://<store>/<title or uid>[#<field>]`, field `password` by default: standard field by type (`login`, `password`, `url`...), custom field by label, or `notes`.
845
+ additionalProperties: false
846
+ required:
847
+ - type
848
+ properties:
849
+ type:
850
+ type: string
851
+ description: Vault type selector.
852
+ enum: [keeper]
853
+ config:
854
+ type: string
855
+ description: >-
856
+ Configuration of the client device (base64 or JSON, e.g. from `ksm profile export`): the value, or `@file:<path>`.
857
+ For the default store, defaults to the value of `vault_password`.
858
+ folder_uid:
859
+ type: string
860
+ description: UID of the shared folder where `config vault create` adds records (not needed to read).
594
861
  VaultFileOptions:
595
862
  type: object
596
- description: Encrypted file secret store.
863
+ description: Encrypted file secret store. Reference `@vault://<store>/<label>[#<field>]`, field `password` by default.
864
+ additionalProperties: false
597
865
  required:
598
866
  - type
599
867
  properties:
@@ -601,12 +869,23 @@ components:
601
869
  type: string
602
870
  description: Vault type selector.
603
871
  enum: [file]
604
- name:
872
+ file:
605
873
  type: string
874
+ x-cli-complete: file
606
875
  description: >-
607
- Path to the encrypted vault file.
876
+ Path to the encrypted vault file, created when the first secret is added.
608
877
  Relative paths are resolved from the configuration folder.
878
+ Read when used, and again when modified.
609
879
  default: vault.bin
880
+ name:
881
+ type: string
882
+ x-cli-complete: file
883
+ description: Same as `file` (compatibility).
884
+ password:
885
+ type: string
886
+ description: >-
887
+ Password of the vault file: the value, or `@file:<path>`, read again when modified.
888
+ For the default store, defaults to the value of `vault_password`.
610
889
  VaultSecret:
611
890
  type: object
612
891
  description: Secret entry in the vault
@@ -628,21 +907,58 @@ components:
628
907
  description:
629
908
  type: string
630
909
  description: Human-readable description of this secret
631
- VaultOptions:
632
- title: Secret vault configuration
633
- description: Secret vault configuration. Set `type` to select the vault backend.
910
+ VaultStore:
911
+ type: object
912
+ title: Secret store
913
+ description: Parameters of a secret store. Set `type` to select the store type.
634
914
  oneOf:
635
915
  - $ref: "#/components/schemas/VaultHashicorpOptions"
636
916
  - $ref: "#/components/schemas/VaultSystemOptions"
917
+ - $ref: "#/components/schemas/VaultSecretServiceOptions"
637
918
  - $ref: "#/components/schemas/VaultFileOptions"
638
919
  - $ref: "#/components/schemas/VaultOnePasswordOptions"
920
+ - $ref: "#/components/schemas/VaultKeeperOptions"
639
921
  discriminator:
640
922
  propertyName: type
641
923
  mapping:
642
924
  vault: "#/components/schemas/VaultHashicorpOptions"
643
925
  system: "#/components/schemas/VaultSystemOptions"
926
+ secret_service: "#/components/schemas/VaultSecretServiceOptions"
644
927
  file: "#/components/schemas/VaultFileOptions"
645
- 1password: "#/components/schemas/VaultOnePasswordOptions"
928
+ 1password: "#/components/schemas/VaultOnePasswordOptions" # HashiCorpIgnore
929
+ keeper: "#/components/schemas/VaultKeeperOptions"
930
+ VaultStores:
931
+ type: object
932
+ title: Secret stores
933
+ description: Named secret stores, and the default store.
934
+ additionalProperties: false
935
+ required:
936
+ - stores
937
+ properties:
938
+ default:
939
+ type: string
940
+ description: >-
941
+ Name of the default store, in `stores`: read by `@vault:<label>.<field>`, managed by `config vault`, unlocked with option `vault_password`.
942
+ No default store if not set.
943
+ cache_ttl:
944
+ type: number
945
+ minimum: 0
946
+ description: Time in seconds a value read by reference is kept in memory, `0` for no cache.
947
+ default: 60
948
+ stores:
949
+ type: object
950
+ description: >-
951
+ Name of store (letters, digits, `_`, `.`, `-`) → parameters of store, with `type`.
952
+ Secrets are read by reference with `@vault://<store>/<path>[?<options>][#<field>]` from any store.
953
+ additionalProperties:
954
+ $ref: "#/components/schemas/VaultStore"
955
+ VaultOptions:
956
+ type: object
957
+ title: Secret vault configuration
958
+ description: Named secret stores (`stores`), or (deprecated) the parameters of one store, which is the default store, named after its type.
959
+ oneOf:
960
+ - $ref: "#/components/schemas/VaultStores"
961
+ - $ref: "#/components/schemas/VaultStore"
646
962
  ImageOptions:
647
963
  type: object
648
964
  description: Options for displaying images and thumbnails in the terminal.
@@ -662,9 +978,96 @@ components:
662
978
  Default is `true` if the terminal supports Unicode (see `utf8`).
663
979
  font_ratio:
664
980
  type: number
665
- format: float
666
981
  description: Terminal font aspect ratio (height divided by width).
667
982
  default: 2.3
983
+ AscpLogsOptions:
984
+ type: object
985
+ description: Analysis of `ascp` log files (`config ascp logs`).
986
+ additionalProperties: false
987
+ properties:
988
+ period:
989
+ type: integer
990
+ description: Snapshot period, in minutes.
991
+ default: 1
992
+ zero_bytes:
993
+ type: boolean
994
+ description: Include sessions without transferred bytes.
995
+ default: false
996
+ mtu:
997
+ type: integer
998
+ description: MTU, when not found in logs.
999
+ resolve:
1000
+ type: boolean
1001
+ description: Resolve peer addresses to host names.
1002
+ default: false
1003
+ timezone:
1004
+ type: string
1005
+ description: Time zone of the log lines (`UTC` or `+HH:MM`), to read a log from another time zone. Default is the local time zone.
1006
+ health_minutes:
1007
+ type: integer
1008
+ description: Window in minutes to report transfer errors and low efficiency.
1009
+ default: 60
1010
+ remote_max_size:
1011
+ type: integer
1012
+ description: Maximum total size in bytes of the log files read from a server (`server logs`).
1013
+ default: 536870912
1014
+ thresholds:
1015
+ type: object
1016
+ description: Diagnostic thresholds.
1017
+ additionalProperties: false
1018
+ properties:
1019
+ efficiency:
1020
+ type: number
1021
+ description: Minimum efficiency percentage below which a warning is emitted.
1022
+ default: 90.0
1023
+ control_loss_percent:
1024
+ type: number
1025
+ description: Minimum percentage of lost control messages to trigger a warning.
1026
+ default: 5.0
1027
+ control_loss_sent:
1028
+ type: integer
1029
+ description: Minimum number of control messages sent before checking control loss.
1030
+ default: 10
1031
+ retry_window:
1032
+ type: integer
1033
+ description: Maximum interval in seconds between sessions to link a retry.
1034
+ default: 3600
1035
+ last_error_window:
1036
+ type: integer
1037
+ description: Window in seconds before exit to attribute the last logged error.
1038
+ default: 60
1039
+ rate_decline_ratio:
1040
+ type: number
1041
+ description: Ratio of second half rate to first half rate below which rate decline is diagnosed.
1042
+ default: 0.7
1043
+ rate_decline_min_samples:
1044
+ type: integer
1045
+ description: Minimum number of samples to evaluate rate decline.
1046
+ default: 10
1047
+ rate_decline_delay:
1048
+ type: integer
1049
+ description: Delay in seconds after session start before evaluating rate decline samples.
1050
+ default: 20
1051
+ rate_decline_end_fraction:
1052
+ type: number
1053
+ description: Fraction of samples to discard from the end of a session when evaluating rate decline.
1054
+ default: 0.1
1055
+ license_expiry_days:
1056
+ type: integer
1057
+ description: Number of days before the expiry of the license of ascp (or less, if already expired) at which a warning is emitted.
1058
+ default: 30
1059
+ small_files_min_count:
1060
+ type: integer
1061
+ description: Minimum number of transferred files to check for the small-files diagnostic.
1062
+ default: 100
1063
+ small_files_max_mean:
1064
+ type: integer
1065
+ description: Maximum mean file size in bytes below which the small-files diagnostic is emitted.
1066
+ default: 1000000
1067
+ small_mtu_max:
1068
+ type: integer
1069
+ description: Path MTU in bytes below which the small-MTU diagnostic is emitted (ascp measures 1492, 1006, 508 or 296).
1070
+ default: 1400
668
1071
  PackageFolderOptions:
669
1072
  type: object
670
1073
  title: Package download folder organization
@@ -680,7 +1083,9 @@ components:
680
1083
  items:
681
1084
  type: string
682
1085
  maxItems: 2
683
- example: ["name", "id"]
1086
+ examples:
1087
+ - - name
1088
+ - id
684
1089
  seq:
685
1090
  type: boolean
686
1091
  description: >-
@@ -711,7 +1116,8 @@ components:
711
1116
  user_id:
712
1117
  type: string
713
1118
  description: Identifier of the user for whom the token is generated.
714
- example: jdoe
1119
+ examples:
1120
+ - jdoe # cspell:disable-line
715
1121
  _validity:
716
1122
  type: integer
717
1123
  description: Token lifetime in seconds (convenience key, removed before signing).
@@ -737,7 +1143,8 @@ components:
737
1143
  description: >-
738
1144
  Token expiry timestamp in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`).
739
1145
  Computed automatically from `_validity` when absent.
740
- example: "2030-01-01T00:00:00Z"
1146
+ examples:
1147
+ - "2030-01-01T00:00:00Z"
741
1148
  NodeEmulatorOptions:
742
1149
  type: object
743
1150
  description: >-
@@ -756,26 +1163,34 @@ components:
756
1163
  default: http://localhost:8080
757
1164
  cert:
758
1165
  type: string
1166
+ x-cli-complete: file
759
1167
  description: >-
760
1168
  Path to the TLS certificate file.
761
1169
  Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).
762
- example: /path/to/cert.pem
1170
+ examples:
1171
+ - /path/to/cert.pem
763
1172
  key:
764
1173
  type: string
1174
+ x-cli-complete: file
765
1175
  description: >-
766
1176
  Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.
767
- example: /path/to/key.pem
1177
+ examples:
1178
+ - /path/to/key.pem
768
1179
  chain:
769
1180
  type: string
1181
+ x-cli-complete: file
770
1182
  description: Path to the PEM certificate chain file (appended as extra chain certificates).
771
- example: /path/to/chain.pem
1183
+ examples:
1184
+ - /path/to/chain.pem
772
1185
  docroot:
773
1186
  type: string
1187
+ x-cli-complete: folder
774
1188
  description: >-
775
1189
  Local folder of the node files.
776
1190
  Paths of `/files/browse` and local paths of transfers (sources of `send`, destination of `receive`) are relative to it, and confined in it.
777
1191
  Defaults to the current working directory.
778
- example: /data/aspera
1192
+ examples:
1193
+ - /data/aspera
779
1194
  retention_sec:
780
1195
  type: integer
781
1196
  minimum: 1
@@ -788,13 +1203,15 @@ components:
788
1203
  Set together with `password`.
789
1204
  When not set, requests are accepted without authentication.
790
1205
  Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).
791
- example: node_user
1206
+ examples:
1207
+ - node_user
792
1208
  password:
793
1209
  type: string
794
1210
  description: >-
795
1211
  Password expected from clients in HTTP Basic authentication, for the above `username`.
796
1212
  Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).
797
- example: my_password
1213
+ examples:
1214
+ - "<PASSWORD>"
798
1215
  password_min_bits:
799
1216
  type: integer
800
1217
  minimum: 0
@@ -818,14 +1235,15 @@ components:
818
1235
  url:
819
1236
  type: string
820
1237
  description: Base URL of the Instana backend (without `/v1`).
821
- example: https://my-instana.example.com
1238
+ examples:
1239
+ - https://my-instana.example.com
822
1240
  key:
823
1241
  type: string
824
1242
  description: Instana API key sent in the `x-instana-key` header.
825
- example: my-instana-api-key
1243
+ examples:
1244
+ - my-instana-api-key
826
1245
  interval:
827
1246
  type: number
828
- format: float
829
1247
  description: >-
830
1248
  Polling interval in seconds. Use `0` for a single-shot run (no loop).
831
1249
  default: 10
@@ -834,7 +1252,8 @@ components:
834
1252
  description: >-
835
1253
  Value sent in the `x-instana-host` header.
836
1254
  Defaults to the local machine's hostname.
837
- example: hsts-prod-01
1255
+ examples:
1256
+ - hsts-prod-01
838
1257
  OrchestratorWorkflowStart:
839
1258
  type: object
840
1259
  description: >-
@@ -852,13 +1271,15 @@ components:
852
1271
  description: >-
853
1272
  Name of the work step providing the result.
854
1273
  Requires `variable`, and implies `synchronous`.
855
- example: ResultStep
1274
+ examples:
1275
+ - ResultStep
856
1276
  variable:
857
1277
  type: string
858
1278
  description: >-
859
1279
  Name of the output variable of `step` returned as result.
860
1280
  Requires `step`, and implies `synchronous`.
861
- example: Complete_status_message
1281
+ examples:
1282
+ - Complete_status_message
862
1283
  OrchestratorInitiateParameters:
863
1284
  type: object
864
1285
  description: >-
@@ -910,13 +1331,15 @@ components:
910
1331
  filename:
911
1332
  type: string
912
1333
  description: Path of the workflow file (`.yml` or `.wkf`) on the Orchestrator host.
913
- example: /opt/aspera/orchestrator/var/run/orchestrator/workflows/import/my_workflow.yml
1334
+ examples:
1335
+ - /opt/aspera/orchestrator/var/run/orchestrator/workflows/import/my_workflow.yml
914
1336
  add_as_revision:
915
- type: integer
1337
+ type: [integer, 'null']
916
1338
  description: >-
917
1339
  ID of an existing workflow: the file is imported as a new revision of this workflow (to be published).
918
- If not set, a new workflow is created.
919
- example: 123
1340
+ If not set, or `null`, a new workflow is created.
1341
+ examples:
1342
+ - 123
920
1343
  subwf_constraints:
921
1344
  type: object
922
1345
  description: 'Resolution for each sub-workflow, by name: `Map to the Existing Sub-Workflow`, `Create a new Sub-Workflow with a unique name`, or `Add a new revision to the existing Sub-Workflow`.'
@@ -959,9 +1382,66 @@ components:
959
1382
  description: List of plugin names to reload.
960
1383
  items:
961
1384
  type: string
962
- example:
963
- - soap_requests
964
- - frameio_operations
1385
+ examples:
1386
+ - - soap_requests
1387
+ - frameio_operations # cspell:disable-line
1388
+ DetectOptions:
1389
+ type: object
1390
+ description: Application to detect (`config detect`).
1391
+ additionalProperties: false
1392
+ properties:
1393
+ url:
1394
+ type: string
1395
+ description: URL of the application. Asked interactively if not provided.
1396
+ examples:
1397
+ - https://app.example.com/aspera/app
1398
+ plugin:
1399
+ type: string
1400
+ description: 'Check only this plugin (default: all plugins).'
1401
+ examples:
1402
+ - aoc
1403
+ PresetLookupCriteria:
1404
+ type: object
1405
+ description: Criteria to find a preset (`config preset lookup`).
1406
+ additionalProperties: false
1407
+ required:
1408
+ - url
1409
+ - username
1410
+ properties:
1411
+ url:
1412
+ type: string
1413
+ description: URL of the application, compared with option `url` of presets.
1414
+ examples:
1415
+ - https://app.example.com/aspera/app
1416
+ username:
1417
+ type: string
1418
+ description: User name (or access key), compared with option `username` of presets.
1419
+ WizardOptions:
1420
+ type: object
1421
+ description: Application to configure with the wizard (`config wizard`). Options of the plugin (e.g. `--username`, `--password`, `--client-id`, `--private-key`) are given on the command line.
1422
+ additionalProperties: false
1423
+ properties:
1424
+ url:
1425
+ type: string
1426
+ description: URL of the application. Asked interactively if not provided.
1427
+ examples:
1428
+ - https://app.example.com/aspera/app
1429
+ plugin:
1430
+ type: string
1431
+ description: 'Check only this plugin (default: all plugins).'
1432
+ examples:
1433
+ - aoc
1434
+ preset:
1435
+ type: string
1436
+ description: 'Name of the preset to create (default: generated from the product, URL and user).'
1437
+ examples:
1438
+ - my_preset
1439
+ override:
1440
+ type: boolean
1441
+ description: 'Override the existing default preset of the plugin, if it exists (default: no).'
1442
+ default:
1443
+ type: boolean
1444
+ description: 'Set the preset as default configuration for the plugin (default: yes).'
965
1445
  TableOptions:
966
1446
  type: object
967
1447
  description: Terminal table rendering options.
@@ -986,6 +1466,8 @@ components:
986
1466
  default: data
987
1467
  file:
988
1468
  type: string
1469
+ x-cli-complete: file
1470
+ x-security: low
989
1471
  description: Destination file for results (use `-` for stdout).
990
1472
  fields:
991
1473
  description: >-
@@ -1024,6 +1506,74 @@ components:
1024
1506
  Default is auto-detected: enabled if stdout is a terminal and the locale is UTF-8, or on Windows, the terminal renders Unicode (e.g. Windows Terminal, VS Code).
1025
1507
  img:
1026
1508
  $ref: "#/components/schemas/ImageOptions"
1509
+ PollOptions:
1510
+ type: object
1511
+ description: >-
1512
+ Repeat a read-only command (e.g. `list`, `show`, `status`) and display its result,
1513
+ until a condition is met, or a number of runs or a time is reached.
1514
+ The command runs first immediately, then again `interval` seconds after the end of each run.
1515
+ Without `max`, `timeout` and `until`, it runs until interrupted (Ctrl-C).
1516
+ Refused on a command that changes state (e.g. `send`, `create`, `delete`, `start`), before anything is executed.
1517
+ Formatting options (`--format`, `--fields`, `--out.query`) apply to each result displayed.
1518
+ A short status line on `stderr` gives the run number and the time before each result displayed.
1519
+ By default, an error of a run (e.g. an API error) ends the command with that error (see `errors`).
1520
+ additionalProperties: false
1521
+ properties:
1522
+ interval:
1523
+ oneOf:
1524
+ - type: number
1525
+ minimum: 0
1526
+ - type: string
1527
+ description: >-
1528
+ Time to wait after a run, before the next one.
1529
+ A duration: a number of seconds, or a `String`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00` (rounded down to seconds).
1530
+ default: 5
1531
+ max:
1532
+ type: integer
1533
+ minimum: 1
1534
+ description: Maximum number of runs. No limit by default.
1535
+ timeout:
1536
+ oneOf:
1537
+ - type: number
1538
+ minimum: 0
1539
+ - type: string
1540
+ description: >-
1541
+ Maximum time since the start of the first run.
1542
+ A duration, as `interval`, e.g. `600`, `10m`, `1h`.
1543
+ A last run occurs at this time. No limit by default.
1544
+ With `max`, polling stops at the first limit reached.
1545
+ until:
1546
+ type: string
1547
+ description: >-
1548
+ JMESPath expression (https://jmespath.org) evaluated on the JSON view of the result data:
1549
+ after `--select` (for a list of objects), before `--fields` and `--out.query`.
1550
+ 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.
1551
+ So `@` (the data itself) waits for a non-empty result, e.g. a list with at least one item.
1552
+ The syntax is checked before the first run.
1553
+ If the condition is not met after the last run (`max` or `timeout`), the command fails (exit code 1).
1554
+ show:
1555
+ type: string
1556
+ description: >-
1557
+ Which results are displayed.
1558
+
1559
+ - `change`: the first result, then each result whose display differs from the previous one.
1560
+
1561
+ - `each`: every result.
1562
+
1563
+ - `last`: only the last result, when polling stops (including when the condition is not met).
1564
+ enum: [change, each, last]
1565
+ default: change
1566
+ errors:
1567
+ type: string
1568
+ description: >-
1569
+ What an error of a run does (e.g. an API error, an entity not found yet).
1570
+
1571
+ - `fail`: the command ends with this error.
1572
+
1573
+ - `retry`: the error is shown on the status line, and the command runs again, as for a result where `until` is false.
1574
+ If the last run fails, the command ends with its error.
1575
+ enum: [fail, retry]
1576
+ default: fail
1027
1577
  WebServerOptions:
1028
1578
  type: object
1029
1579
  description: >-
@@ -1039,19 +1589,25 @@ components:
1039
1589
  default: http://localhost:8080
1040
1590
  cert:
1041
1591
  type: string
1592
+ x-cli-complete: file
1042
1593
  description: >-
1043
1594
  Path to the TLS certificate file.
1044
1595
  Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).
1045
- example: /path/to/cert.pem
1596
+ examples:
1597
+ - /path/to/cert.pem
1046
1598
  key:
1047
1599
  type: string
1600
+ x-cli-complete: file
1048
1601
  description: >-
1049
1602
  Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.
1050
- example: /path/to/key.pem
1603
+ examples:
1604
+ - /path/to/key.pem
1051
1605
  chain:
1052
1606
  type: string
1607
+ x-cli-complete: file
1053
1608
  description: Path to the PEM certificate chain file (appended as extra chain certificates).
1054
- example: /path/to/chain.pem
1609
+ examples:
1610
+ - /path/to/chain.pem
1055
1611
  Faspex4GatewayOptions:
1056
1612
  description: >-
1057
1613
  Configuration for the Faspex 4 gateway emulator (`faspex5 gateway`, `aoc gateway`).
@@ -1078,13 +1634,15 @@ components:
1078
1634
  Set together with `password`.
1079
1635
  When not set, requests are accepted without authentication.
1080
1636
  Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).
1081
- example: fx4_user
1637
+ examples:
1638
+ - fx4_user
1082
1639
  password:
1083
1640
  type: string
1084
1641
  description: >-
1085
1642
  Password expected from clients in HTTP Basic authentication, for the above `username`.
1086
1643
  Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).
1087
- example: my_password
1644
+ examples:
1645
+ - "<PASSWORD>"
1088
1646
  password_min_bits:
1089
1647
  type: integer
1090
1648
  minimum: 0
@@ -1115,11 +1673,13 @@ components:
1115
1673
  chain: {}
1116
1674
  script_folder:
1117
1675
  type: string
1676
+ x-cli-complete: folder
1118
1677
  description: >-
1119
1678
  Folder containing the post-processing scripts.
1120
1679
  The URL path (after the base path) is appended to this folder to locate the script to execute.
1121
1680
  default: "."
1122
- example: /opt/faspex/scripts
1681
+ examples:
1682
+ - /opt/faspex/scripts
1123
1683
  fail_on_error:
1124
1684
  type: boolean
1125
1685
  description: >-
@@ -1160,10 +1720,11 @@ components:
1160
1720
  This parameter or `secret_token` is required when `url` is not a local address.
1161
1721
  oneOf:
1162
1722
  - type: string
1163
- example: "192.168.1.10"
1723
+ examples:
1724
+ - "192.168.1.10"
1164
1725
  - type: array
1165
1726
  items:
1166
1727
  type: string
1167
- example:
1168
- - "192.168.1.10"
1169
- - "10.89.0.0/24"
1728
+ examples:
1729
+ - - "192.168.1.10"
1730
+ - "10.89.0.0/24"