aspera-cli 4.27.5 → 4.29.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/BUGS.md +5 -10
- data/CHANGELOG.md +301 -4
- data/CODE_OF_CONDUCT.md +18 -0
- data/CONTRIBUTING.md +139 -58
- data/GOVERNANCE.md +30 -0
- data/LICENSE +201 -0
- data/README.md +103 -26
- data/SECURITY.md +70 -0
- data/bin/ascli +8 -5
- data/bin/asession +10 -7
- data/docs/README.md +2551 -772
- data/docs/test-mcp-with-ai.md +13 -11
- 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 +34 -22
- data/lib/aspera/agent/factory.rb +8 -4
- 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 +8 -5
- data/lib/aspera/api/faspex.rb +16 -9
- data/lib/aspera/api/httpgw.rb +9 -6
- data/lib/aspera/api/node.rb +23 -19
- data/lib/aspera/ascmd.rb +8 -5
- data/lib/aspera/ascp/installation.rb +84 -42
- 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 +354 -0
- data/lib/aspera/ascp/management.rb +102 -48
- data/lib/aspera/ascp/session_errors.rb +217 -0
- data/lib/aspera/assert.rb +4 -0
- data/lib/aspera/cli/ascp_actions.rb +16 -37
- data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
- data/lib/aspera/cli/async_transfer_store.rb +7 -4
- data/lib/aspera/cli/bootstrapper.rb +37 -34
- data/lib/aspera/cli/command_line.rb +24 -6
- data/lib/aspera/cli/command_registry.rb +49 -4
- data/lib/aspera/cli/command_spec.rb +34 -4
- data/lib/aspera/cli/completion/ascli.bash +53 -5
- data/lib/aspera/cli/completion/ascli.fish +27 -8
- data/lib/aspera/cli/completion/ascli.ps1 +63 -0
- data/lib/aspera/cli/completion/ascli.zsh +36 -4
- data/lib/aspera/cli/completion_actions.rb +594 -0
- data/lib/aspera/cli/context.rb +9 -4
- data/lib/aspera/cli/deprecation.rb +5 -2
- data/lib/aspera/cli/error.rb +45 -0
- data/lib/aspera/cli/extended_value.rb +83 -24
- data/lib/aspera/cli/formatter.rb +142 -73
- data/lib/aspera/cli/gem_checker.rb +9 -6
- data/lib/aspera/cli/hints.rb +22 -11
- data/lib/aspera/cli/http.rb +17 -13
- data/lib/aspera/cli/info.rb +17 -6
- data/lib/aspera/cli/mailer.rb +7 -4
- data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
- data/lib/aspera/cli/mcp/secrets.rb +146 -0
- data/lib/aspera/cli/mcp/tool.rb +232 -0
- 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 +72 -11
- data/lib/aspera/cli/options.schema.yaml +856 -81
- data/lib/aspera/cli/parser.rb +64 -31
- data/lib/aspera/cli/plugins/alee.rb +7 -4
- data/lib/aspera/cli/plugins/aoc.rb +250 -44
- data/lib/aspera/cli/plugins/ats.rb +9 -8
- data/lib/aspera/cli/plugins/base.rb +51 -25
- data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
- data/lib/aspera/cli/plugins/config.rb +207 -141
- data/lib/aspera/cli/plugins/console.rb +9 -4
- data/lib/aspera/cli/plugins/cos.rb +8 -4
- data/lib/aspera/cli/plugins/factory.rb +22 -8
- data/lib/aspera/cli/plugins/faspex5.rb +37 -44
- data/lib/aspera/cli/plugins/faspio.rb +41 -8
- data/lib/aspera/cli/plugins/httpgw.rb +8 -4
- data/lib/aspera/cli/plugins/mcp.rb +186 -121
- data/lib/aspera/cli/plugins/node.rb +41 -34
- data/lib/aspera/cli/plugins/oauth.rb +5 -1
- data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
- data/lib/aspera/cli/plugins/preview.rb +69 -44
- data/lib/aspera/cli/plugins/server.rb +66 -12
- data/lib/aspera/cli/plugins/shares.rb +288 -48
- data/lib/aspera/cli/plugins/transferd.rb +223 -0
- data/lib/aspera/cli/preset_actions.rb +155 -33
- data/lib/aspera/cli/preset_manager.rb +72 -16
- data/lib/aspera/cli/prompt.rb +7 -2
- data/lib/aspera/cli/result.rb +28 -11
- data/lib/aspera/cli/runner.rb +193 -80
- data/lib/aspera/cli/secret_finder.rb +4 -1
- data/lib/aspera/cli/security.rb +204 -0
- data/lib/aspera/cli/special_values.rb +4 -1
- data/lib/aspera/cli/sync_actions.rb +13 -10
- data/lib/aspera/cli/table_fitter.rb +119 -0
- data/lib/aspera/cli/terminal_formatter.rb +32 -40
- data/lib/aspera/cli/transfer_actions.rb +11 -8
- data/lib/aspera/cli/transfer_agent.rb +31 -19
- data/lib/aspera/cli/transfer_progress.rb +13 -45
- data/lib/aspera/cli/vault_actions.rb +45 -0
- data/lib/aspera/cli/vault_manager.rb +197 -50
- data/lib/aspera/cli/version.rb +4 -1
- data/lib/aspera/cli/web_secret.html.erb +61 -0
- data/lib/aspera/cli/web_secret.rb +222 -0
- data/lib/aspera/cli/wizard.rb +58 -45
- data/lib/aspera/command_line_builder.rb +35 -5
- data/lib/aspera/command_line_converter.rb +4 -1
- data/lib/aspera/coverage.rb +103 -33
- data/lib/aspera/data_repository.rb +42 -25
- data/lib/aspera/dot_container.rb +4 -1
- data/lib/aspera/duration.rb +45 -0
- data/lib/aspera/environment.rb +106 -33
- data/lib/aspera/exec_spec.rb +9 -5
- data/lib/aspera/faspex_gw.rb +105 -35
- data/lib/aspera/faspex_postproc.rb +193 -47
- data/lib/aspera/formatter_interface.rb +4 -2
- data/lib/aspera/graphql.rb +5 -1
- data/lib/aspera/hash_ext.rb +3 -0
- data/lib/aspera/id_generator.rb +6 -3
- data/lib/aspera/json_rpc/client.rb +55 -35
- data/lib/aspera/json_rpc/version.rb +4 -0
- data/lib/aspera/line_logger.rb +4 -1
- data/lib/aspera/link_header.rb +4 -1
- data/lib/aspera/log.rb +20 -10
- data/lib/aspera/markdown.rb +155 -115
- data/lib/aspera/mime.rb +9 -0
- data/lib/aspera/nagios.rb +9 -5
- data/lib/aspera/node_emulator.rb +111 -112
- data/lib/aspera/oauth/client/base.rb +163 -0
- data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
- data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
- data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
- data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
- data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
- data/lib/aspera/oauth/client/shares_web.rb +85 -0
- data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
- data/lib/aspera/oauth/client/web.rb +84 -0
- data/lib/aspera/oauth/server/authorize.html.erb +34 -0
- data/lib/aspera/oauth/server/pkce.rb +427 -0
- data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
- 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 +11 -6
- data/lib/aspera/preview/utils.rb +6 -4
- data/lib/aspera/products/connect.rb +5 -2
- data/lib/aspera/products/desktop.rb +4 -1
- 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 +30 -1
- data/lib/aspera/rest/aspera_errors.rb +55 -60
- data/lib/aspera/rest/call_error.rb +3 -0
- data/lib/aspera/rest/client.rb +42 -42
- data/lib/aspera/rest/error_analyzer.rb +14 -2
- data/lib/aspera/rest/list.rb +14 -10
- data/lib/aspera/rest/parameters.rb +3 -0
- data/lib/aspera/rest/util.rb +13 -4
- data/lib/aspera/rest.rb +9 -7
- data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
- data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
- data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
- 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/IBM_Aspera_Shares.yaml +819 -7
- data/lib/aspera/schema/async_tables.yaml +11 -10
- data/lib/aspera/schema/documentation.rb +56 -78
- data/lib/aspera/schema/reader.rb +46 -11
- data/lib/aspera/schema/registry.rb +45 -24
- data/lib/aspera/schema/transferd-config.schema.json +333 -0
- data/lib/aspera/schema/validator.rb +4 -1
- data/lib/aspera/sealed_hash.rb +166 -0
- data/lib/aspera/secret/hider.rb +201 -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 +110 -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 +114 -0
- 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 +6 -1
- data/lib/aspera/sync/conf.schema.yaml +25 -10
- data/lib/aspera/sync/database.rb +3 -0
- data/lib/aspera/sync/operations.rb +34 -12
- data/lib/aspera/temp_file_manager.rb +85 -22
- 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 +22 -14
- data/lib/aspera/transfer/result.rb +3 -0
- data/lib/aspera/transfer/resumer.rb +6 -4
- data/lib/aspera/transfer/spec.rb +45 -18
- data/lib/aspera/transfer/spec.schema.yaml +8 -5
- data/lib/aspera/transfer/units.rb +75 -0
- data/lib/aspera/uri_reader.rb +57 -7
- data/lib/aspera/web_auth/index.html.erb +20 -0
- 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 +59 -14
- data/lib/aspera/web_page.html.erb +262 -0
- data/lib/aspera/web_page.rb +66 -0
- data/lib/aspera/web_server_simple.rb +82 -13
- data/lib/aspera/yaml.rb +5 -1
- data/llms.txt +81 -0
- data/skills/ascli/SKILL.md +88 -0
- data.tar.gz.sig +0 -0
- metadata +116 -48
- metadata.gz.sig +0 -0
- data/lib/aspera/cli/mcp_tool.rb +0 -189
- data/lib/aspera/keychain/base.rb +0 -25
- data/lib/aspera/keychain/encrypted_hash.rb +0 -188
- data/lib/aspera/keychain/factory.rb +0 -59
- data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
- data/lib/aspera/keychain/macos_security.rb +0 -171
- data/lib/aspera/keychain/one_password_api.rb +0 -86
- data/lib/aspera/keychain/one_password_base.rb +0 -34
- data/lib/aspera/keychain/one_password_cli.rb +0 -98
- data/lib/aspera/oauth/base.rb +0 -141
- data/lib/aspera/oauth/web.rb +0 -57
- data/lib/aspera/oauth.rb +0 -9
- data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
- data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
- data/lib/aspera/secret_hider.rb +0 -117
- data/lib/aspera/web_auth/index.html +0 -147
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
<%# Layout of HTML pages: style and branding, see Aspera::WebPage. Variables: title, content (HTML of the card) %>
|
|
2
|
+
<!DOCTYPE html>
|
|
3
|
+
<html lang="en">
|
|
4
|
+
|
|
5
|
+
<head>
|
|
6
|
+
<meta charset="utf-8">
|
|
7
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
8
|
+
<%# Light and dark themes: the browser adapts form controls and scrollbars too %>
|
|
9
|
+
<meta name="color-scheme" content="light dark">
|
|
10
|
+
<link rel="icon" type="image/svg+xml"
|
|
11
|
+
href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='6' fill='%230f62fe'/%3E%3Ctext x='16' y='22' font-family='monospace' font-size='18' font-weight='bold' fill='white' text-anchor='middle'%3E%3E_%3C/text%3E%3C/svg%3E">
|
|
12
|
+
<title><%= h title %></title>
|
|
13
|
+
<style>
|
|
14
|
+
/* Colors: light theme, overridden by the dark theme of the system or browser */
|
|
15
|
+
:root {
|
|
16
|
+
--page-bg-start: #f0f4f8;
|
|
17
|
+
--page-bg-end: #d9e2ec;
|
|
18
|
+
--card-bg: #ffffff;
|
|
19
|
+
--surface: #f4f4f4;
|
|
20
|
+
--border: #e0e0e0;
|
|
21
|
+
--shadow: 0 4px 24px rgba(0, 0, 0, 0.08), 0 1px 3px rgba(0, 0, 0, 0.04);
|
|
22
|
+
--text: #161616;
|
|
23
|
+
--text-secondary: #525252;
|
|
24
|
+
--text-muted: #8d8d8d;
|
|
25
|
+
--accent: #0f62fe;
|
|
26
|
+
--button-bg: #0f62fe;
|
|
27
|
+
--button-bg-hover: #0043ce;
|
|
28
|
+
--on-button: #ffffff;
|
|
29
|
+
--danger: #da1e28;
|
|
30
|
+
--danger-bg: #da1e28;
|
|
31
|
+
--success: #24a148;
|
|
32
|
+
--icon-bg: #edf5ff;
|
|
33
|
+
--icon-bg-ok: #defbe6;
|
|
34
|
+
--icon-bg-ko: #fff1f1;
|
|
35
|
+
--input-bg: #ffffff;
|
|
36
|
+
--input-border: #8d8d8d;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
@media (prefers-color-scheme: dark) {
|
|
40
|
+
:root {
|
|
41
|
+
--page-bg-start: #121619;
|
|
42
|
+
--page-bg-end: #1d2226;
|
|
43
|
+
--card-bg: #21272a;
|
|
44
|
+
--surface: #2f353a;
|
|
45
|
+
--border: #42484e;
|
|
46
|
+
--shadow: 0 4px 24px rgba(0, 0, 0, 0.45), 0 1px 3px rgba(0, 0, 0, 0.3);
|
|
47
|
+
--text: #f2f4f8;
|
|
48
|
+
--text-secondary: #c1c7cd;
|
|
49
|
+
--text-muted: #878d96;
|
|
50
|
+
--accent: #78a9ff;
|
|
51
|
+
--button-bg: #0f62fe;
|
|
52
|
+
--button-bg-hover: #0050e6;
|
|
53
|
+
--on-button: #ffffff;
|
|
54
|
+
--danger: #ff8389;
|
|
55
|
+
--danger-bg: #da1e28;
|
|
56
|
+
--success: #42be65;
|
|
57
|
+
--icon-bg: rgba(69, 137, 255, 0.18);
|
|
58
|
+
--icon-bg-ok: rgba(66, 190, 101, 0.18);
|
|
59
|
+
--icon-bg-ko: rgba(250, 77, 86, 0.18);
|
|
60
|
+
--input-bg: #121619;
|
|
61
|
+
--input-border: #697077;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
* {
|
|
66
|
+
box-sizing: border-box;
|
|
67
|
+
margin: 0;
|
|
68
|
+
padding: 0;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
body {
|
|
72
|
+
font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
|
|
73
|
+
background: linear-gradient(135deg, var(--page-bg-start) 0%, var(--page-bg-end) 100%);
|
|
74
|
+
min-height: 100vh;
|
|
75
|
+
display: flex;
|
|
76
|
+
align-items: center;
|
|
77
|
+
justify-content: center;
|
|
78
|
+
padding: 1.5rem;
|
|
79
|
+
color: var(--text);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
.card {
|
|
83
|
+
background: var(--card-bg);
|
|
84
|
+
border-radius: 12px;
|
|
85
|
+
box-shadow: var(--shadow);
|
|
86
|
+
border: 1px solid var(--border);
|
|
87
|
+
max-width: 460px;
|
|
88
|
+
width: 100%;
|
|
89
|
+
padding: 2.25rem 2rem;
|
|
90
|
+
text-align: center;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
.brand {
|
|
94
|
+
display: inline-flex;
|
|
95
|
+
align-items: center;
|
|
96
|
+
gap: 0.5rem;
|
|
97
|
+
margin-bottom: 1.5rem;
|
|
98
|
+
padding: 0.25rem 0.75rem;
|
|
99
|
+
background: var(--surface);
|
|
100
|
+
border-radius: 16px;
|
|
101
|
+
font-size: 0.8rem;
|
|
102
|
+
color: var(--text-secondary);
|
|
103
|
+
border: 1px solid var(--border);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
.brand .badge {
|
|
107
|
+
font-weight: 700;
|
|
108
|
+
color: var(--accent);
|
|
109
|
+
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/* Icons are drawn with currentColor */
|
|
113
|
+
.icon-circle {
|
|
114
|
+
width: 56px;
|
|
115
|
+
height: 56px;
|
|
116
|
+
border-radius: 50%;
|
|
117
|
+
margin: 0 auto 1.25rem;
|
|
118
|
+
display: flex;
|
|
119
|
+
align-items: center;
|
|
120
|
+
justify-content: center;
|
|
121
|
+
background: var(--icon-bg);
|
|
122
|
+
color: var(--accent);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
.icon-circle.ok {
|
|
126
|
+
background: var(--icon-bg-ok);
|
|
127
|
+
color: var(--success);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
.icon-circle.ko {
|
|
131
|
+
background: var(--icon-bg-ko);
|
|
132
|
+
color: var(--danger);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
h1 {
|
|
136
|
+
font-size: 1.5rem;
|
|
137
|
+
font-weight: 600;
|
|
138
|
+
color: var(--text);
|
|
139
|
+
margin-bottom: 0.5rem;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
p {
|
|
143
|
+
font-size: 0.95rem;
|
|
144
|
+
line-height: 1.5;
|
|
145
|
+
color: var(--text-secondary);
|
|
146
|
+
margin-top: 0.5rem;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
.client {
|
|
150
|
+
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
|
|
151
|
+
font-weight: 600;
|
|
152
|
+
background: var(--surface);
|
|
153
|
+
padding: 0.15rem 0.4rem;
|
|
154
|
+
border-radius: 4px;
|
|
155
|
+
color: var(--text);
|
|
156
|
+
border: 1px solid var(--border);
|
|
157
|
+
word-break: break-all;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
.actions {
|
|
161
|
+
display: flex;
|
|
162
|
+
gap: 0.75rem;
|
|
163
|
+
margin-top: 1.5rem;
|
|
164
|
+
justify-content: center;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
button {
|
|
168
|
+
flex: 1;
|
|
169
|
+
padding: 0.75rem 1.25rem;
|
|
170
|
+
font-size: 0.95rem;
|
|
171
|
+
font-weight: 500;
|
|
172
|
+
border-radius: 6px;
|
|
173
|
+
cursor: pointer;
|
|
174
|
+
transition: background-color 0.15s ease, border-color 0.15s ease, color 0.15s ease;
|
|
175
|
+
border: 1px solid transparent;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
.allow {
|
|
179
|
+
background: var(--button-bg);
|
|
180
|
+
color: var(--on-button);
|
|
181
|
+
border-color: var(--button-bg);
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
.allow:hover {
|
|
185
|
+
background: var(--button-bg-hover);
|
|
186
|
+
border-color: var(--button-bg-hover);
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
.deny {
|
|
190
|
+
background: var(--card-bg);
|
|
191
|
+
color: var(--danger);
|
|
192
|
+
border: 1px solid var(--danger);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
.deny:hover {
|
|
196
|
+
background: var(--danger-bg);
|
|
197
|
+
border-color: var(--danger-bg);
|
|
198
|
+
color: var(--on-button);
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
.secret {
|
|
202
|
+
display: block;
|
|
203
|
+
margin-top: 1.25rem;
|
|
204
|
+
text-align: left;
|
|
205
|
+
font-size: 0.875rem;
|
|
206
|
+
color: var(--text-secondary);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
.secret input {
|
|
210
|
+
display: block;
|
|
211
|
+
width: 100%;
|
|
212
|
+
margin-top: 0.35rem;
|
|
213
|
+
padding: 0.6rem 0.75rem;
|
|
214
|
+
font-size: 0.95rem;
|
|
215
|
+
background: var(--input-bg);
|
|
216
|
+
color: var(--text);
|
|
217
|
+
border: 1px solid var(--input-border);
|
|
218
|
+
border-radius: 6px;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
.error {
|
|
222
|
+
color: var(--danger);
|
|
223
|
+
font-weight: 600;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
.info-box {
|
|
227
|
+
background: var(--surface);
|
|
228
|
+
border-radius: 6px;
|
|
229
|
+
padding: 0.75rem 1rem;
|
|
230
|
+
margin-top: 1.25rem;
|
|
231
|
+
font-size: 0.875rem;
|
|
232
|
+
color: var(--text);
|
|
233
|
+
word-break: break-word;
|
|
234
|
+
border-left: 3px solid var(--accent);
|
|
235
|
+
text-align: left;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
.footer {
|
|
239
|
+
margin-top: 1.5rem;
|
|
240
|
+
padding-top: 1rem;
|
|
241
|
+
border-top: 1px solid var(--surface);
|
|
242
|
+
font-size: 0.75rem;
|
|
243
|
+
color: var(--text-muted);
|
|
244
|
+
}
|
|
245
|
+
</style>
|
|
246
|
+
</head>
|
|
247
|
+
|
|
248
|
+
<body>
|
|
249
|
+
<div class="card">
|
|
250
|
+
<div class="brand">
|
|
251
|
+
<span class="badge">ascli</span>
|
|
252
|
+
<span>IBM Aspera CLI</span>
|
|
253
|
+
</div>
|
|
254
|
+
|
|
255
|
+
<%= content %>
|
|
256
|
+
<div class="footer">
|
|
257
|
+
IBM Aspera Command-Line Interface
|
|
258
|
+
</div>
|
|
259
|
+
</div>
|
|
260
|
+
</body>
|
|
261
|
+
|
|
262
|
+
</html>
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# SPDX-FileCopyrightText: IBM Corp.
|
|
4
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
5
|
+
|
|
6
|
+
require 'erb'
|
|
7
|
+
|
|
8
|
+
module Aspera
|
|
9
|
+
# HTML pages of embedded web servers, sharing a layout: style and branding.
|
|
10
|
+
# The ERB template of each page is the content of the card of the layout, with its own variables.
|
|
11
|
+
module WebPage
|
|
12
|
+
# ERB template of the layout, with variables `title` and `content`
|
|
13
|
+
LAYOUT_PATH = File.join(__dir__, 'web_page.html.erb')
|
|
14
|
+
# Context of templates: variables as methods, and `h` to escape HTML
|
|
15
|
+
class Context
|
|
16
|
+
include ERB::Util
|
|
17
|
+
|
|
18
|
+
# @param variables [Hash{Symbol => Object}] Variables of the template
|
|
19
|
+
def initialize(variables)
|
|
20
|
+
variables.each { |name, value| define_singleton_method(name) { value } }
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
# @param template_path [String] Path of the ERB template
|
|
24
|
+
# @return [String] Result of the template
|
|
25
|
+
def render(template_path)
|
|
26
|
+
ERB.new(File.read(template_path)).result(template_binding)
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
private
|
|
30
|
+
|
|
31
|
+
# @return [Binding] Binding without local variables, so that they do not hide template variables
|
|
32
|
+
def template_binding = binding
|
|
33
|
+
end
|
|
34
|
+
# Headers of HTML pages: type, and protection against clickjacking, caching, and leak of the URL to other sites.
|
|
35
|
+
# Not `Referrer-Policy: no-referrer`: the browser would send `Origin: null` with a form, refused by ServletHelpers#check_request
|
|
36
|
+
HEADERS = {
|
|
37
|
+
'Content-Type' => 'text/html; charset=utf-8',
|
|
38
|
+
'X-Frame-Options' => 'DENY',
|
|
39
|
+
'Content-Security-Policy' => "frame-ancestors 'none'",
|
|
40
|
+
'Cache-Control' => 'no-store',
|
|
41
|
+
'Referrer-Policy' => 'same-origin'
|
|
42
|
+
}.freeze
|
|
43
|
+
private_constant :LAYOUT_PATH, :Context, :HEADERS
|
|
44
|
+
|
|
45
|
+
class << self
|
|
46
|
+
# Set the headers of an HTML page: type and security headers
|
|
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
|
|
49
|
+
# @return [nil]
|
|
50
|
+
def secure_headers(response, content_security_policy: nil)
|
|
51
|
+
HEADERS.each { |name, value| response[name] = value }
|
|
52
|
+
response['Content-Security-Policy'] = content_security_policy unless content_security_policy.nil?
|
|
53
|
+
nil
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
# @param template_path [String] Path of the ERB template of the content of the page
|
|
57
|
+
# @param title [String] Title of the page
|
|
58
|
+
# @param variables [Hash] Variables of the template of the content
|
|
59
|
+
# @return [String] HTML page
|
|
60
|
+
def render(template_path, title:, **variables)
|
|
61
|
+
content = Context.new(variables).render(template_path)
|
|
62
|
+
Context.new(title: title, content: content).render(LAYOUT_PATH)
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
end
|
|
@@ -1,9 +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'
|
|
9
|
+
require 'delegate'
|
|
10
|
+
require 'ipaddr'
|
|
3
11
|
require 'webrick'
|
|
4
|
-
require 'aspera/log'
|
|
5
|
-
require 'aspera/assert'
|
|
6
|
-
require 'aspera/hash_ext'
|
|
7
12
|
|
|
8
13
|
module Aspera
|
|
9
14
|
# Simple WEBrick server with HTTPS support
|
|
@@ -15,9 +20,67 @@ module Aspera
|
|
|
15
20
|
PKCS12_EXT = %w[p12 pfx].map { |i| ".#{i}" }.freeze
|
|
16
21
|
CLOCK_SKEW_OFFSET_SEC = 5
|
|
17
22
|
|
|
18
|
-
private_constant :GENERIC_ISSUER, :ONE_YEAR_SECONDS, :PKCS12_EXT, :CLOCK_SKEW_OFFSET_SEC
|
|
23
|
+
private_constant :PARAMS, :DEFAULT_URL, :GENERIC_ISSUER, :ONE_YEAR_SECONDS, :PKCS12_EXT, :CLOCK_SKEW_OFFSET_SEC
|
|
24
|
+
|
|
25
|
+
# Logger of WEBrick: its information messages (version, start, shutdown) at debug level, the server logs its URL
|
|
26
|
+
class WebrickLogger < SimpleDelegator
|
|
27
|
+
def info(message = nil, &block) = debug(message, &block)
|
|
28
|
+
def info? = debug?
|
|
29
|
+
end
|
|
30
|
+
private_constant :WebrickLogger
|
|
31
|
+
|
|
32
|
+
# @return [URI] URL of the server, with the port it listens on: any free port if `0` was given
|
|
33
|
+
attr_reader :uri
|
|
19
34
|
|
|
20
35
|
class << self
|
|
36
|
+
# @param host [String] Host name or IP address the server listens on
|
|
37
|
+
# @return [Boolean] `true` if the server is reachable from the local host only
|
|
38
|
+
def loopback?(host)
|
|
39
|
+
return true if host.eql?('localhost')
|
|
40
|
+
address = IPAddr.new(host)
|
|
41
|
+
# Older versions of ipaddr do not see IPv4-mapped IPv6 addresses (::ffff:127.0.0.1) as loopback
|
|
42
|
+
address = address.native if address.ipv4_mapped?
|
|
43
|
+
address.loopback?
|
|
44
|
+
rescue IPAddr::Error
|
|
45
|
+
false
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
# @param parameters [Hash] Parameters of a command that starts a server (symbol keys): `url`, `cert`, `key`, `chain`, others are for the servlet
|
|
49
|
+
# @return [URI] URL of the server: `url`, or `DEFAULT_URL`
|
|
50
|
+
def url(parameters) = URI.parse(parameters.fetch(:url, DEFAULT_URL))
|
|
51
|
+
|
|
52
|
+
# @param parameters [Hash] Parameters of a command that starts a server, see `url`
|
|
53
|
+
# @return [Hash] Parameters of the servlet: other than `url`, `cert`, `key`, `chain`
|
|
54
|
+
def servlet_parameters(parameters) = parameters.except(:url, *PARAMS)
|
|
55
|
+
|
|
56
|
+
# Start a server with one servlet on the path of `url`, until signal INT or TERM.
|
|
57
|
+
# A server without protection reachable from the network is refused, see `assert_protected`.
|
|
58
|
+
# @param parameters [Hash] Parameters of the command, see `url`
|
|
59
|
+
# @param servlet [Class] Servlet
|
|
60
|
+
# @param protected [Boolean] `true` if requests are authenticated or restricted
|
|
61
|
+
# @param what [String] Parameters that protect the server, for the error message
|
|
62
|
+
# @param type [Exception] Exception to raise
|
|
63
|
+
# @yieldreturn [Array] Arguments of the servlet, evaluated once parameters are checked
|
|
64
|
+
def serve(parameters, servlet, protected:, what:, type: ParameterError)
|
|
65
|
+
uri = url(parameters)
|
|
66
|
+
assert_protected(uri.hostname, protected: protected, what: what, type: type)
|
|
67
|
+
server = new(uri, **parameters.slice(*PARAMS))
|
|
68
|
+
server.mount(uri.path, servlet, *yield)
|
|
69
|
+
server.start
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
# Refuse a server without protection reachable from the network: anyone could call it
|
|
73
|
+
# @param host [String] Host name or IP address the server listens on
|
|
74
|
+
# @param protected [Boolean] `true` if requests are authenticated or restricted
|
|
75
|
+
# @param what [String] Parameters that protect the server, for the error message
|
|
76
|
+
# @param type [Exception] Exception to raise
|
|
77
|
+
# @raise [Exception] if not protected and `host` is not a loopback address
|
|
78
|
+
def assert_protected(host, protected:, what:, type: ParameterError)
|
|
79
|
+
Aspera.assert(protected || loopback?(host), type: type) do
|
|
80
|
+
"#{what} is required when the server listens on an address that is not loopback (localhost, 127.0.0.0/8, ::1): #{host}"
|
|
81
|
+
end
|
|
82
|
+
end
|
|
83
|
+
|
|
21
84
|
# Generate or fill and self sign certificate
|
|
22
85
|
def self_signed_cert(private_key, digest: 'SHA256')
|
|
23
86
|
cert = OpenSSL::X509::Certificate.new
|
|
@@ -46,18 +109,19 @@ module Aspera
|
|
|
46
109
|
end
|
|
47
110
|
end
|
|
48
111
|
|
|
49
|
-
# @param
|
|
112
|
+
# @param uri [URI] Local address where server will listen (use scheme, host and port only), port `0` for any free port
|
|
50
113
|
# @param cert [String] Path to certificate file, either with extension .p12 or .pfx, else assumed PEM
|
|
51
114
|
# @param key [String] Path to key file (PEM) or passphrase (pkcs12)
|
|
52
115
|
# @param chain [String] Path to certificate chain file (PEM only)
|
|
53
116
|
def initialize(uri, cert: nil, key: nil, chain: nil)
|
|
54
117
|
Aspera.assert_type(uri, URI)
|
|
55
|
-
@uri = uri
|
|
118
|
+
@uri = uri.dup
|
|
56
119
|
# see https://www.rubydoc.info/stdlib/webrick/WEBrick/Config
|
|
57
120
|
webrick_options = {
|
|
58
|
-
|
|
121
|
+
# without brackets of IPv6 address
|
|
122
|
+
BindAddress: @uri.hostname,
|
|
59
123
|
Port: @uri.port,
|
|
60
|
-
Logger: Log.log,
|
|
124
|
+
Logger: WebrickLogger.new(Log.log),
|
|
61
125
|
AccessLog: [[self, WEBrick::AccessLog::COMMON_LOG_FORMAT]] # replace default access log to call local method "<<" below
|
|
62
126
|
}
|
|
63
127
|
case @uri.scheme
|
|
@@ -92,7 +156,7 @@ module Aspera
|
|
|
92
156
|
else
|
|
93
157
|
OpenSSL::X509::Certificate.new(File.read(cert))
|
|
94
158
|
end
|
|
95
|
-
webrick_options[:SSLExtraChainCert] = read_chain_file(chain) unless chain.nil?
|
|
159
|
+
webrick_options[:SSLExtraChainCert] = self.class.read_chain_file(chain) unless chain.nil?
|
|
96
160
|
Aspera.assert(webrick_options[:SSLCertificate].public_key.to_der == webrick_options[:SSLPrivateKey].public_key.to_der, type: Error) { 'key and cert do not match' }
|
|
97
161
|
end
|
|
98
162
|
end
|
|
@@ -100,14 +164,19 @@ module Aspera
|
|
|
100
164
|
# self signed certificate generates characters on STDERR
|
|
101
165
|
# see create_self_signed_cert in webrick/ssl.rb
|
|
102
166
|
Log.capture_stderr { super(webrick_options) }
|
|
167
|
+
@uri.port = config[:Port]
|
|
103
168
|
end
|
|
104
169
|
|
|
105
|
-
#
|
|
170
|
+
# Serve requests until #shutdown.
|
|
171
|
+
# In the main thread, signals INT and TERM call #shutdown.
|
|
172
|
+
# In another thread, signals are left to the application, which calls #shutdown, e.g. INT interrupts the main thread.
|
|
106
173
|
def start
|
|
107
174
|
Log.log.info { "Listening on #{@uri}" }
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
175
|
+
if Thread.current.equal?(Thread.main)
|
|
176
|
+
# kill (-TERM) for graceful shutdown
|
|
177
|
+
handler = proc { shutdown }
|
|
178
|
+
%i{INT TERM}.each { |sig| trap(sig, &handler) }
|
|
179
|
+
end
|
|
111
180
|
super
|
|
112
181
|
end
|
|
113
182
|
|
data/lib/aspera/yaml.rb
CHANGED
data/llms.txt
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# ascli: command line interface for IBM Aspera
|
|
2
|
+
|
|
3
|
+
> `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
|
|
4
|
+
> An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
|
|
5
|
+
> transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
|
|
6
|
+
|
|
7
|
+
If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
|
|
8
|
+
|
|
9
|
+
## Products and plugins
|
|
10
|
+
|
|
11
|
+
The first word after `ascli` is a plugin: one per product.
|
|
12
|
+
|
|
13
|
+
- `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
|
|
14
|
+
- `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
|
|
15
|
+
- `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
|
|
16
|
+
- `node`: Node API of a transfer server (files, access keys, transfers, sync)
|
|
17
|
+
- `shares`: IBM Aspera Shares
|
|
18
|
+
- `console`: IBM Aspera Console
|
|
19
|
+
- `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
|
|
20
|
+
- `ats`: IBM Aspera Transfer Service
|
|
21
|
+
- `cos`: IBM Cloud Object Storage
|
|
22
|
+
- `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
|
|
23
|
+
- `preview`: generation of previews of files
|
|
24
|
+
- `transferd`: Transfer Daemon of the Transfer SDK (install, service)
|
|
25
|
+
- `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
|
|
26
|
+
- `mcp`: Model Context Protocol server
|
|
27
|
+
|
|
28
|
+
## Two ways to use it
|
|
29
|
+
|
|
30
|
+
- Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
|
|
31
|
+
Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
|
|
32
|
+
- MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
|
|
33
|
+
The description of the tool repeats the rules below.
|
|
34
|
+
|
|
35
|
+
## Discover, do not guess
|
|
36
|
+
|
|
37
|
+
Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
|
|
38
|
+
|
|
39
|
+
1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
|
|
40
|
+
2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
|
|
41
|
+
3. Filter parameters of a list command: `--query=help`.
|
|
42
|
+
4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
|
|
43
|
+
5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
|
|
44
|
+
|
|
45
|
+
## Workflow development
|
|
46
|
+
|
|
47
|
+
Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
|
|
48
|
+
|
|
49
|
+
- IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
|
|
50
|
+
Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
|
|
51
|
+
Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
|
|
52
|
+
Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
|
|
53
|
+
- IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
|
|
54
|
+
|
|
55
|
+
## Rules
|
|
56
|
+
|
|
57
|
+
- Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
|
|
58
|
+
- Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
|
|
59
|
+
- Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
|
|
60
|
+
- Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
|
|
61
|
+
- Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
|
|
62
|
+
- Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
|
|
63
|
+
- Show the user the command line that was executed.
|
|
64
|
+
|
|
65
|
+
## Examples
|
|
66
|
+
|
|
67
|
+
```shell
|
|
68
|
+
ascli config commands faspex5
|
|
69
|
+
ascli faspex5 packages send help
|
|
70
|
+
ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
|
|
71
|
+
ascli aoc files browse / --format=json
|
|
72
|
+
ascli server upload /path/to/file --to-folder=/Upload
|
|
73
|
+
ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Documentation
|
|
77
|
+
|
|
78
|
+
- [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
|
|
79
|
+
- [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
|
|
80
|
+
- [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
|
|
81
|
+
- [Source](https://github.com/IBM/aspera-cli)
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ascli
|
|
3
|
+
description: 'Operate IBM Aspera products with the ascli command line: Aspera on Cloud, Faspex 5, High-Speed Transfer Server, Node API, Shares, Console, Orchestrator, Cloud Object Storage. Use when the user wants to transfer files with FASP (ascp), send or receive packages, browse or manage remote files, administer users, workspaces, nodes or access keys, analyze ascp logs, or develop Orchestrator or Aspera on Cloud Automation workflows.'
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
compatibility: Requires the ascli command (Ruby gem aspera-cli) in the shell, or the ascli MCP server.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# ascli: command line interface for IBM Aspera
|
|
9
|
+
|
|
10
|
+
> `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
|
|
11
|
+
> An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
|
|
12
|
+
> transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
|
|
13
|
+
|
|
14
|
+
If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
|
|
15
|
+
|
|
16
|
+
## Products and plugins
|
|
17
|
+
|
|
18
|
+
The first word after `ascli` is a plugin: one per product.
|
|
19
|
+
|
|
20
|
+
- `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
|
|
21
|
+
- `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
|
|
22
|
+
- `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
|
|
23
|
+
- `node`: Node API of a transfer server (files, access keys, transfers, sync)
|
|
24
|
+
- `shares`: IBM Aspera Shares
|
|
25
|
+
- `console`: IBM Aspera Console
|
|
26
|
+
- `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
|
|
27
|
+
- `ats`: IBM Aspera Transfer Service
|
|
28
|
+
- `cos`: IBM Cloud Object Storage
|
|
29
|
+
- `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
|
|
30
|
+
- `preview`: generation of previews of files
|
|
31
|
+
- `transferd`: Transfer Daemon of the Transfer SDK (install, service)
|
|
32
|
+
- `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
|
|
33
|
+
- `mcp`: Model Context Protocol server
|
|
34
|
+
|
|
35
|
+
## Two ways to use it
|
|
36
|
+
|
|
37
|
+
- Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
|
|
38
|
+
Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
|
|
39
|
+
- MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
|
|
40
|
+
The description of the tool repeats the rules below.
|
|
41
|
+
|
|
42
|
+
## Discover, do not guess
|
|
43
|
+
|
|
44
|
+
Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
|
|
45
|
+
|
|
46
|
+
1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
|
|
47
|
+
2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
|
|
48
|
+
3. Filter parameters of a list command: `--query=help`.
|
|
49
|
+
4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
|
|
50
|
+
5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
|
|
51
|
+
|
|
52
|
+
## Workflow development
|
|
53
|
+
|
|
54
|
+
Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
|
|
55
|
+
|
|
56
|
+
- IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
|
|
57
|
+
Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
|
|
58
|
+
Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
|
|
59
|
+
Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
|
|
60
|
+
- IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
|
|
61
|
+
|
|
62
|
+
## Rules
|
|
63
|
+
|
|
64
|
+
- Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
|
|
65
|
+
- Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
|
|
66
|
+
- Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
|
|
67
|
+
- Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
|
|
68
|
+
- Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
|
|
69
|
+
- Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
|
|
70
|
+
- Show the user the command line that was executed.
|
|
71
|
+
|
|
72
|
+
## Examples
|
|
73
|
+
|
|
74
|
+
```shell
|
|
75
|
+
ascli config commands faspex5
|
|
76
|
+
ascli faspex5 packages send help
|
|
77
|
+
ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
|
|
78
|
+
ascli aoc files browse / --format=json
|
|
79
|
+
ascli server upload /path/to/file --to-folder=/Upload
|
|
80
|
+
ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Documentation
|
|
84
|
+
|
|
85
|
+
- [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
|
|
86
|
+
- [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
|
|
87
|
+
- [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
|
|
88
|
+
- [Source](https://github.com/IBM/aspera-cli)
|
data.tar.gz.sig
CHANGED
|
Binary file
|