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

Region や Zone を推測せず、インスタンス ID を直接指定するコマンドを使用してください。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 を使用します：

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 がローカルオプションとして解析しないよう、必ず -- の後に指定してください。パイプ、リダイレクト、&&、変数展開などのシェル構文がリモートコマンドで必要な場合にのみ、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 を使用します。エージェントが段階的に読み取る場合は、前回の 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

場所を指定せずに、1 つ以上のインスタンス EIP を切り替えます。CLI がアベイラビリティーゾーンごとに解決してグループ化します。

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

専用帯域幅は、対応する UCloud アベイラビリティーゾーンでのみ利用できます。各アカウントで購入できるのは、1 ゾーンにつき 1 つまでです。購入しても既存のインスタンスは自動的に切り替わりません。そのゾーンで新規作成するインスタンスには、デフォルトで適用されます。削除すると、リソースを解放する前に、紐付けられた 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）で利用できます。各アカウントでゾーンごとに 1 つの 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 分が 1 か月分、自動的に購入されることがあります。実行中のインスタンスで 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 を使用してスキルを探し、--context-ir と --skill-id の両方を渡してください。 動画の入力には、誰でもアクセスできるURLまたはデータURLを使用できます。コールバックには --callback-url を渡し、受信側がトークンを検証する場合は COMPSHARE_MINIMAX_CALLBACK_TOKEN を設定してください。 ユーザーが明示的に必要としており、ルートオプションとして --show-sensitive を追加しない限り、生成された動画のURLは伏せられます。

キャンセル時は、リクエストを送信する前に現在のタスクを読み取ります。

compshare --json minimax cancel TASK_ID --yes

画像の場合は、タスクを作成する前に現在の料金を確認してください。各リクエストで画像を1枚生成します。

デフォルトの解像度は1Kです。2Kのリクエストは、その階層が minimax image config で有効になっている場合にのみ受け付けられます。価格が 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 を使用してください。 ユーザーが明示的に必要としており、ルートオプションとして --show-sensitive を追加しない限り、生成された画像と音声のURLは伏せられます。音声の出力は速やかにダウンロードしてください。APIでの保持期間は7日間です。完了したタスクを削除すると、その出力も削除されます。

診断

compshare --json doctor

ローカル設定、認証、ネットワーク、SSH環境を確認するには doctor を使用してください。

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での作成時に対話入力を求められる：作成セクションに記載されている、自動化に必須の7つのオプションをすべて指定してください。
• SSHオプションがCLIに解析される：リモートコマンドの前に -- を挿入してください。
• 長いSSHコマンドが中断される：同期的な再試行ではなく、instance job として再送信してください。
• ライフサイクルまたはジョブのタイムアウト：再試行する前に現在の状態を確認してください。リモート操作が停止したと決めつけないでください。
• 予期しないオプションまたは出力：compshare --json COMMAND --help を照会し、このリファレンスではなくインストール済みバージョンに従ってください。