compshare-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CompShare CLI

Manage CompShare GPU compute from the terminal with the

compshare

command.

通过

compshare

命令从终端管理CompShare GPU计算资源。

Operating rules

操作规则

Use
```
compshare --json ...
```
for automation. Parse the single JSON document instead of terminal tables.
Run
```
compshare --json COMMAND --help
```
before using an unfamiliar command or option. JSON help returns the current command, parameter and subcommand structure without requiring credentials.

Put global options before the command group, for example

compshare --json --profile production instance list --all

Inspect resources and prices before changing them. Use
```
instance create --dry-run
```
before a real create operation.
Add
```
--yes
```
only when the user has authorized the mutation. Deletion, stopping, reinstalling, resizing and similar operations can require confirmation.
Use explicit timeouts for creation, lifecycle waits and remote jobs. After a timeout, inspect the resource before retrying because the remote operation may still be running.
Keep sensitive output redacted. Do not use
```
--show-sensitive
```
unless the user explicitly needs the raw password, IP, access URL or login command.
Do not print, log or commit API credentials. Prefer an existing profile or environment variables over passing a private key on the command line.

自动化场景下使用
```
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凭证。优先使用现有配置文件或环境变量，而非在命令行中传递私钥。

Install and configure

安装与配置

bash

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

Configure a credential profile interactively:

bash

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

For non-interactive environments, provide credentials through the process environment:

bash

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

Select a named profile with

--profile NAME

. Use

compshare config path

to locate the configuration file and

compshare config use NAME

to change the default profile.

bash

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

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

bash

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

在非交互式环境中，通过进程环境提供凭证：

bash

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

使用

--profile NAME

选择指定的配置文件。使用

compshare config path

查找配置文件位置，使用

compshare config use NAME

更改默认配置文件。

Discover current commands

查看当前命令

Prefer the CLI's structured help over guessing flags:

bash

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

Global options:

```
--json
```
: emit the stable machine-readable response envelope.
```
--profile NAME
```
: select a credential profile.
```
--lang zh|en
```
: select the output language; JSON error codes remain language-independent.
```
--show-sensitive
```
: reveal normally redacted fields; avoid by default.
```
--version
```
: print the CLI version.

优先使用CLI的结构化帮助而非猜测参数：

bash

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版本。

Create an instance

创建实例

Discover locations and images, then search legal specifications and real inventory:

bash

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

makes

instance search

check real inventory. Without it, the command lists legal specifications only. Search does not filter CPU or memory; validate the exact CPU and memory combination with the create dry run.

Build and inspect the create plan without changing resources:

bash

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

Review the returned selection, capacity, price and request. If the user approves it, rerun without

--dry-run

and add

--yes

plus an explicit timeout:

bash

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

In JSON mode, creation cannot open the interactive wizard. Supply

--gpu

--count

--cpu

--memory

--image

--region

and

--zone

. Here

--count

is GPUs per instance;

--max-count

is the number of instances.

先查看可用区域和镜像，再搜索合法规格和实际库存：

bash

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或内存；需通过创建预演（dry run）验证CPU和内存的精确组合。

无需修改资源即可生成并查看创建计划：

bash

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

以及明确的超时时间后重新运行：

bash

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

指实例的数量。

Inspect and manage instances

查看与管理实例

bash

undefined

bash

undefined

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

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

永久删除；仅当需要同时删除挂载的数据盘时添加--release-disk

compshare --json instance delete INSTANCE_ID --yes --timeout 600


Use the direct instance ID commands without guessing a Region or Zone; the CLI resolves the location. Batch operations report succeeded and failed instances separately and exit nonzero on partial failure.

Other instance workflows are available under:

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

Inspect each workflow with

compshare --json instance COMMAND --help

before invoking it.

compshare --json instance delete INSTANCE_ID --yes --timeout 600


直接使用实例ID命令，无需猜测Region或Zone；CLI会自动解析位置。批量操作会分别报告成功和失败的实例，若部分失败则返回非零退出码。

其他实例工作流可通过以下命令访问：

```text
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 and file transfer

SSH与文件传输

Use

instance ssh

for an interactive shell or a short synchronous command:

bash

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'

Always place remote command arguments after

--

so the CLI does not parse them as local options. Use

sh -lc

only when the remote command needs shell syntax such as pipes, redirects,

&&

or variable expansion.

Copy a file or directory by prefixing the remote path with

bash

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

The CLI automatically resolves and caches SSH connection data. Use

--refresh

after a password reset or reinstall, and

--no-cache

when cached connection data must not be used.

使用

instance ssh

获取交互式shell或执行短期同步命令：

bash

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

。

通过在远程路径前添加

来复制文件或目录：

bash

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

。

Durable remote jobs

持久化远程任务

Use

instance job

for installation, training, compilation and other work that must survive a local terminal or network disconnect:

bash

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

Use

--follow

for live logs. For incremental agent reads, use byte offsets from the previous JSON response:

bash

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

Cancel or prune jobs only when authorized:

bash

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

A job wait timeout does not cancel the remote job. Query its state before submitting replacement work.

对于安装、训练、编译等需要在本地终端或网络断开后仍能继续运行的工作，使用

instance job

：

bash

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

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

bash

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

仅在获得授权时取消或清理任务：

bash

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

任务等待超时不会取消远程任务。提交替代任务前先查询其状态。

Images, storage and teams

镜像、存储与团队

Discover subcommands first, then inspect the exact operation:

bash

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

Common entry points:

text

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

Treat image deletion, disk deletion, disk detach/resize, quota changes and team mutations as state-changing operations. Read the current resource and request confirmation before adding

--yes

where supported.

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

bash

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

常见入口：

text

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

将镜像删除、磁盘删除、磁盘挂载/卸载/调整规格、配额变更和团队变更视为状态变更操作。在支持添加

--yes

的场景下，先查看当前资源状态并请求确认。

Product questions and diagnostics

产品咨询与诊断

bash

compshare --json ask '按量实例关机以后，云硬盘还收费吗？'
compshare --json doctor
compshare feedback bug '创建实例时发生错误'

Use

ask

for CompShare product usage and billing questions. Use

doctor

for local configuration, authentication, network and SSH environment checks. Use

feedback

only when the user asks to send feedback; it performs an external write.

bash

compshare --json ask '按量实例关机以后，云硬盘还收费吗？'
compshare --json doctor
compshare feedback bug '创建实例时发生错误'

使用

ask

咨询CompShare产品使用和账单相关问题。使用

doctor

检查本地配置、认证、网络和SSH环境。仅当用户要求发送反馈时使用

feedback

；该操作会执行外部写入。

JSON contract

JSON协议

Successful commands return one UTF-8 JSON document shaped like:

json

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

Failures return

ok: false

with a stable

error.code

, a human-readable

error.message

and optional

error.details

. List commands place rows in

data.items

and pagination or API metadata in

meta

. Check the process exit code as well as

ok

; batch operations can fail partially.

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

json

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

失败时返回

ok: false

，包含稳定的

error.code

、易读的

error.message

和可选的

error.details

。列表命令会将行数据放在

data.items

中，分页或API元数据放在

meta

中。除了检查

ok

字段，还要检查进程退出码；批量操作可能部分失败。

Troubleshooting

故障排查

Authentication or configuration failure: run
```
compshare --json doctor
```
, then inspect
```
compshare config list
```
without exposing credential values.
No available specification: search again with the exact image and
```
--available
```
; relax GPU, Region, Zone, CPU, memory, billing or disk constraints deliberately.
JSON creation asks for interaction: provide all seven required automation options listed in the create section.
SSH option parsed by the CLI: insert
```
--
```
before the remote command.
Long SSH command interrupted: resubmit it as an
```
instance job
```
rather than retrying synchronously.
Lifecycle or job timeout: inspect current state before retrying; do not assume the remote operation stopped.
Unexpected option or output: query
```
compshare --json COMMAND --help
```
and follow the installed version rather than this reference.

认证或配置失败：执行
```
compshare --json doctor
```
，然后查看
```
compshare config list
```
，注意不要暴露凭证信息。
无可用规格：使用精确镜像和
```
--available
```
重新搜索；有针对性地放宽GPU、Region、Zone、CPU、内存、计费方式或磁盘限制。
JSON模式创建请求交互：提供创建部分列出的所有七个必填自动化选项。
SSH选项被CLI解析：在远程命令前插入
```
--
```
。
长SSH命令中断：将其重新提交为
```
instance job
```
而非同步重试。
生命周期或任务超时：重试前先检查当前状态；不要假设远程操作已停止。
意外选项或输出：查询
```
compshare --json COMMAND --help
```
，以已安装版本的帮助为准，而非此参考文档。