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

# 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

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 storage cfs --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
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

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.

CFS file storage

CFS is available in container zones reported by instance zones (IsPod=true). Each account can have one CFS resource per zone, shared by its container instances. Capacity is 50-2048 GiB; new purchases support Month, Year, Day and Dynamic, and expansion cannot shrink storage.

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

Review the quote or operation plan before replacing --dry-run with --yes. Prices are in CNY. Resource queries and purchases accept --project ID when a non-default project is needed. Attaching CFS may automatically purchase 50 GiB for one month if none exists in the zone. Attaching or detaching CFS on a running instance can restart it; save work before confirming. The existing storage us3 attach command has the same behavior for cpod- instances.

instance create --cfs and instance template create --cfs enable attachment of an existing CFS in that zone. They do not purchase CFS if none exists. Use --no-cfs to override a template. Back up data and detach instances before deleting CFS. delete --recycle may detach stopped instances first; it still refuses to delete storage mounted by a running instance.

MiniMax H3 media 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. Video supports 480P, 768P, 1080P, 2K and 4K and durations from 4 to 30 seconds. Use minimax skill list to find a Skill, then pass both --context-ir and --skill-id. Video inputs may use publicly accessible URLs or Data 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

For images, inspect current pricing before creating a task. Each request creates one image:

The default resolution is 1K. 2K requests are accepted only when that tier is enabled in minimax image config; a null price means the tier is unavailable.

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

For reference images, minimax image upload FILE --width PIXELS --height PIXELS --yes returns an asset ID; repeat --reference-asset ASSET_ID when creating an image. Check the actual dimensions before upload because the API validates them.

For speech, inspect pricing and voices before creating a task:

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

For an authorized reference recording, minimax audio upload FILE --duration-ms MS --yes returns an asset ID. Use --voice-source asset --asset-id ASSET_ID, or save it with minimax audio voice-create ASSET_ID NAME --yes and then use --voice-source custom --voice-id VOICE_ID. Generated image and speech URLs stay redacted unless the user explicitly needs them and --show-sensitive is added as a root option. Download speech output promptly; the API retains it for seven days. Deleting a finished task also removes its output.

Diagnostics

compshare --json doctor

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

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.