cmp コマンドラインツール

ポータルでの場所: インストールコマンドはAPIリファレンス (https://<your-domain>/apidoc、セクション「Command-line interface」) にあります。ログインの承認: https://<your-domain>/link。接続済みデバイス: API keys (/api-keys) › Connected apps & devices。

動作内容

cmp は、顧客 (および管理者) 向けの小さなコマンドラインプログラムで、すべてのAPI操作をコマンドに変換します (cmp vm list、cmp vm start <id>、cmp billing invoice list)。これはリリース時のお客様のインストールのOpenAPIドキュメントからビルドされているため、有効にした機能に一致するコマンドになります。Linux、macOS、Windows (amd64およびarm64) 用の単一の静的バイナリであり、他に追加でインストールする必要はありません。

要件

項目	要件
サーバー	追加の要件はありません。リリースパッケージはNexCMPリリースに含まれており、パネルによって https://<your-domain>/cli/ で提供されます。
顧客のマシン	Linux、macOS、または Windows (PowerShell 5.1+)。署名の検証には ssh-keygen (OpenSSH 8.0+) のみが必要です。
資格情報	ワンタイムコードによるブラウザログイン、またはAPI key。
ネットワーク	パネルへのHTTPS接続。CLIは、平文のhttp://でのキー送信をlocalhost宛を除き拒否します。

インフラストラクチャの準備

なし。パネルはこれらのファイルを/cli/から配信します（ビルドやアップロードは不要です）：

ファイル	用途
install.sh, install.ps1	Linux/macOSおよびWindows用インストーラー。パネルのアドレスが含まれています。
latest.json	現在のバージョン、ファイル一覧、サイズ、sha256。
v<version>/cmp_<version>_<os>_<arch>.tar.gz または .zip	プログラム本体：linux amd64/arm64、darwin amd64/arm64/universal、windows amd64/arm64。
v<version>/SHA256SUMS, SHA256SUMS.sig	チェックサムおよびそれらのed25519署名。
cmp-cli.pub	リリース公開鍵。

インストール（お客様）

macOSおよびLinux：

curl -fsSL https://cloud.example.com/cli/install.sh | sh

Windows PowerShell：

irm https://cloud.example.com/cli/install.ps1 | iex

インストーラーはOSとCPUに適したパッケージを選択し、SHA256SUMSとその署名をダウンロードし、スクリプトに埋め込まれた鍵で署名を検証し、パッケージのハッシュを検証した上で、cmpを/usr/local/bin（rootとして）または~/.local/binにインストールします。Windowsの場合は%LOCALAPPDATA%\cmp\binにインストールされ（ユーザーのPATHに追加されます）。いずれかのチェックに失敗した場合、何もインストールされません。

変数	意味
CMP_VERSION	最新版の代わりにこのバージョンをインストールします。
CMP_INSTALL_DIR	インストールフォルダー。
CMP_REQUIRE_SIGNATURE	1 = 署名を検証できない場合に処理を中断します。
CMP_BASE_URL	ダウンロード元ベース（ミラー用）。

手動でのダウンロードと検証：

curl -fsSLO https://cloud.example.com/cli/latest.json
sha256sum --check --ignore-missing SHA256SUMS

ログイン

cmp login

1. CLIにワンタイムコードとリンク（https://cloud.example.com/link?code=WDJB-MJHT）が表示され、ブラウザが開いて待機します。
2. ブラウザでポータルにサインインし、クライアント名、デバイス、IP、国を確認し、権限（スコープ）にチェックを入れ、キーの有効期間を選択します（デフォルト90日）。課金やデータ削除を伴う権限は、初期状態でチェックが外れています。承認をクリックします。
3. CLIは、お客様が手動で作成したキーとは別の独自のキーを受け取り、~/.config/cmp/config.json（モード0600、Windowsでは%APPDATA%\cmp）に保存します。このキーはAPI keys › Connected apps & devicesに表示され、そこから無効化できます。

コードの有効期限は10分です。承認には、他のキーや代行セッションではなく、検証済みのメールアドレスを使用した実際のサインイン済みポータルセッションが必要です。

便利なフラグ：--scopes vm:read,billing:read、--name "build server"、--no-browser、--profile、--api-url。

CI環境やブラウザのないサーバーでは、ポータルから取得したキーを使用してください：

printf %s "$KEY" | cmp login --with-token
export CMP_TOKEN=vk_XXXX      # nothing is written to disk
cmp whoami

コマンドの使用方法

cmp <group> [subgroup] <action> [<id> ...] [flags]

• パスパラメータは位置引数であり、クエリパラメータおよびボディフィールドはkebab-caseのフラグ（--start-port 443）になります。
• --data '{"a":1}'、--data @file.json、--data -のいずれかでJSONボディ全体を指定でき、フラグによってそのフィールドを上書きできます。
• cmp help vm firewall add（または--help）で、任意のコマンドの詳細を表示できます。

cmp catalog plans
cmp vm list --state active --per-page 50
cmp vm get 3f2a1c9e-0000-4000-8000-000000000000
cmp vm start 3f2a1c9e-0000-4000-8000-000000000000
cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24
cmp billing wallet
cmp api GET /v1/vm --query page=2      # raw call to any endpoint

組み込みコマンド：login、logout、whoami、config、api、completion、version、update、help。その他の機能はAPIドキュメントから生成されます。

グローバルフラグ：

フラグ	意味
-o, --output json|table|yaml	フォーマット。デフォルトは端末出力時はtable、パイプ出力時はjsonです。
--profile, --api-url	保存されたログイン情報およびサイトの指定。
-y, --yes	破壊的または有料のコマンドの確認プロンプトをスキップします。
--idempotency-key <k>	有料コマンドのキーを選択します。
--retry <n>	HTTP 429エラーが発生した場合、Retry-After秒待機して最大n回まで再試行します。
--timeout <s>	レスポンスヘッダーを待機する秒数（デフォルト60）。
--debug	キーをマスクした状態で、HTTP通信のやり取りをstderrに表示します。

ウォレットに課金したりデータを削除したりするコマンドは確認を求め、課金の場合は自動生成された Idempotency-Key を送信します（stderrに出力されるため、--idempotency-key で安全に再試行できます）。ターミナルがない場合は、--yes が指定されない限り実行を拒否します。

終了コード

コード	意味
0	成功
1	その他のエラー（ネットワーク、未記載の HTTP 4xx/5xx）
2	使用方法エラー
3	認証エラー（401/403）
4	見つかりません（404）
5	レート制限（429）
6	確認が必要または拒否されました
130	中断されました

プロファイルと環境

cmp config はプロファイルを一覧表示し、cmp config use <name> は切り替えます。リセラーの顧客は自身のドメイン cmp login --api-url https://shop.example.net --profile shop を使用します。優先順位：フラグ、環境変数、設定ファイル。変数：CMP_TOKEN、CMP_PROFILE、CMP_API_URL、CMP_OUTPUT、CMP_CONFIG_DIR、CMP_ALLOW_HTTP、CMP_UPDATE_URL。

GitHub Actions：

- name: Install cmp
  run: |
    curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh
    echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
- name: List running VMs
  env:
    CMP_TOKEN: ${{ secrets.CMP_TOKEN }}   # a read-only key
  run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname'

シェル補完：cmp completion bash|zsh|fish|powershell。

アップデートとアンインストール

cmp version
cmp update --check
cmp update

cmp update は latest.json、SHA256SUMS および署名をダウンロードし、実行中のバイナリに組み込まれた公開鍵で署名を検証し、パッケージハッシュを検証したうえで自身を置き換えます。ダウングレードには --force が必要です。NexCMP をアップデートすると、パネルは新バージョンに付属する CLI リリースを提供します。

アンインストールするには、cmp バイナリと設定ディレクトリ（cmp config path で確認できます）を削除します。マシンを紛失した場合は API keys からキーを失効させてください。

確認

1. cmp version はバージョンおよび API ドキュメントのバージョンを出力します。
2. cmp login を実行し、ブラウザで承認してから cmp whoami を実行すると、プロファイルとパネルの URL が表示されます。
3. cmp vm list は VM を返し、cmp vm list -o json | jq . は生の JSON を表示します。

制限と注意事項

• コマンドリストはビルドによって異なります。リリースビルド時にインストール環境の OpenAPI ドキュメントからパッケージが生成されるため、リリースで無効化されているプロダクトのコマンドは存在しません。CLI が認識していないパスには cmp api を使用してください。
• CLI は MIT ライセンスの下で提供されています。
• 各パッケージには ed25519 キーで署名されています。署名キーはアップデート時に取得されるのではなく、インストーラーおよびバイナリ内にピン留めされています。
• キーにはキーごと、アカウントごとの制限があります（REST API を参照）。

トラブルシューティング

症状	原因	対処法
curl .../cli/install.sh が 404 を返す	サーバー上のリリースに CLI フォルダーがないか、ホストがライセンスの対象外です	https://<domain>/cli/latest.json とドメインを確認し、NexCMP をアップデートしてください。
署名を検証できませんでした	ssh-keygen が存在しないか古すぎます	OpenSSH 8.0+ をインストールするか、リスクを許容する場合のみ CMP_REQUIRE_SIGNATURE=0 を設定してください。
cmp login でコードの有効期限切れが表示される	10 分が経過しました	もう一度 cmp login を実行してください。
終了コード 3	キーにスコープがないか、有効期限切れまたは失効しています	cmp whoami; スコープを追加して作成または再承認してください。
スクリプト内での終了コード 6	端末なしでの有料または破壊的なコマンド	--yes（および独自の --idempotency-key）を追加してください。
httpでのキー送信が拒否されます	通常の http API URL	https:// を使用するか、検証環境でのみ CMP_ALLOW_HTTP=1 を使用してください。
ブラウザが間違ったサイトを開く	リセラー用の --api-url が設定されていません	cmp login --api-url https://<reseller-domain>.