Compshare CLI

CompShare CLI

Manage CompShare GPU compute and MiniMax H3 from the terminal with the compshare command.

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.

Install and configure

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

Configure a credential profile interactively:

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

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

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

MiniMax H3 uses a separate model API key:

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

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.

Discover current commands

Prefer the CLI's structured help over guessing flags:

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.

Create an instance

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

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:

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:

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.

Inspect and manage instances

# 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
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:

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.

SSH and file transfer

Use instance ssh for an interactive shell or a short synchronous command:

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 ::

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.

Durable remote jobs

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

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:

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:

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.

Dedicated bandwidth

List dedicated bandwidth resources and inspect instance EIP assignments:

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

Purchase, resize or delete only after reviewing the corresponding dry run. Prices are returned in cents by the API, while human output renders 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

Switch one or more instance EIPs without supplying locations; the CLI resolves and groups them by availability zone:

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

Dedicated bandwidth is available only in supported UCloud availability zones. Each account can purchase at most one per zone. Existing instances do not switch automatically after purchase; new instances in that zone use it by default. Deleting migrates bound EIPs back to shared bandwidth before releasing the resource.

Images, storage and teams

Discover subcommands first, then inspect the exact operation:

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

Common entry points:

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.

MiniMax H3 video tasks

Inspect points and existing work before creating a task:

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

Preview the request, then create only after approval. Reuse an explicit idempotency key when retrying an uncertain request:

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

Use --first-frame and --last-frame for frame-driven video, or repeat --reference-image, --reference-video and --reference-audio for reference-driven video. All media inputs must be publicly accessible URLs. For callbacks, pass --callback-url and set COMPSHARE_MINIMAX_CALLBACK_TOKEN if the receiver validates a token. Generated video URLs stay redacted unless the user explicitly needs them and --show-sensitive is added as a root option.

Cancellation reads the current task before submitting the request:

compshare --json minimax cancel TASK_ID --yes

Diagnostics and feedback

compshare --json doctor
compshare feedback bug '创建实例时发生错误'

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.

JSON contract

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

{
  "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.

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.