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.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/BUGS.md +5 -10
- data/CHANGELOG.md +217 -2
- data/CODE_OF_CONDUCT.md +18 -0
- data/CONTRIBUTING.md +135 -56
- data/GOVERNANCE.md +30 -0
- data/LICENSE +201 -0
- data/README.md +122 -26
- data/SECURITY.md +84 -0
- data/bin/ascli +8 -5
- data/bin/asession +9 -6
- data/docs/README.md +1895 -632
- data/docs/test-mcp-with-ai.md +8 -8
- data/lib/aspera/agent/base.rb +23 -2
- data/lib/aspera/agent/connect.rb +16 -12
- data/lib/aspera/agent/desktop.rb +10 -7
- data/lib/aspera/agent/direct.rb +20 -19
- data/lib/aspera/agent/factory.rb +6 -3
- data/lib/aspera/agent/httpgw.rb +7 -5
- data/lib/aspera/agent/node.rb +15 -7
- data/lib/aspera/agent/transferd.rb +167 -43
- data/lib/aspera/api/alee.rb +4 -1
- data/lib/aspera/api/aoc.rb +14 -11
- data/lib/aspera/api/ats.rb +4 -2
- data/lib/aspera/api/cos_node.rb +7 -4
- data/lib/aspera/api/faspex.rb +16 -9
- data/lib/aspera/api/httpgw.rb +9 -6
- data/lib/aspera/api/node.rb +29 -22
- data/lib/aspera/ascmd.rb +8 -5
- data/lib/aspera/ascp/installation.rb +95 -67
- data/lib/aspera/ascp/log.schema.yaml +1084 -0
- data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
- data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
- data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
- data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
- data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
- data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
- data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
- data/lib/aspera/ascp/log_analyzer.rb +370 -0
- data/lib/aspera/ascp/log_locations.rb +163 -0
- data/lib/aspera/ascp/management.rb +16 -8
- data/lib/aspera/ascp/session_errors.rb +217 -0
- data/lib/aspera/assert.rb +4 -0
- data/lib/aspera/cli/ascp_actions.rb +12 -19
- data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
- data/lib/aspera/cli/async_transfer_store.rb +7 -4
- data/lib/aspera/cli/bootstrapper.rb +38 -33
- data/lib/aspera/cli/command_line.rb +63 -8
- data/lib/aspera/cli/command_registry.rb +9 -1
- data/lib/aspera/cli/command_spec.rb +47 -7
- data/lib/aspera/cli/completion/ascli.bash +19 -5
- data/lib/aspera/cli/completion/ascli.fish +13 -2
- data/lib/aspera/cli/completion/ascli.ps1 +31 -9
- data/lib/aspera/cli/completion/ascli.zsh +22 -6
- data/lib/aspera/cli/completion_actions.rb +303 -69
- data/lib/aspera/cli/context.rb +9 -4
- data/lib/aspera/cli/deprecation.rb +5 -2
- data/lib/aspera/cli/error.rb +6 -0
- data/lib/aspera/cli/extended_value.rb +66 -31
- data/lib/aspera/cli/formatter.rb +43 -30
- data/lib/aspera/cli/gem_checker.rb +9 -6
- data/lib/aspera/cli/hints.rb +22 -10
- data/lib/aspera/cli/http.rb +38 -10
- data/lib/aspera/cli/info.rb +12 -7
- data/lib/aspera/cli/mailer.rb +6 -3
- data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
- data/lib/aspera/cli/mcp/secrets.rb +8 -5
- data/lib/aspera/cli/mcp/tool.rb +20 -17
- data/lib/aspera/cli/option_declarator.rb +10 -4
- data/lib/aspera/cli/option_registry.rb +6 -3
- data/lib/aspera/cli/option_types.rb +17 -2
- data/lib/aspera/cli/option_value.rb +77 -18
- data/lib/aspera/cli/options.schema.yaml +641 -80
- data/lib/aspera/cli/parser.rb +71 -35
- data/lib/aspera/cli/plugins/alee.rb +7 -4
- data/lib/aspera/cli/plugins/aoc.rb +248 -37
- data/lib/aspera/cli/plugins/ats.rb +10 -9
- data/lib/aspera/cli/plugins/base.rb +50 -18
- data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
- data/lib/aspera/cli/plugins/config.rb +210 -104
- data/lib/aspera/cli/plugins/console.rb +6 -3
- data/lib/aspera/cli/plugins/cos.rb +8 -4
- data/lib/aspera/cli/plugins/factory.rb +21 -7
- data/lib/aspera/cli/plugins/faspex5.rb +31 -26
- data/lib/aspera/cli/plugins/faspio.rb +7 -5
- data/lib/aspera/cli/plugins/httpgw.rb +7 -4
- data/lib/aspera/cli/plugins/mcp.rb +42 -22
- data/lib/aspera/cli/plugins/node.rb +39 -38
- data/lib/aspera/cli/plugins/oauth.rb +23 -6
- data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
- data/lib/aspera/cli/plugins/preview.rb +72 -45
- data/lib/aspera/cli/plugins/server.rb +66 -14
- data/lib/aspera/cli/plugins/shares.rb +87 -18
- data/lib/aspera/cli/plugins/transferd.rb +228 -0
- data/lib/aspera/cli/poll.rb +236 -0
- data/lib/aspera/cli/preset_actions.rb +144 -30
- data/lib/aspera/cli/preset_manager.rb +113 -35
- data/lib/aspera/cli/prompt.rb +157 -9
- data/lib/aspera/cli/result.rb +12 -8
- data/lib/aspera/cli/runner.rb +89 -48
- data/lib/aspera/cli/secret_finder.rb +4 -1
- data/lib/aspera/cli/security.rb +89 -9
- data/lib/aspera/cli/special_values.rb +4 -1
- data/lib/aspera/cli/sync_actions.rb +15 -10
- data/lib/aspera/cli/table_fitter.rb +3 -0
- data/lib/aspera/cli/terminal_formatter.rb +9 -6
- data/lib/aspera/cli/transfer_actions.rb +11 -8
- data/lib/aspera/cli/transfer_agent.rb +43 -20
- data/lib/aspera/cli/transfer_progress.rb +14 -45
- data/lib/aspera/cli/vault_actions.rb +45 -0
- data/lib/aspera/cli/vault_manager.rb +188 -42
- data/lib/aspera/cli/version.rb +4 -1
- data/lib/aspera/cli/web_secret.rb +12 -10
- data/lib/aspera/cli/wizard.rb +42 -39
- data/lib/aspera/command_line_builder.rb +9 -5
- data/lib/aspera/command_line_converter.rb +4 -1
- data/lib/aspera/coverage.rb +103 -33
- data/lib/aspera/data_repository.rb +4 -1
- data/lib/aspera/dot_container.rb +4 -1
- data/lib/aspera/environment.rb +23 -12
- data/lib/aspera/exec_spec.rb +3 -0
- data/lib/aspera/faspex_gw.rb +13 -9
- data/lib/aspera/faspex_postproc.rb +15 -12
- data/lib/aspera/formatter_interface.rb +4 -1
- data/lib/aspera/graphql.rb +5 -1
- data/lib/aspera/hash_ext.rb +3 -0
- data/lib/aspera/id_generator.rb +20 -5
- data/lib/aspera/inflate.rb +43 -0
- data/lib/aspera/json_rpc/client.rb +6 -5
- data/lib/aspera/json_rpc/version.rb +3 -0
- data/lib/aspera/line_logger.rb +4 -1
- data/lib/aspera/link_header.rb +4 -1
- data/lib/aspera/log.rb +18 -5
- data/lib/aspera/markdown.rb +5 -2
- data/lib/aspera/mime.rb +3 -0
- data/lib/aspera/nagios.rb +6 -4
- data/lib/aspera/node_emulator.rb +15 -13
- data/lib/aspera/oauth/client/base.rb +124 -73
- data/lib/aspera/oauth/client/boot.rb +7 -4
- data/lib/aspera/oauth/client/factory.rb +41 -18
- data/lib/aspera/oauth/client/generic.rb +5 -1
- data/lib/aspera/oauth/client/json_credentials.rb +7 -3
- data/lib/aspera/oauth/client/jwt.rb +6 -3
- data/lib/aspera/oauth/client/shares_web.rb +94 -0
- data/lib/aspera/oauth/client/url_json.rb +7 -3
- data/lib/aspera/oauth/client/web.rb +40 -13
- data/lib/aspera/oauth/server/pkce.rb +6 -5
- data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
- data/lib/aspera/persistency_action_once.rb +5 -3
- data/lib/aspera/persistency_folder.rb +6 -3
- data/lib/aspera/preview/file_types.rb +6 -3
- data/lib/aspera/preview/generator.rb +9 -5
- data/lib/aspera/preview/options.schema.yaml +3 -3
- data/lib/aspera/preview/terminal.rb +16 -6
- data/lib/aspera/preview/utils.rb +6 -4
- data/lib/aspera/products/connect.rb +5 -2
- data/lib/aspera/products/desktop.rb +17 -2
- data/lib/aspera/products/other.rb +4 -2
- data/lib/aspera/products/transferd.rb +6 -2
- data/lib/aspera/products/transferd_service.rb +610 -0
- data/lib/aspera/proxy_auto_config.js +2 -2
- data/lib/aspera/proxy_auto_config.rb +5 -2
- data/lib/aspera/rainbow.rb +3 -0
- data/lib/aspera/rest/aspera_errors.rb +4 -1
- data/lib/aspera/rest/call_error.rb +3 -0
- data/lib/aspera/rest/client.rb +45 -34
- data/lib/aspera/rest/error_analyzer.rb +5 -2
- data/lib/aspera/rest/list.rb +8 -4
- data/lib/aspera/rest/parameters.rb +3 -0
- data/lib/aspera/rest/util.rb +8 -5
- data/lib/aspera/rest.rb +9 -6
- data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
- data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
- data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
- data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
- data/lib/aspera/schema/async_tables.yaml +11 -10
- data/lib/aspera/schema/documentation.rb +8 -2
- data/lib/aspera/schema/reader.rb +7 -0
- data/lib/aspera/schema/registry.rb +44 -28
- data/lib/aspera/schema/transferd-config.schema.json +333 -0
- data/lib/aspera/schema/validator.rb +4 -1
- data/lib/aspera/sealed_hash.rb +150 -0
- data/lib/aspera/secret/hider.rb +213 -0
- data/lib/aspera/secret/reference.rb +150 -0
- data/lib/aspera/secret/resolver.rb +212 -0
- data/lib/aspera/secret/store/base.rb +153 -0
- data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
- data/lib/aspera/secret/store/factory.rb +103 -0
- data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
- data/lib/aspera/secret/store/keeper.rb +141 -0
- data/lib/aspera/secret/store/macos_security.rb +284 -0
- data/lib/aspera/secret/store/one_password_api.rb +99 -0
- data/lib/aspera/secret/store/one_password_base.rb +42 -0
- data/lib/aspera/secret/store/one_password_cli.rb +112 -0
- data/lib/aspera/secret/store/secret_service.rb +125 -0
- data/lib/aspera/secret/strength.rb +119 -0
- data/lib/aspera/servlet_helpers.rb +5 -2
- data/lib/aspera/ssh.rb +10 -7
- data/lib/aspera/ssl.rb +5 -2
- data/lib/aspera/string_ext.rb +3 -0
- data/lib/aspera/sync/args.schema.yaml +3 -0
- data/lib/aspera/sync/conf.schema.yaml +9 -4
- data/lib/aspera/sync/database.rb +3 -0
- data/lib/aspera/sync/operations.rb +17 -15
- data/lib/aspera/temp_file_manager.rb +8 -4
- data/lib/aspera/timer_limiter.rb +3 -0
- data/lib/aspera/transfer/error.rb +4 -1
- data/lib/aspera/transfer/faux_file.rb +4 -1
- data/lib/aspera/transfer/parameters.rb +17 -14
- data/lib/aspera/transfer/result.rb +23 -0
- data/lib/aspera/transfer/resumer.rb +6 -4
- data/lib/aspera/transfer/spec.rb +9 -22
- data/lib/aspera/units/decimal.rb +67 -0
- data/lib/aspera/units/duration.rb +109 -0
- data/lib/aspera/uri_reader.rb +64 -9
- data/lib/aspera/web_auth/index.html.erb +6 -2
- data/lib/aspera/web_auth/paste.rb +109 -0
- data/lib/aspera/web_auth/receiver.rb +50 -0
- data/lib/aspera/web_auth/relay.rb +76 -0
- data/lib/aspera/web_auth/reply.html.erb +150 -0
- data/lib/aspera/web_auth/server.rb +47 -10
- data/lib/aspera/web_page.rb +7 -2
- data/lib/aspera/web_server_simple.rb +6 -3
- data/lib/aspera/yaml.rb +5 -1
- data/llms-install.md +88 -0
- data/llms.txt +87 -0
- data/skills/ascli/SKILL.md +94 -0
- data.tar.gz.sig +0 -0
- metadata +77 -20
- metadata.gz.sig +0 -0
- data/lib/aspera/duration.rb +0 -42
- data/lib/aspera/keychain/base.rb +0 -30
- data/lib/aspera/keychain/encrypted_hash.rb +0 -192
- data/lib/aspera/keychain/factory.rb +0 -58
- data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
- data/lib/aspera/keychain/macos_security.rb +0 -277
- data/lib/aspera/keychain/one_password_api.rb +0 -91
- data/lib/aspera/keychain/one_password_base.rb +0 -39
- data/lib/aspera/keychain/one_password_cli.rb +0 -100
- data/lib/aspera/secret_hider.rb +0 -196
- data/lib/aspera/secret_strength.rb +0 -114
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
<%# Content of the page displayed after login when the reply is given to the user, to paste in the terminal of ascli, in layout of Aspera::WebPage. Variables: additional_info, code, nonce %>
|
|
2
|
+
<style>
|
|
3
|
+
.code-box {
|
|
4
|
+
display: flex;
|
|
5
|
+
align-items: stretch;
|
|
6
|
+
gap: 0.5rem;
|
|
7
|
+
margin-top: 1.25rem;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
.code {
|
|
11
|
+
flex: 1;
|
|
12
|
+
min-width: 0;
|
|
13
|
+
padding: 0.6rem 0.75rem;
|
|
14
|
+
text-align: left;
|
|
15
|
+
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
|
|
16
|
+
font-size: 0.8rem;
|
|
17
|
+
line-height: 1.4;
|
|
18
|
+
letter-spacing: 0.05em;
|
|
19
|
+
word-break: break-all;
|
|
20
|
+
max-height: 9rem;
|
|
21
|
+
overflow-y: auto;
|
|
22
|
+
background: var(--surface);
|
|
23
|
+
color: var(--text);
|
|
24
|
+
border: 1px solid var(--border);
|
|
25
|
+
border-radius: 6px;
|
|
26
|
+
user-select: none;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
.code.revealed {
|
|
30
|
+
user-select: all;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
.code-box button.icon {
|
|
34
|
+
flex: none;
|
|
35
|
+
width: 2.75rem;
|
|
36
|
+
padding: 0;
|
|
37
|
+
display: flex;
|
|
38
|
+
align-items: center;
|
|
39
|
+
justify-content: center;
|
|
40
|
+
background: var(--card-bg);
|
|
41
|
+
color: var(--text-secondary);
|
|
42
|
+
border: 1px solid var(--input-border);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
.code-box button.icon:hover {
|
|
46
|
+
color: var(--accent);
|
|
47
|
+
border-color: var(--accent);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
.code-box button.icon svg.hide,
|
|
51
|
+
.code-box button.icon.on svg.show {
|
|
52
|
+
display: none;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
.code-box button.icon.on svg.hide {
|
|
56
|
+
display: block;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
.status {
|
|
60
|
+
min-height: 1.4rem;
|
|
61
|
+
font-size: 0.85rem;
|
|
62
|
+
color: var(--success);
|
|
63
|
+
}
|
|
64
|
+
</style>
|
|
65
|
+
|
|
66
|
+
<div class="icon-circle ok">
|
|
67
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
|
|
68
|
+
<polyline points="6 16 13 23 26 9"/>
|
|
69
|
+
</svg>
|
|
70
|
+
</div>
|
|
71
|
+
|
|
72
|
+
<h1>Login Complete</h1>
|
|
73
|
+
<p>Copy this code, and paste it in the terminal where <b>ascli</b> waits for it. This code is valid for <%= Aspera::SealedHash::PERIOD / 60 %> minutes. You can then close this window.</p>
|
|
74
|
+
|
|
75
|
+
<% unless additional_info.to_s.empty? %>
|
|
76
|
+
<div class="info-box">
|
|
77
|
+
<%= h additional_info %>
|
|
78
|
+
</div>
|
|
79
|
+
<% end %>
|
|
80
|
+
|
|
81
|
+
<div class="code-box">
|
|
82
|
+
<div id="code" class="code" aria-live="polite">••••••••••••••••••••</div>
|
|
83
|
+
<button type="button" id="reveal" class="icon" title="Show the code" aria-label="Show the code" aria-pressed="false">
|
|
84
|
+
<svg class="show" xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
|
85
|
+
<path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/>
|
|
86
|
+
<circle cx="12" cy="12" r="3"/>
|
|
87
|
+
</svg>
|
|
88
|
+
<svg class="hide" xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
|
89
|
+
<path d="M17.94 17.94A10.07 10.07 0 0 1 12 20c-7 0-11-8-11-8a18.45 18.45 0 0 1 5.06-5.94M9.9 4.24A9.12 9.12 0 0 1 12 4c7 0 11 8 11 8a18.5 18.5 0 0 1-2.16 3.19m-6.72-1.07a3 3 0 1 1-4.24-4.24"/>
|
|
90
|
+
<line x1="1" y1="1" x2="23" y2="23"/>
|
|
91
|
+
</svg>
|
|
92
|
+
</button>
|
|
93
|
+
</div>
|
|
94
|
+
<div class="actions">
|
|
95
|
+
<button type="button" id="copy" class="allow">Copy</button>
|
|
96
|
+
</div>
|
|
97
|
+
<p id="status" class="status" role="status"></p>
|
|
98
|
+
|
|
99
|
+
<%# The code is in this script only, not in the page: it is inserted in the page when the user shows it %>
|
|
100
|
+
<script nonce="<%= h nonce %>">
|
|
101
|
+
(function () {
|
|
102
|
+
var code = <%= JSON.generate(code.to_s).gsub('<', '\u003c') %>;
|
|
103
|
+
var box = document.getElementById('code');
|
|
104
|
+
var mask = box.textContent;
|
|
105
|
+
var reveal = document.getElementById('reveal');
|
|
106
|
+
var status = document.getElementById('status');
|
|
107
|
+
var shown = false;
|
|
108
|
+
|
|
109
|
+
reveal.addEventListener('click', function () {
|
|
110
|
+
shown = !shown;
|
|
111
|
+
box.textContent = shown ? code : mask;
|
|
112
|
+
box.classList.toggle('revealed', shown);
|
|
113
|
+
reveal.classList.toggle('on', shown);
|
|
114
|
+
reveal.setAttribute('aria-pressed', shown ? 'true' : 'false');
|
|
115
|
+
var label = shown ? 'Hide the code' : 'Show the code';
|
|
116
|
+
reveal.title = label;
|
|
117
|
+
reveal.setAttribute('aria-label', label);
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
function legacyCopy() {
|
|
121
|
+
var area = document.createElement('textarea');
|
|
122
|
+
area.value = code;
|
|
123
|
+
area.setAttribute('readonly', '');
|
|
124
|
+
area.style.position = 'fixed';
|
|
125
|
+
area.style.opacity = '0';
|
|
126
|
+
document.body.appendChild(area);
|
|
127
|
+
area.select();
|
|
128
|
+
var ok = false;
|
|
129
|
+
try { ok = document.execCommand('copy'); } catch (e) { ok = false; }
|
|
130
|
+
document.body.removeChild(area);
|
|
131
|
+
return ok;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function done(ok) {
|
|
135
|
+
status.style.color = ok ? '' : 'var(--danger)';
|
|
136
|
+
status.textContent = ok ? 'Copied. Paste it in the terminal.' : 'Copy failed: show the code, select it and copy it.';
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
document.getElementById('copy').addEventListener('click', function () {
|
|
140
|
+
if (navigator.clipboard && window.isSecureContext) {
|
|
141
|
+
navigator.clipboard.writeText(code).then(function () { done(true); }, function () { done(legacyCopy()); });
|
|
142
|
+
} else {
|
|
143
|
+
done(legacyCopy());
|
|
144
|
+
}
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
// The callback URL contains a code or tokens: remove the query from the address bar and from the entry of the session history
|
|
148
|
+
if (window.history && history.replaceState) history.replaceState(null, '', location.pathname);
|
|
149
|
+
})();
|
|
150
|
+
</script>
|
|
@@ -1,9 +1,16 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
# SPDX-FileCopyrightText: IBM Corp.
|
|
4
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
5
|
+
|
|
6
|
+
require_relative '../web_server_simple'
|
|
7
|
+
require_relative '../servlet_helpers'
|
|
8
|
+
require_relative '../web_page'
|
|
9
|
+
require_relative '../sealed_hash'
|
|
10
|
+
require_relative '../cli/info'
|
|
11
|
+
require_relative '../assert'
|
|
12
|
+
require 'json'
|
|
13
|
+
require 'securerandom'
|
|
7
14
|
|
|
8
15
|
module Aspera
|
|
9
16
|
module WebAuth
|
|
@@ -13,7 +20,11 @@ module Aspera
|
|
|
13
20
|
|
|
14
21
|
# ERB template of page displayed in browser after authentication
|
|
15
22
|
HTML_TEMPLATE_PATH = File.join(__dir__, 'index.html.erb')
|
|
16
|
-
|
|
23
|
+
# ERB template of page displayed in browser after authentication, when the reply is given to the user to paste in a terminal
|
|
24
|
+
REPLY_TEMPLATE_PATH = File.join(__dir__, 'reply.html.erb')
|
|
25
|
+
# Policy of the reply page: it has a secret. Only its own script (with nonce) and style, nothing external
|
|
26
|
+
REPLY_CSP = "default-src 'none'; img-src data:; style-src 'unsafe-inline'; script-src 'nonce-%<nonce>s'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
|
|
27
|
+
private_constant :HTML_TEMPLATE_PATH, :REPLY_TEMPLATE_PATH, :REPLY_CSP
|
|
17
28
|
|
|
18
29
|
# @param server [WEBrick::HTTPServer] the HTTP server instance
|
|
19
30
|
# @param web_auth [Server] the Server instance to record the callback
|
|
@@ -33,25 +44,42 @@ module Aspera
|
|
|
33
44
|
Aspera.assert_values(request.path, [@web_auth.expected_path], type: WEBrick::HTTPStatus::NotFound) { "Unsupported path: #{request.path}" }
|
|
34
45
|
# response to browser
|
|
35
46
|
response.status = 200
|
|
36
|
-
|
|
37
|
-
|
|
47
|
+
if @web_auth.reply_keys.nil?
|
|
48
|
+
WebPage.secure_headers(response)
|
|
49
|
+
response.body = WebPage.render(HTML_TEMPLATE_PATH, title: 'Authentication Complete', additional_info: @web_auth.additional_info)
|
|
50
|
+
else
|
|
51
|
+
render_reply(request, response)
|
|
52
|
+
end
|
|
38
53
|
# continue internal processing
|
|
39
54
|
@web_auth.signal_request(request)
|
|
40
55
|
nil
|
|
41
56
|
end
|
|
57
|
+
|
|
58
|
+
private
|
|
59
|
+
|
|
60
|
+
# Page that gives the reply to the user: the code to paste in the terminal of the remote ascli
|
|
61
|
+
def render_reply(request, response)
|
|
62
|
+
nonce = SecureRandom.base64(16)
|
|
63
|
+
WebPage.secure_headers(response, content_security_policy: format(REPLY_CSP, nonce: nonce))
|
|
64
|
+
code = SealedHash.seal(request.query.slice(*@web_auth.reply_keys).transform_values(&:to_s), base_key: Cli::Info::CMD_NAME)
|
|
65
|
+
response.body = WebPage.render(REPLY_TEMPLATE_PATH, title: 'Login Complete', additional_info: @web_auth.additional_info, code: code, nonce: nonce)
|
|
66
|
+
end
|
|
42
67
|
end
|
|
43
68
|
|
|
44
69
|
# start a local web server
|
|
45
70
|
# then start a browser that will callback the local server upon authentication
|
|
46
71
|
# store the final query
|
|
47
72
|
class Server < WebServerSimple
|
|
48
|
-
|
|
73
|
+
# @return [Array<String>, nil] Keys of the query that the page gives to the user as a code to paste in a terminal, `nil` for the standard page
|
|
74
|
+
attr_reader :additional_info, :expected_path, :reply_keys
|
|
49
75
|
|
|
50
76
|
# @param endpoint_url [String] e.g. 'https://127.0.0.1:12345'
|
|
51
77
|
# @param additional_info [String] Information in web page
|
|
52
|
-
|
|
78
|
+
# @param reply_keys [Array<String>, nil] If set, the page shows to the user a code with these keys of the query, to paste in the terminal of `ascli` that waits for it
|
|
79
|
+
def initialize(endpoint_url, additional_info = nil, reply_keys: nil)
|
|
53
80
|
uri = URI.parse(endpoint_url)
|
|
54
81
|
super(uri)
|
|
82
|
+
@reply_keys = reply_keys
|
|
55
83
|
@mutex = Mutex.new
|
|
56
84
|
@cond = ConditionVariable.new
|
|
57
85
|
@expected_path = uri.path.empty? ? '/' : uri.path
|
|
@@ -60,7 +88,16 @@ module Aspera
|
|
|
60
88
|
# last argument (self) is provided to constructor of servlet
|
|
61
89
|
mount(@expected_path, Servlet, self)
|
|
62
90
|
# server runs in thread
|
|
63
|
-
Thread.new { start }
|
|
91
|
+
@thread = Thread.new { start }
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
# Wait until the server thread has ended: the response of the last request (page shown to the user) is sent.
|
|
95
|
+
# To call after `received_request`, when the process does not continue with a long operation.
|
|
96
|
+
# @param timeout [Integer] Maximum time to wait, in seconds
|
|
97
|
+
# @return [nil]
|
|
98
|
+
def wait_stopped(timeout = 10)
|
|
99
|
+
@thread.join(timeout)
|
|
100
|
+
nil
|
|
64
101
|
end
|
|
65
102
|
|
|
66
103
|
# Called by web server thread on received request
|
data/lib/aspera/web_page.rb
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
# SPDX-FileCopyrightText: IBM Corp.
|
|
4
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
5
|
+
|
|
3
6
|
require 'erb'
|
|
4
7
|
|
|
5
8
|
module Aspera
|
|
@@ -41,10 +44,12 @@ module Aspera
|
|
|
41
44
|
|
|
42
45
|
class << self
|
|
43
46
|
# Set the headers of an HTML page: type and security headers
|
|
44
|
-
# @param response
|
|
47
|
+
# @param response [WEBrick::HTTPResponse]
|
|
48
|
+
# @param content_security_policy [String, nil] Policy that replaces the default one, e.g. to allow a script of the page
|
|
45
49
|
# @return [nil]
|
|
46
|
-
def secure_headers(response)
|
|
50
|
+
def secure_headers(response, content_security_policy: nil)
|
|
47
51
|
HEADERS.each { |name, value| response[name] = value }
|
|
52
|
+
response['Content-Security-Policy'] = content_security_policy unless content_security_policy.nil?
|
|
48
53
|
nil
|
|
49
54
|
end
|
|
50
55
|
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
# SPDX-FileCopyrightText: IBM Corp.
|
|
4
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
5
|
+
|
|
6
|
+
require_relative 'log'
|
|
7
|
+
require_relative 'assert'
|
|
8
|
+
require_relative 'hash_ext'
|
|
3
9
|
require 'delegate'
|
|
4
10
|
require 'ipaddr'
|
|
5
11
|
require 'webrick'
|
|
6
|
-
require 'aspera/log'
|
|
7
|
-
require 'aspera/assert'
|
|
8
|
-
require 'aspera/hash_ext'
|
|
9
12
|
|
|
10
13
|
module Aspera
|
|
11
14
|
# Simple WEBrick server with HTTPS support
|
data/lib/aspera/yaml.rb
CHANGED
data/llms-install.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Install the IBM Aspera CLI MCP server
|
|
2
|
+
|
|
3
|
+
Instructions for an AI agent that installs and configures the MCP server of `ascli` (IBM Aspera CLI) for an MCP client.
|
|
4
|
+
Details: [MCP client configuration](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#mcp-client-configuration) in the manual.
|
|
5
|
+
|
|
6
|
+
## 1. Check Ruby
|
|
7
|
+
|
|
8
|
+
```shell
|
|
9
|
+
ruby -v
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Ruby 3.3 or later is required.
|
|
13
|
+
If Ruby is missing or older, install it first (macOS: `brew install ruby`, Linux: the distribution package or `rbenv`, Windows: RubyInstaller).
|
|
14
|
+
|
|
15
|
+
## 2. Install the gems
|
|
16
|
+
|
|
17
|
+
Install the published gem from RubyGems, with the optional gem `mcp` (required for `ascli mcp server`).
|
|
18
|
+
Do not build the gem from the source repository, even if it is cloned locally.
|
|
19
|
+
|
|
20
|
+
```shell
|
|
21
|
+
gem install aspera-cli mcp
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Check:
|
|
25
|
+
|
|
26
|
+
```shell
|
|
27
|
+
ascli -v
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`ascli mcp server` starts the server on standard input and output (`stdio`): it waits for an MCP client and does not return.
|
|
31
|
+
To check it outside a client, stop it after the line `Starting MCP server`.
|
|
32
|
+
|
|
33
|
+
## 3. Add the server to the MCP client
|
|
34
|
+
|
|
35
|
+
Add the server to the configuration file of the MCP client itself (not to VS Code `settings.json`).
|
|
36
|
+
Server name: `ascli`, command: `ascli`, arguments: `mcp server`.
|
|
37
|
+
|
|
38
|
+
Cline: add to `cline_mcp_settings.json` (Cline: MCP Servers > Configure, or Edit Configuration):
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"mcpServers": {
|
|
43
|
+
"ascli": {
|
|
44
|
+
"command": "ascli",
|
|
45
|
+
"args": ["mcp", "server"]
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The same `mcpServers` entry applies to Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and IBM Bob (`.bob/mcp.json`).
|
|
52
|
+
|
|
53
|
+
VS Code (GitHub Copilot agent mode): add to `.vscode/mcp.json`:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"servers": {
|
|
58
|
+
"ascli": {
|
|
59
|
+
"type": "stdio",
|
|
60
|
+
"command": "ascli",
|
|
61
|
+
"args": ["mcp", "server"]
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Claude Code:
|
|
68
|
+
|
|
69
|
+
```shell
|
|
70
|
+
claude mcp add ascli -- ascli mcp server
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
If `ascli` is not found by the client, use the absolute path given by `which ascli` (Windows: `where ascli`) as `command`.
|
|
74
|
+
|
|
75
|
+
## 4. Verify
|
|
76
|
+
|
|
77
|
+
The client lists the server `ascli`, connected, with the tool `execute_ascli_command`.
|
|
78
|
+
|
|
79
|
+
## 5. Optional: try it
|
|
80
|
+
|
|
81
|
+
No account needed, the public Aspera demo server:
|
|
82
|
+
|
|
83
|
+
```shell
|
|
84
|
+
ascli config initdemo
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Then ask the AI: "List the files on the Aspera demo server."
|
|
88
|
+
For your own systems, create presets (`ascli config wizard`) and keep secrets in a vault: the AI never sees them.
|
data/llms.txt
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# ascli: command line interface for IBM Aspera
|
|
2
|
+
|
|
3
|
+
> `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
|
|
4
|
+
> An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
|
|
5
|
+
> transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
|
|
6
|
+
|
|
7
|
+
If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
|
|
8
|
+
|
|
9
|
+
## Products and plugins
|
|
10
|
+
|
|
11
|
+
The first word after `ascli` is a plugin: one per product.
|
|
12
|
+
|
|
13
|
+
- `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
|
|
14
|
+
- `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
|
|
15
|
+
- `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
|
|
16
|
+
- `node`: Node API of a transfer server (files, access keys, transfers, sync)
|
|
17
|
+
- `shares`: IBM Aspera Shares
|
|
18
|
+
- `console`: IBM Aspera Console
|
|
19
|
+
- `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
|
|
20
|
+
- `ats`: IBM Aspera Transfer Service
|
|
21
|
+
- `cos`: IBM Cloud Object Storage
|
|
22
|
+
- `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
|
|
23
|
+
- `preview`: generation of previews of files
|
|
24
|
+
- `transferd`: Transfer Daemon of the Transfer SDK (install, service)
|
|
25
|
+
- `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
|
|
26
|
+
- `mcp`: Model Context Protocol server
|
|
27
|
+
|
|
28
|
+
## Two ways to use it
|
|
29
|
+
|
|
30
|
+
- Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
|
|
31
|
+
Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
|
|
32
|
+
- MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
|
|
33
|
+
The description of the tool repeats the rules below.
|
|
34
|
+
|
|
35
|
+
## Discover, do not guess
|
|
36
|
+
|
|
37
|
+
Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
|
|
38
|
+
|
|
39
|
+
1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
|
|
40
|
+
2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
|
|
41
|
+
3. Filter parameters of a list command: `--query=help`.
|
|
42
|
+
4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
|
|
43
|
+
5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
|
|
44
|
+
|
|
45
|
+
## Workflow development
|
|
46
|
+
|
|
47
|
+
Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
|
|
48
|
+
|
|
49
|
+
- IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
|
|
50
|
+
Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
|
|
51
|
+
Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
|
|
52
|
+
Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
|
|
53
|
+
- IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
|
|
54
|
+
Start with the section of each trigger and action used (for example, "Send a package" is action type `package_transfer`, section `package-transfer`),
|
|
55
|
+
then `payload-rules-enforced-by-the-api` and `finding-the-identifiers`.
|
|
56
|
+
|
|
57
|
+
## Rules
|
|
58
|
+
|
|
59
|
+
- Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
|
|
60
|
+
- Extended values inside JSON (e.g. a vault secret in a parameter file): write `"@vault:<label>.<field>@"` (closing `@`) in the file, and give `@json:@extend:@file:<path>`. Without `@extend:`, or without the closing `@`, the value stays a literal string. Check with `ascli config echo`.
|
|
61
|
+
- Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
|
|
62
|
+
- Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
|
|
63
|
+
- Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
|
|
64
|
+
- Wait for a state (a work order complete, a task created, a package received): repeat a read-only command (`list`, `show`, `status`) with `--poll`, not with `sleep` or a shell loop, e.g. ``--poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'``.
|
|
65
|
+
`until` is a JMESPath expression on the result (`@`: result not empty), the command fails if it is not met after `max` runs (or `timeout`). `"show":"last"` displays only the last result, `"errors":"retry"` runs again after an error. With `--format=json`, each result displayed is one line: usable in a background watcher. See section `polling-option-poll` of the manual.
|
|
66
|
+
- Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
|
|
67
|
+
- Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
|
|
68
|
+
- Show the user the command line that was executed.
|
|
69
|
+
|
|
70
|
+
## Examples
|
|
71
|
+
|
|
72
|
+
```shell
|
|
73
|
+
ascli config commands faspex5
|
|
74
|
+
ascli faspex5 packages send help
|
|
75
|
+
ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
|
|
76
|
+
ascli aoc files browse / --format=json
|
|
77
|
+
ascli orchestrator workorders status 1234 --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}' --format=json
|
|
78
|
+
ascli server upload /path/to/file --to-folder=/Upload
|
|
79
|
+
ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Documentation
|
|
83
|
+
|
|
84
|
+
- [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
|
|
85
|
+
- [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
|
|
86
|
+
- [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
|
|
87
|
+
- [Source](https://github.com/IBM/aspera-cli)
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ascli
|
|
3
|
+
description: 'Operate IBM Aspera products with the ascli command line: Aspera on Cloud, Faspex 5, High-Speed Transfer Server, Node API, Shares, Console, Orchestrator, Cloud Object Storage. Use when the user wants to transfer files with FASP (ascp), send or receive packages, browse or manage remote files, administer users, workspaces, nodes or access keys, analyze ascp logs, or develop Orchestrator or Aspera on Cloud Automation workflows.'
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
compatibility: Requires the ascli command (Ruby gem aspera-cli) in the shell, or the ascli MCP server.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# ascli: command line interface for IBM Aspera
|
|
9
|
+
|
|
10
|
+
> `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
|
|
11
|
+
> An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
|
|
12
|
+
> transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
|
|
13
|
+
|
|
14
|
+
If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
|
|
15
|
+
|
|
16
|
+
## Products and plugins
|
|
17
|
+
|
|
18
|
+
The first word after `ascli` is a plugin: one per product.
|
|
19
|
+
|
|
20
|
+
- `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
|
|
21
|
+
- `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
|
|
22
|
+
- `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
|
|
23
|
+
- `node`: Node API of a transfer server (files, access keys, transfers, sync)
|
|
24
|
+
- `shares`: IBM Aspera Shares
|
|
25
|
+
- `console`: IBM Aspera Console
|
|
26
|
+
- `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
|
|
27
|
+
- `ats`: IBM Aspera Transfer Service
|
|
28
|
+
- `cos`: IBM Cloud Object Storage
|
|
29
|
+
- `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
|
|
30
|
+
- `preview`: generation of previews of files
|
|
31
|
+
- `transferd`: Transfer Daemon of the Transfer SDK (install, service)
|
|
32
|
+
- `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
|
|
33
|
+
- `mcp`: Model Context Protocol server
|
|
34
|
+
|
|
35
|
+
## Two ways to use it
|
|
36
|
+
|
|
37
|
+
- Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
|
|
38
|
+
Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
|
|
39
|
+
- MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
|
|
40
|
+
The description of the tool repeats the rules below.
|
|
41
|
+
|
|
42
|
+
## Discover, do not guess
|
|
43
|
+
|
|
44
|
+
Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
|
|
45
|
+
|
|
46
|
+
1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
|
|
47
|
+
2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
|
|
48
|
+
3. Filter parameters of a list command: `--query=help`.
|
|
49
|
+
4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
|
|
50
|
+
5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
|
|
51
|
+
|
|
52
|
+
## Workflow development
|
|
53
|
+
|
|
54
|
+
Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
|
|
55
|
+
|
|
56
|
+
- IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
|
|
57
|
+
Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
|
|
58
|
+
Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
|
|
59
|
+
Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
|
|
60
|
+
- IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
|
|
61
|
+
Start with the section of each trigger and action used (for example, "Send a package" is action type `package_transfer`, section `package-transfer`),
|
|
62
|
+
then `payload-rules-enforced-by-the-api` and `finding-the-identifiers`.
|
|
63
|
+
|
|
64
|
+
## Rules
|
|
65
|
+
|
|
66
|
+
- Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
|
|
67
|
+
- Extended values inside JSON (e.g. a vault secret in a parameter file): write `"@vault:<label>.<field>@"` (closing `@`) in the file, and give `@json:@extend:@file:<path>`. Without `@extend:`, or without the closing `@`, the value stays a literal string. Check with `ascli config echo`.
|
|
68
|
+
- Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
|
|
69
|
+
- Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
|
|
70
|
+
- Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
|
|
71
|
+
- Wait for a state (a work order complete, a task created, a package received): repeat a read-only command (`list`, `show`, `status`) with `--poll`, not with `sleep` or a shell loop, e.g. ``--poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'``.
|
|
72
|
+
`until` is a JMESPath expression on the result (`@`: result not empty), the command fails if it is not met after `max` runs (or `timeout`). `"show":"last"` displays only the last result, `"errors":"retry"` runs again after an error. With `--format=json`, each result displayed is one line: usable in a background watcher. See section `polling-option-poll` of the manual.
|
|
73
|
+
- Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
|
|
74
|
+
- Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
|
|
75
|
+
- Show the user the command line that was executed.
|
|
76
|
+
|
|
77
|
+
## Examples
|
|
78
|
+
|
|
79
|
+
```shell
|
|
80
|
+
ascli config commands faspex5
|
|
81
|
+
ascli faspex5 packages send help
|
|
82
|
+
ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
|
|
83
|
+
ascli aoc files browse / --format=json
|
|
84
|
+
ascli orchestrator workorders status 1234 --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}' --format=json
|
|
85
|
+
ascli server upload /path/to/file --to-folder=/Upload
|
|
86
|
+
ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Documentation
|
|
90
|
+
|
|
91
|
+
- [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
|
|
92
|
+
- [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
|
|
93
|
+
- [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
|
|
94
|
+
- [Source](https://github.com/IBM/aspera-cli)
|
data.tar.gz.sig
CHANGED
|
Binary file
|