XServer CLI リファレンス — VPS管理

XServer CLI で、XServer VPS の一覧・電源・パケットフィルター・OS再インストール・新規お申し込みなどを操作するコマンドのリファレンスです。

xserver vps 配下のコマンドを掲載しています。対象サービスは XServer VPS（VPS / ビジネスVPS / Windows Server / GPUサーバー） です。ゲーム専用VPSおよび無料プランのVPSは対象外です。新規お申し込みは VPS・ビジネスVPS（Linux 標準 OS）のみです。

CLIの変更履歴は 更新履歴 を参照してください。

インストール

Node.js（v18 以上）がインストールされた環境で、npm からグローバルインストールしてください。

npm install -g xserver-cli

インストール後は、ターミナルのどのディレクトリからでも xserver コマンドが利用可能です。

インストールせずに即時実行することもできます。

npx xserver-cli vps list

バージョン確認

xserver --version

認証設定

認証に使用する秘密値はAPIキーのみです。XServerアカウントの「APIキー管理」で、対象のVPSと必要な権限を設定して発行してください。VPSの操作対象はコマンドの uuid で指定します。

APIキーの発行手順については、下記マニュアルをご参照ください。

• XServer VPS — CLI設定マニュアル

xserver auth login

対話形式でAPIキーを設定します。入力したAPIキーはマスク表示され、ログイン時に利用可能なサービス・権限・対象VPS・新規お申し込みの可否・APIキー有効期限を表示してから、名前付きプロファイルに保存します。

xserver auth login
# ✔ APIキーを入力: ****
# 認証情報を検証中...
# ✓ 認証に成功しました
#
# 利用可能なサービス:
#   VPS
#     権限: すべての操作
#     対象VPS: すべて
#     新規お申し込み: 許可されていません
#
# APIキー有効期限: 2026-12-31 00:00:00
#
# ✓ プロファイル "default" を保存しました
#   設定ファイル: ~/.config/xserver-cli/config.json

--api-keyによる非対話設定もできますが、値がプロセス一覧やシェル履歴へ残る可能性があります。CI/CDでは実行環境のシークレット機能を使用してください。

xserver auth login --api-key YOUR_API_KEY

プロファイル

複数のAPIキーは名前付きプロファイルとして保存し、実行時に切り替えられます。

xserver --profile staging vps list

設定ファイルは ~/.config/xserver-cli/config.json に保存されます。

環境変数

CI/CDでは環境変数でAPIキーを指定できます。VPSの識別子（uuid）は環境変数に固定せず、コマンドで指定します。

# XSERVER_API_KEYは実行環境のシークレット機能などで事前に設定
xserver vps list

認証の優先順位

※環境変数はXSERVER_API_KEYが設定されている場合のみ使用されます。

※--profile <name>を指定した場合は、環境変数より指定したプロファイルを優先します。--profile未指定時は上表の順序で認証情報を取得します。

操作対象の指定

既存VPSを操作するコマンドでは、位置引数 <uuid> に対象の識別子を指定します。uuid は xserver vps list、またはVPSパネルのVPS詳細画面で確認できます。

plans、signup は特定の既存VPSを対象としないため、uuid は不要です。signup-status には申込応答のサービスコード id（正の整数）を指定します。「指定のVPSのみ」のAPIキーでは新規お申し込み（vps signup）はできません。plans と signup-status は、新規お申し込みの許可があれば利用できます。

xserver vps info a1b2c3d4-5678-40ab-cdef-1234567890ab

uuid は収容ホストの移転を伴うメンテナンス等で変更される場合があります。指定した uuid が見つからない場合は、一覧を再取得してください。移転により新しいVPS契約へ移行した場合は、「指定のVPSのみ」を対象とするAPIキーの設定を更新してください（「すべてのVPS」を対象とするAPIキーはそのまま利用できます）。

APIキーに設定された「対象のVPS」の範囲外の uuid を指定した場合は、対象外として拒否されます（TARGET_NOT_ALLOWED など）。

グローバルオプション

os-reinstall run では --yes 単独では実行できません。詳細は「OS再インストール」を参照してください。新規契約の実申請でも --yes では確認を省略できません。

出力形式

既定では人が読みやすいテーブル形式で出力します。自動処理では --format json を使用できます。

確認が必要な操作では、対象のプレビューや確認メッセージを標準エラー出力へ、最終結果を標準出力へ表示します。--format json の標準出力はそのままパイプ処理できます。

電源操作とOS再インストールの受け付けは本文なしです。CLI は受付時点で終了し、完了待ちはしません。進捗はそれぞれ vps power status / vps os-reinstall status で確認してください。

xserver vps list

xserver --format json vps list

xserver --format json vps list | jq ".servers[].uuid"

新規契約の安全確認

vps signup はプリペイド残高から料金が支払われる本契約の申込です。無料お試し期間はありません。利用には、新規申込が許可されたAPIキーと十分なプリペイド残高が必要です。

1. vps plans で対象プラン、契約期間（months）、税込合計金額（total_price）、OSイメージ（os_images[].image_id）を確認します。
2. --agree-to-terms --dry-run を付けて試算し、課金・契約作成を行わずに申込内容を確認します。
3. 実申請では、確認した金額を --expected-total-price に指定し、--agree-to-terms --confirm-purchase を付けて実行します。
4. 表示されるサービス利用規約、個人情報の取り扱い、申込内容、税込合計金額を確認し、対話端末へ指定された確認文字列を入力します。

見積額と --expected-total-price が一致しない場合は申込を中止します。課金を伴う実申請は対話端末でのみ実行でき、--yes では確認を省略できません。CI/CDなどの非対話環境では --dry-run のみ利用してください。

--period は vps plans が返した months から指定してください。プランに無い月数は PLAN_NOT_AVAILABLE になります。

--auto-renew は省略すると有効（API既定）になります。無効にする場合は --auto-renew false を指定してください。

実申請時の冪等性キーは省略するとCLIが自動生成し、標準エラー出力へ表示します。入力不備・残高不足・価格不一致などの4xxエラーで却下された場合は、内容を修正して同じキーで再実行できます。

応答を受け取れなかった場合やサーバーエラーの場合は、同じキーでの再送は48時間 409 DUPLICATE_REQUEST になります。vps list と請求履歴で申込状況を確認し、未実行と確認できた場合のみ新しいキーで再申請してください。

電源操作の反映

起動・再起動・停止は、リクエストを受け付けた後バックグラウンドで反映されます。CLI は受付時点で終了し、進捗は vps power status で確認してください。

1. vps power start / reboot / stop を実行します。
2. 反映状況は vps power status で確認します（ポーリングの推奨間隔: 5秒程度。反映の目安は最大3分）。
3. status が running（起動・再起動後）または stopped（停止後）になれば反映は完了です。

現在の電源状態で実行できない操作（稼働中のVPSへの起動、停止中のVPSへの停止など）は INVALID_POWER_STATE などで拒否されます。プラン変更・ディスク増設・OS再インストールなどの処理が実行中のVPSに対する書き込みも拒否されます。

vps power reboot --force は、通常の再起動で応答がない場合の強制再起動（電源断相当）です。起動・停止に force はありません。

OS再インストール

OS再インストールを実行すると、サーバー内のデータ・設定はすべて削除されます。必要なデータは、あらかじめバックアップを取ったうえで実行してください。削除されたデータを復元することはできません。

実行前の条件

• VPSを停止しておく必要があります。稼働中の場合は INVALID_POWER_STATE になります。停止は vps power stop で行えます。
• プラン変更・イメージ保存・バックアップ復元などの処理が実行中の場合は FEATURE_UNAVAILABLE になります。
• --confirm-reinstall が必須です。--yes 単独では実行できません。対話時は「<uuid> のOS再インストールを承認」を正確に入力します。非対話では --yes と --confirm-reinstall の両方が必要です。

誤操作を防ぐしくみ

1. APIキーの権限 — 権限を「カスタム」にすると「OS再インストール」だけを操作不可にできます。「すべての操作」のキーでは実行できます。
2. VPSごとの操作保護 — vps protection set --os-reinstall true にしたVPSは PROTECTED で拒否します。再インストールするときだけ false に戻してください（VPSパネルからの操作には影響しません）。

プランごとに指定できるイメージ・パスワード

指定できるイメージはVPSパネルのOS再インストール画面と同じです。実際に指定できるイメージは vps os-images で取得してください。

パスワードは共通して 9〜70文字です。`（バッククォート）・<・>・全角文字は使用できません。CLI は長さを先に確認し、文字種は API が判定します。

管理ツール付きのゲームイメージでは --basic-password（半角英数字12〜64文字）が必要です。対象は vps os-images の requires_basic_password で判別できます。

SSHキーには、VPSパネルで登録済みのキーを指定するか、--ssh-key-name と --ssh-public-key を併用して公開鍵を登録できます。APIは秘密鍵を応答しないため、SSHキーの自動生成は行いません。

保存イメージからの復元・ドメイン/SSLクイック設定には対応していません。VPSパネルからご利用ください。

再インストールの流れ

1. vps os-images で image_id を取得します。
2. 操作保護を有効にしているVPSでは vps protection set --os-reinstall false にします。
3. vps power stop → vps power status で stopped を確認します。
4. vps os-reinstall run ... --confirm-reinstall を実行します。
5. vps os-reinstall status で進行状況を確認します（ポーリングの推奨間隔: 30秒程度）。
6. status が completed になれば完了です。再インストール後のVPSは稼働中になります。

再インストール後は SSH のホスト鍵も変わるため、接続時に警告が表示される場合は既知のホスト情報を削除してください。パケットフィルター・IPアドレス・逆引きホスト名は変わりません。

破壊的操作の安全確認

パケットフィルタールールの削除と、再起動の --force では、CLIが対象を表示して確認します。既定の回答は No です。自動実行で確認を省略する場合のみ --yes を指定してください。

OS再インストールは上記と別の確認です。--yes では省略できません。

秘密値の取り扱い

• パスワードや公開鍵をコマンドへ直接指定すると、プロセス一覧やシェル履歴へ残る可能性があります。共有端末での実行を避け、履歴・CIログ・実行権限を適切に管理してください。
• --debugの出力には機密情報が含まれる場合があります。共有前に必ず内容を確認してください。

レート制限エラー

APIの利用上限を超えた場合、CLIは RATE_LIMIT_EXCEEDED エラーを表示して終了します。HTTPレスポンスに Retry-After ヘッダーが含まれる場合は、その秒数を目安に待ってから再実行してください。

VPS のレート制限はアカウント単位で、プランによらず一律です。同じアカウントの複数キーでも合算されます。

認証失敗が短時間に続いた場合はIPアドレス単位で一時的にブロックされます。APIキーや環境変数の設定を確認してから再試行してください。