compshare-cli

---
name: compshare-cli
description: Manage CompShare GPU cloud resources and MiniMax H3 video, image, and speech tasks through the compshare CLI. Use when Codex needs to install or configure compshare-cli, search GPU specifications and inventory, inspect pricing, create or manage instances, connect over SSH, transfer files, run durable remote jobs, manage images, disks, US3, teams or billing, create or inspect MiniMax H3 media, or diagnose CLI problems.
---

# 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

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

MiniMax H3 uses a separate model API key:

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

```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.

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

## Inspect and manage instances

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

```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.

## SSH and file transfer

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.

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

## Dedicated bandwidth

List dedicated bandwidth resources and inspect instance EIP assignments:

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

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

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

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

```text
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.

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

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

```bash
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.
Audio references can be used alone, with or without a text prompt. Frame inputs cannot be
combined with reference inputs. Reference inputs allow up to 9 images, 3 videos and 3 audio
clips, with at most 12 in total.

Video supports 480P, 768P, 1080P, 2K and 4K and durations from 4 to 30 seconds, generated in
one pass even with video references. `--context-ir` is optional for every duration and off by
default; it is strongly recommended and adds 5 points per task. 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. Images must be at most 30 MiB,
with each dimension between 256 and 5760 pixels and a width/height ratio between 0.4 and 2.5.
Reference videos allow at most 50 MiB per file; reference audio allows 15 MiB. Each video or
audio clip must be 2-15.08 seconds long, and each media type has a separate total duration
limit of 15.08 seconds. Input limits are independent of the output video duration.
Video references add 5 points per input second at 480P or 10 at higher resolutions, with
durations summed before rounding up to whole seconds. Image and audio references add no
input fee. 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:

```bash
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.

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

```bash
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`
accepts 500-30000 milliseconds and at most 15 MiB, and returns an asset ID. These speech
reference limits differ from the audio references used for video generation above.
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. Speech output is managed in the organization's
media library; automatic cleanup is off by default and follows organization retention or
capacity settings when enabled. Download output promptly. Unused speech reference assets
are retained for seven days by default; saved custom voices are kept separately.
Deleting a finished task also removes its output.

## Diagnostics

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

```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.

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

• SKILL.md 18 KB
• agents/openai.yaml 1 KB