在 Linux、macOS 或 Windows 上使用 matvenus 命令行客户端。本手册只包含终端命令。
配置 CLI
使用平台提供的、与操作系统匹配的版本化 matvenus 可执行文件。先验证客户端,再配置 HTTPS API 源地址。
matvenus version matvenus config set api-url https://YOUR_PLATFORM matvenus config show
用 API 密钥登录
在浏览器账户中创建密钥,再用 login 将其存入操作系统凭证存储。自动化场景可通过 stdin 提供密钥。绝不要把真实密钥写入共享命令或源文件。
matvenus login matvenus auth status matvenus whoami # Automation reads a key from protected stdin. matvenus login --with-key-stdin
查看工具
列出已发布版本,并在创建请求文件前阅读工具契约。
matvenus tools list matvenus tools show protein_properties_physicochemical \ --tool-version 2026-10-14-candidate matvenus tools schema protein_properties_physicochemical --tool-version 2026-10-14-candidate
上传与下载文件
客户端会校验传输。任务请求中使用 READY 文件 ID。下载不会覆盖已存在的输出路径。
matvenus files upload ./protein_panel.fasta matvenus files list --status READY matvenus files show FILE_UUID matvenus files download FILE_UUID --output ./downloaded.fasta
提交并等待
为每个逻辑任务使用一个明确的提交密钥。把它保存在 CLI 进程之外,以便中断后重试能恢复原任务。
将下方版本化示例中的完整 request.json 保存下来。其中的提交、等待与结果命令使用该确切载荷与版本。
跟踪任务并读取结果
本地等待超时或 Ctrl+C 会停止等待,但不会取消远程任务。请继续使用已受理的任务 ID。
jobs download 只适用于声明的输出文件。理化性质示例没有输出文件;请用 jobs result 获取其 JSON。
matvenus jobs list --status RUNNING matvenus jobs show "$JOB_ID" matvenus jobs wait "$JOB_ID" --timeout 5m matvenus jobs result "$JOB_ID" matvenus jobs download "$JOB_ID" \ --file-id FILE_UUID --output ./result.csv
取消任务
该命令只是请求取消。请持续检查任务直到确认停止。按次工具只对成功交付的任务收费。
matvenus jobs cancel "$JOB_ID" matvenus jobs show "$JOB_ID"
JSON 输出与自动化
使用 --json 获取机器可读的 stdout。诊断信息写入 stderr。结果不确定后复用同一提交密钥与载荷。
账户统计使用 /developers/api#usage 中描述的 REST 用量与消费报表。创建期间费用不同于结算期间消费;当前余额与活跃是独立快照。null、零与未核实用量始终区分。请使用已有的余额与任务命令,或经认证的 REST 报表。不提供新的 CLI 统计或整单导出命令。
matvenus --json balance matvenus --json jobs show "$JOB_ID" matvenus --json jobs result "$JOB_ID" matvenus logout
完整示例:蛋白性质
protein_properties_physicochemical@2026-10-14-candidate
正在检查该示例版本当前是否已发布…
用途与输入规则
从一条蛋白序列计算理化特征:长度、分子量、理论 pI 与氨基酸组成,以 JSON 返回。
该版本只返回理化特征,不生成蛋白结构,也不输出文件。公开示例是教学材料,不是一次新的计算,也不构成质量评估。
- sequence 与 fasta_file 必须且只能提供一个;另一个请省略或设为 null。同时提供或都不提供都会被拒绝。
- sequence 不能为空,且只能使用大写 ACDEFGHIKLMNPQRSTVWY。FASTA 必须包含一条非空序列并使用同一字母表;包含多条记录会被拒绝。
- task_name 固定为 Physical and chemical properties。省略时使用默认值,或按原样传入该常量;不支持其他任务。
- fasta_file 请使用属于本账户且状态为 READY 的文件。接受的格式为 fasta、fa 与 faa。本地路径不是 file_id。
- 工具输入上限为 134217728 字节。直接提交 JSON 任务(含元数据)上限为 131072 字节(128 KiB)。序列更大时请改用文件上传与 READY 引用。结构化结果上限为 65536 字节。
版本 2026-10-14-candidate。将下方完整公开请求体保存为 request.json。
将 MATVENUS_API_URL 设为你的 HTTPS 平台基础地址,并把 MATVENUS_API_KEY 放在受保护的环境中(或使用已有 CLI 登录)。为这个逻辑任务设置新的唯一 SUBMISSION_KEY;重试时保留同一密钥与完全相同的请求。新任务需要新密钥。
{
"tool_id": "protein_properties_physicochemical",
"tool_version": "2026-10-14-candidate",
"parameters": {
"sequence": "ACDEFGHIKLMNPQRSTVWY"
}
}matvenus CLI
请逐条执行命令:先核对确切版本并提交 request.json,再将 JOB_ID 设为回执中的 id。超时不会创建新任务;等待 SUCCEEDED 后再读取结果。
matvenus --json tools show protein_properties_physicochemical --tool-version 2026-10-14-candidate matvenus --json jobs submit --input request.json --submission-key "$SUBMISSION_KEY" matvenus --json jobs show "$JOB_ID" matvenus --json jobs wait "$JOB_ID" --timeout 5m matvenus --json jobs result "$JOB_ID"
HTTP 202 表示已受理。即使客户端超时也请保留 Job ID。结果未就绪时返回 409,删除或过期后返回 410。失败或取消的任务可能没有结果。冲突重试返回 409;请检查原任务而非重新提交。
改用 FASTA 文件
将这份公开单记录样本保存为 public-sample.fasta,通过 REST 或 CLI 上传;MCP 不能上传二进制文件。确认返回的文件属于你的账户且状态为 READY。
此处展示的预期 JSON 对应直接序列输入,其 sequence_id 为 temp_sequence。使用 FASTA 输入时,sequence_id 来自记录头;本示例 FASTA 使用 public-sample。序列标识与平台任务 ID 是两回事。
>public-sample ACDEFGHIKLMNPQRSTVWY
先执行上传命令,再将 FILE_ID 设为返回的 id,并确认文件状态为 READY。
matvenus --json files upload ./public-sample.fasta matvenus --json files show "$FILE_ID"
将文件 ID 占位符替换为该 READY 的 UUID,再存为 request.json 并用上面的 REST 或 CLI 步骤提交。这个不同的逻辑任务需要使用新的提交密钥。此时省略 sequence。
{
"tool_id": "protein_properties_physicochemical",
"tool_version": "2026-10-14-candidate",
"parameters": {
"fasta_file": {
"file_id": "REPLACE_WITH_READY_FILE_UUID"
}
}
}公开样本来源
仓库中的版本化材料;这些样本不能证明工具当前可用,以启用目录为准。
worker_groups/protein-properties-physicochemical/candidate-contract.jsonSHA-256: 17f0d36cc81729a3dcf225813df8253213faf19905ec99409962d1d33632497eworker_groups/protein-properties-physicochemical/public/sequence-request.jsonSHA-256: 83bbe6829d85d48aa0446a8646232b97012af7d058707a232c9057f7b1a1abe4worker_groups/protein-properties-physicochemical/public/expected-sequence-result.jsonSHA-256: 0353c5c39d8d9a9f0ae278655ba536f99611e112a41d3a064d8df885b76cb7f2worker_groups/protein-properties-physicochemical/public/public-sample.fastaSHA-256: 27b4df93ee69cfe9d6d92bc808a99f21a8272c20b3daab602138ec0d94e5df83
理解 JSON 结果
公开序列的完整预期输出。这是已存储的公开样本,不是本页面执行的计算。该版本没有输出文件。
{
"data": {
"sequence_id": "temp_sequence",
"sequence_length": 20,
"molecular_weight": 2395.71,
"theoretical_pI": 6.78,
"aromaticity": 0.15,
"instability_index": 84.74,
"gravy": -0.49,
"secondary_structure_fraction": {
"helix": 0.25,
"turn": 0.25,
"sheet": 0.35
},
"amino_acid_composition": {
"A": 0.05,
"C": 0.05,
"D": 0.05,
"E": 0.05,
"F": 0.05,
"G": 0.05,
"H": 0.05,
"I": 0.05,
"K": 0.05,
"L": 0.05,
"M": 0.05,
"N": 0.05,
"P": 0.05,
"Q": 0.05,
"R": 0.05,
"S": 0.05,
"T": 0.05,
"V": 0.05,
"W": 0.05,
"Y": 0.05
}
},
"success": true
}| 名称 | 类型 | 必填 | 说明 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
success | true | 是 | 有效的交付结果要求 success=true 且 data 非空。空对象对该工具不是有效结果。 · 固定为 true | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data | object | 是 | 不允许其他属性 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_id | string | 是 | 结果中的序列标识,与平台任务 ID 不同。 · 最短长度 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_length | integer | 是 | 以氨基酸残基计的序列长度。 · 最小值 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.molecular_weight | number | 是 | 分子量。契约未声明单位,待维护者确认。 · 大于 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.theoretical_pI | number | 是 | 理论等电点(pI),范围 0–14。 · 0–14(含边界) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.aromaticity | number | 是 | 芳香性数值,范围 0–1。以原始比值显示,不是百分比。 · 0–1(含边界) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.instability_index | number | 是 | 报告的不稳定指数;不推断稳定性评级。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.gravy | number | 是 | 报告的 GRAVY 亲水性指数;不推断质量评级。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.secondary_structure_fraction · 3 个字段 · 必填螺旋、转角与折叠的占比,各自 0–1。它们不必相加为 1,也不代表已生成的结构。 · 不允许其他属性
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.amino_acid_composition · 20 个字段 · 必填二十种氨基酸的占比,各自 0–1。二十个字母键均为必填;0.05 表示占比 5%。 · 不允许其他属性
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||