compshare-cli

CompShare CLI

使用 compshare 命令，在终端管理 CompShare GPU 计算资源和 MiniMax H3。

操作规则

• 自动化时使用 compshare --json ...。解析单个 JSON 文档，而不是终端表格。
• 使用不熟悉的命令或选项前，先运行 compshare --json COMMAND --help。JSON 帮助会返回当前命令、参数和子命令结构，无需凭据。
• 将全局选项放在命令组之前，例如 compshare --json --profile production instance list --all。
• 更改资源前，先检查资源和价格。实际创建前，使用 instance create --dry-run。
• 仅在用户已授权变更操作时，才添加 --yes。删除、停止、重新安装、调整大小等操作可能需要确认。
• 为创建操作、生命周期等待和远程作业设置明确的超时时间。超时后，先检查资源再重试，因为远程操作可能仍在运行。
• 对敏感输出进行脱敏。除非用户明确需要原始密码、IP、访问 URL 或登录命令，否则不要使用 --show-sensitive。
• 不要打印、记录或提交 API 凭据。优先使用现有配置文件或环境变量，而不是在命令行上传递私钥。

安装和配置

pip install compshare-cli
pip install --upgrade compshare-cli

交互式配置凭据配置文件：

compshare config --name default
compshare config list
compshare --json doctor

对于非交互式环境，请通过进程环境提供凭据：

export COMPSHARE_PUBLIC_KEY='...'
export COMPSHARE_PRIVATE_KEY='...'
compshare --json doctor

MiniMax H3 使用单独的模型 API 密钥：

export COMPSHARE_MINIMAX_API_KEY='sk-ml-...'

使用 --profile NAME 选择具名配置文件。使用 compshare config path 查找配置文件，并使用 compshare config use NAME 更改默认配置文件。

查看当前命令

优先使用 CLI 的结构化帮助，不要猜测标志：

compshare --json --help
compshare --json instance --help
compshare --json instance create --help
compshare --json image list --help

全局选项：

• --json：输出稳定的机器可读响应封装。
• --profile NAME：选择凭据配置文件。
• --lang zh|en：选择输出语言；JSON 错误代码不受语言影响。
• --show-sensitive：显示通常会脱敏的字段；默认应避免使用。
• --version：打印 CLI 版本。

创建实例

查看位置和镜像，然后搜索可用规格和实际库存：

compshare --json instance zones
compshare --json image list \
  --source platform \
  --region cn-sh2 \
  --zone cn-sh2-02 \
  --all
compshare --json instance search \
  --region cn-sh2 \
  --zone cn-sh2-02 \
  --gpu 4090 \
  --image IMAGE_ID \
  --available

--image 会使 instance search 检查实际库存。不提供该选项时，命令仅列出可用规格。搜索不会筛选 CPU 或内存；请使用创建预演验证确切的 CPU 和内存组合。

构建并检查创建计划，但不更改资源：

compshare --json instance create \
  --region cn-sh2 \
  --zone cn-sh2-02 \
  --gpu 4090 \
  --count 1 \
  --cpu 16 \
  --memory 64GiB \
  --image IMAGE_ID \
  --image-source platform \
  --disk 100GiB \
  --charge Postpay \
  --max-count 1 \
  --max-price 20 \
  --dry-run

检查返回的选择、容量、价格和请求。如果用户批准，请去掉 --dry-run 后重新运行，并添加 --yes 和明确的超时时间：

compshare --json instance create \
  --region cn-sh2 \
  --zone cn-sh2-02 \
  --gpu 4090 \
  --count 1 \
  --cpu 16 \
  --memory 64GiB \
  --image IMAGE_ID \
  --image-source platform \
  --disk 100GiB \
  --charge Postpay \
  --max-count 1 \
  --max-price 20 \
  --yes \
  --timeout 900

在 JSON 模式下，创建操作无法打开交互式向导。请提供 --gpu、--count、--cpu、--memory、--image、--region 和 --zone。此处的 --count 是每个实例的 GPU 数量；--max-count 是实例数量。

检查和管理实例

# List and filter
compshare --json instance list --all
compshare --json instance list --status Running --gpu 4090 --all

# Show a full record or selected sections
compshare --json instance show INSTANCE_ID
compshare --json instance show INSTANCE_ID --status --spec --billing

# Query monitoring metrics and time series; locations are resolved automatically
compshare --json instance monitor INSTANCE_1 INSTANCE_2

# Batch lifecycle operations
compshare --json instance start INSTANCE_1 INSTANCE_2 --timeout 600
compshare --json instance stop INSTANCE_1 INSTANCE_2 --yes --timeout 600
compshare --json instance wait INSTANCE_1 INSTANCE_2 --state Running --timeout 600

# Permanently delete; add --release-disk only when attached data disks must also be deleted
compshare --json instance delete INSTANCE_ID --yes --timeout 600

使用实例 ID 直接执行命令，无需猜测 Region 或 Zone；CLI 会解析位置。批量操作会分别报告成功和失败的实例，并在部分失败时以非零状态退出。

其他实例工作流可在以下位置查看：

instance rename, password, reinstall, resize
instance price, resize-price, billing, refund, charge
instance network, models, ports, schedule, software, template

调用每个工作流前，使用 compshare --json instance COMMAND --help 检查其说明。

SSH 和文件传输

使用 instance ssh 打开交互式 shell，或执行简短的同步命令：

compshare instance ssh INSTANCE_ID
compshare --json instance ssh INSTANCE_ID -- nvidia-smi
compshare --json instance ssh INSTANCE_ID -- sh -lc 'cd /workspace && python train.py'

始终将远程命令参数放在 -- 之后，避免 CLI 将其解析为本地选项。只有在远程命令需要管道、重定向、&& 或变量展开等 shell 语法时，才使用 sh -lc。

在远程路径前加上 :，即可复制文件或目录：

compshare --json instance cp INSTANCE_ID ./model.bin :/workspace/model.bin
compshare --json instance cp INSTANCE_ID ./dataset :/workspace/dataset
compshare --json instance cp INSTANCE_ID :/workspace/results ./results

CLI 会自动解析并缓存 SSH 连接数据。重置密码或重新安装后使用 --refresh，必须避免使用缓存的连接数据时使用 --no-cache。

持久化远程作业

对于安装、训练、编译以及其他必须在本地终端或网络断开后继续运行的工作，请使用 instance job：

compshare --json instance job submit INSTANCE_ID \
  --name training \
  --cwd /workspace/project \
  -- python train.py --epochs 100

compshare --json instance job list INSTANCE_ID
compshare --json instance job show INSTANCE_ID JOB_ID
compshare --json instance job logs INSTANCE_ID JOB_ID --tail 200
compshare --json instance job wait INSTANCE_ID JOB_ID --timeout 3600

使用 --follow 查看实时日志。对于 Agent 的增量读取，请使用上一次 JSON 响应中的字节偏移量：

compshare --json instance job logs INSTANCE_ID JOB_ID \
  --stdout-offset STDOUT_OFFSET \
  --stderr-offset STDERR_OFFSET \
  --limit 65536

仅在获得授权后取消或清理作业：

compshare --json instance job cancel INSTANCE_ID JOB_ID --yes
compshare --json instance job prune INSTANCE_ID --older-than 7d --yes

作业等待超时不会取消远程作业。提交替代工作前，请先查询作业状态。

专用带宽

列出专用带宽资源，并检查实例的 EIP 分配情况：

compshare --json bandwidth list
compshare --json bandwidth instances

只有在查看相应的试运行结果后，才能购买、调整规格或删除。API 以分为单位返回价格，而面向用户的输出以 CNY 显示：

compshare --json bandwidth create \
  --region cn-wlcb --zone cn-wlcb-01 \
  --bandwidth 100 --charge Month --quantity 1 --dry-run
compshare --json bandwidth create \
  --region cn-wlcb --zone cn-wlcb-01 \
  --bandwidth 100 --charge Month --quantity 1 --yes

compshare --json bandwidth resize BANDWIDTH_ID \
  --region cn-wlcb --zone cn-wlcb-01 --bandwidth 200 --dry-run
compshare --json bandwidth delete BANDWIDTH_ID \
  --region cn-wlcb --zone cn-wlcb-01 --dry-run

切换一个或多个实例的 EIP 时无需提供位置；CLI 会解析并按可用区分组：

compshare --json bandwidth switch INSTANCE_1 INSTANCE_2 --to dedicated --yes
compshare --json bandwidth switch INSTANCE_1 --to shared --yes

专用带宽仅在受支持的 UCloud 可用区提供。每个账户在每个可用区最多可购买一个。购买后，现有实例不会自动切换到专用带宽；该可用区中的新实例默认使用专用带宽。删除专用带宽资源前，会先将绑定的 EIP 迁移回共享带宽。

镜像、存储和团队

先查找子命令，再查看具体操作：

compshare --json image --help
compshare --json storage --help
compshare --json storage disk --help
compshare --json storage cfs --help
compshare --json bandwidth --help
compshare --json team --help

常用入口：

image list/show/create/progress/update/delete/share/unshare/publish
storage disk list/create/attach/detach/price/resize/delete
storage us3 attach
storage cfs list/show/price/create/resize-price/resize/refund/delete/attach/detach
team list/joined/show/create/update/delete/audit
team invite/member/quota/billing

镜像删除、磁盘删除、磁盘卸载或调整规格、配额更改和团队变更都属于会更改状态的操作。请先读取当前资源，并在支持的情况下，添加 --yes 前先请求确认。

CFS 文件存储

CFS 在 instance zones 报告的容器可用区（IsPod=true）中提供。每个账户在每个可用区可拥有一个 CFS 资源，供该可用区中的容器实例共享。容量为 50-2048 GiB；新购支持 Month、Year、Day 和 Dynamic，扩容不能缩小存储容量。

compshare --json storage cfs list
compshare --json storage cfs show CFS_ID
compshare --json storage cfs create --name training --size 100GiB \
  --region cn-bj2 --zone cn-bj2-03 --dry-run
compshare --json storage cfs resize CFS_ID --size 200GiB \
  --region cn-bj2 --zone cn-bj2-03 --dry-run
compshare --json storage cfs delete CFS_ID \
  --region cn-bj2 --zone cn-bj2-03 --dry-run
compshare --json storage cfs attach --instance CPOD_ID --dry-run

将 --dry-run 替换为 --yes 前，请查看报价或操作计划。价格以 CNY 计。需要使用非默认项目时，资源查询和购买操作可接受 --project ID。如果所在可用区没有 CFS，附加 CFS 可能会自动购买 50 GiB、时长为一个月的存储。在运行中的实例上附加或卸载 CFS 可能会重启实例；确认前请保存工作。现有的 storage us3 attach 命令对 cpod- 实例也有相同行为。

instance create --cfs 和 instance template create --cfs 用于附加该可用区中已有的 CFS。如果没有 CFS，它们不会购买。使用 --no-cfs 覆盖模板设置。删除 CFS 前，请备份数据并卸载实例。delete --recycle 可能会先卸载已停止的实例；如果存储仍挂载在运行中的实例上，该命令仍会拒绝删除。

MiniMax H3 媒体任务

创建任务前，先检查积分和已有工作：

compshare --json minimax points
compshare --json minimax packages
compshare --json minimax list --status running
compshare --json minimax show TASK_ID

预览请求，获得批准后再创建。重试结果不确定的请求时，请重复使用明确的幂等键：

compshare --json minimax create 'A sailboat crossing a golden sea' \
  --resolution 1080P --duration 5 --ratio 16:9 \
  --idempotency-key VIDEO_REQUEST_ID --dry-run
compshare --json minimax create 'A sailboat crossing a golden sea' \
  --resolution 1080P --duration 5 --ratio 16:9 \
  --idempotency-key VIDEO_REQUEST_ID --yes

帧驱动视频使用 --first-frame 和 --last-frame；参考素材驱动视频则重复使用 --reference-image、--reference-video 和 --reference-audio。视频支持 480P、768P、1080P、2K 和 4K，时长为 4 至 30 秒。使用 minimax skill list 查找 Skill，然后同时传入 --context-ir 和 --skill-id。 视频输入可以使用可公开访问的 URL 或 Data URL。要使用回调，请传入 --callback-url；如果接收方会验证令牌，请设置 COMPSHARE_MINIMAX_CALLBACK_TOKEN。 除非用户明确需要，否则生成的视频 URL 会保持隐藏；如需显示，请将 --show-sensitive 添加为根选项。

取消任务前，会先读取当前任务，再提交请求：

compshare --json minimax cancel TASK_ID --yes

对于图像，创建任务前先查看当前价格。每个请求会生成一张图像：

默认分辨率为 1K。只有在 minimax image config 中启用了 2K 档位时，才会接受 2K 请求；价格为 null 表示该档位不可用。

compshare --json minimax image config
compshare --json minimax image list --status queued
compshare --json minimax image create 'A cat on the moon' --resolution 1K \
  --idempotency-key IMAGE_REQUEST_ID --dry-run
compshare --json minimax image create 'A cat on the moon' --resolution 1K \
  --idempotency-key IMAGE_REQUEST_ID --yes
compshare --json minimax image show TASK_ID

对于参考图像，minimax image upload FILE --width PIXELS --height PIXELS --yes 会返回资源 ID；创建图像时重复传入 --reference-asset ASSET_ID。上传前请检查实际尺寸，因为 API 会对尺寸进行验证。

对于语音，创建任务前先查看价格和音色：

compshare --json minimax audio pricing
compshare --json minimax audio voices --kind preset
compshare --json minimax audio create 'Hello from CompShare.' --voice-id VOICE_ID \
  --idempotency-key SPEECH_REQUEST_ID --dry-run
compshare --json minimax audio create 'Hello from CompShare.' --voice-id VOICE_ID \
  --idempotency-key SPEECH_REQUEST_ID --yes
compshare --json minimax audio show TASK_ID

对于经过授权的参考录音，minimax audio upload FILE --duration-ms MS --yes 会返回资源 ID。使用 --voice-source asset --asset-id ASSET_ID，或者使用 minimax audio voice-create ASSET_ID NAME --yes 保存录音，然后使用 --voice-source custom --voice-id VOICE_ID。 除非用户明确需要，否则生成的图像和语音 URL 会保持隐藏；如需显示，请将 --show-sensitive 添加为根选项。请及时下载语音输出；API 仅保留 7 天。删除已完成的任务也会移除其输出。

诊断

compshare --json doctor

使用 doctor 检查本地配置、身份验证、网络和 SSH 环境。

JSON 合约

成功的命令会返回一个 UTF-8 JSON 文档，结构如下：

{
  "ok": true,
  "schema_version": "1",
  "data": {}
}

失败时会返回 ok: false，并包含稳定的 error.code、人类可读的 error.message，以及可选的 error.details。列表命令会将行数据放在 data.items 中，并将分页或 API 元数据放在 meta 中。除了检查 ok，还要检查进程退出代码；批量操作可能会部分失败。

故障排除

• 身份验证或配置失败：运行 compshare --json doctor，然后检查 compshare config list，但不要暴露凭据值。
• 没有可用规格：使用准确的镜像名称和 --available 再次搜索；有意放宽 GPU、Region、Zone、CPU、内存、计费或磁盘限制。
• JSON 创建操作要求交互：提供创建部分列出的全部七个自动化必需选项。
• CLI 将 SSH 选项解析为自身选项：在远程命令前插入 --。
• 长时间运行的 SSH 命令被中断：将其作为 instance job 重新提交，不要同步重试。
• 生命周期或作业超时：重试前检查当前状态；不要假设远程操作已停止。
• 遇到意外选项或输出：查询 compshare --json COMMAND --help，并以已安装的版本为准，而非本文档。