Hyperlift CLIを使用してHyperliftに接続する方法

更新日 2026年9月3日

Hyperlift CLI は、ターミナル経由で Spaceship プラットフォーム上の Hyperlift アプリケーションを管理するためのコマンドラインツールです。

このツールはオープンソースで、こちらで公開されています。これは Spaceship External API と通信し、API キーとシークレットで認証します。これを使うと、次のことができます。

アプリケーションの表示と管理
アプリケーションのビルド、起動、停止、再起動
ランタイムログとビルドログの表示
アプリケーションメトリクスの表示
環境変数の管理
スクリプト作成や自動化のために JSON 出力を使用
CLIを最新の状態に保ってください。

CLIはSpaceship External APIと通信し、認証にはSpaceship APIキーとシークレットを使用します。そのため、CLIは内部サービスに直接アクセスするため、内部情報および管理情報は非表示に保たれます。

この記事では、以下を説明します。

1. Hyperlift CLI をインストールする

Hyperlift CLI は macOS、Windows、Linux にインストールできます。OS に応じて、インストールコマンドを実行してください。スクリプトは自動的にオペレーティングシステムとアーキテクチャを検出し、適切なリリースをダウンロードして検証し、hyperlift コマンドをインストールします。

macOS

Homebrew を使用している場合は、次を実行します。

brew install nccloud/tap/hyperlift

Windows

Scoop を使用している場合は、次を実行します。

scoop bucket add nccloud https://github.com/NCCloud/scoop-bucket

scoop install hyperlift

Linux または macOS

インストールスクリプトを使用することもできます。

curl -fsSL https://raw.githubusercontent.com/NCCloud/hyperlift-cli/main/scripts/install.sh | sh

手動インストール

または、Hyperlift CLI Releases page からお使いのオペレーティングシステム向けのアーカイブをダウンロードし、展開して、hyperlift実行ファイルをシステムの PATH に追加してください。

2. API 認証情報を作成する

Hyperlift CLI は、リクエストを認証するために Spaceship API キーとシークレットを使用します。

API 認証情報を作成するには、次の手順を行います。

Spaceship アカウントにログインします。
API Manager を開きます。
+ New API key ボタンをクリックして、新しいキーを作成します。
キーに名前を付け、実行したい操作に必要な権限を選択します。
Custom access レベルを選択すると、Hyperlift には 3 つのアクセスオプションがあります。

スコープ	権限
Read	アプリケーション、ログ、メトリクスを表示
Execute	アプリケーションのビルド、起動、停止、再起動
Manage	環境変数の表示と管理

Read スコープのみのキーでも、アプリケーション、ログ、メトリクスを表示するだけであれば十分です。アプリケーション管理や環境変数には追加のスコープが必要です。

6. 作成した API キーとシークレットをコピーし、詳細を保存します。

重要: API シークレットは、認証情報の作成時に 1 回だけ表示されます。必ず安全に保存してください。

Done をクリックします。

7. 作成したキーは API Manager メニューの下に一覧表示されます。

3. Hyperlift CLI にログインする

CLI をインストールし、API 認証情報を作成したら、次を実行します。

hyperlift auth login

CLI から API キーとシークレットの入力を求められます。

認証に成功すると、API キーは Hyperlift 設定ファイルに保存され、API シークレットは利用可能な場合、お使いのオペレーティングシステムのキーリングに安全に保存されます。

ログイン状態を確認するには、次を実行します。

hyperlift auth whoami

ログアウトして保存済みの認証情報を削除するには、次を実行します。

hyperlift auth logout

ヒント: "Not logged in" というメッセージが表示された場合は、hyperlift auth login を再度実行してください。403 エラーが表示された場合は、API キーに必要なスコープが不足している可能性があります。

非対話型認証

スクリプトから認証する必要がある場合は、コマンドラインオプションを使用して認証情報を指定できます。

hyperlift auth login --key "$KEY" --secret "$SECRET"

ただし、--secret を使用すると、シークレットがコマンドライン引数として露出します。より安全にするには、標準入力経由でシークレットを渡すことができます。

printf '%s' "$SECRET" | hyperlift auth login --key "$KEY" --with-stdin

4. Hyperlift アプリケーションを管理するための基本コマンド

apps コマンドを使用して、Hyperlift アプリケーションを表示および管理します。

アプリケーションを表示

appsコマンドを使用して、Hyperlift アプリケーションを表示および管理します。

コマンド	説明
`hyperlift apps list`	アプリケーションを一覧表示
`hyperlift apps get <app-id>`	特定のアプリケーションに関する情報を表示

アプリケーションをビルド

アプリケーションのビルドを開始するには、次を実行します。

hyperlift apps build <app-id>

デフォルトでは、このコマンドは API がビルドリクエストを受け付けた後に戻ります。

ビルドが完了するまで CLI を待機させたい場合は、--wait オプションを追加します。

hyperlift apps build <app-id> --wait

CLI をどれくらい待機させるかを指定することもできます。

hyperlift apps build <app-id> --wait --timeout 15m

デフォルトのタイムアウトは10分です。

アプリケーションを開始、停止、または再起動する

アプリケーションのステータスを管理するには、次のコマンドを使用します。

操作	コマンド
開始	`hyperlift apps start <app-id>`
停止	`hyperlift apps stop <app-id>`
再起動	`hyperlift apps restart <app-id>`

デフォルトでは、これらのコマンドはAPIがリクエストを受け付けた後に戻ります。CLIが操作の完了まで待機するようにするには、--waitを追加します。

例:

hyperlift apps restart <app-id> --wait

アプリケーションログを表示する

logsコマンドを使用して、ランタイムログとビルドログの両方を表示できます。

コマンド	説明
`hyperlift logs <app-id>`	アプリケーションのランタイムログを表示する
`hyperlift logs <app-id> --build`	ビルドログを表示
`hyperlift logs <app-id> --follow` または `hyperlift logs <app-id> --build --follow`	新しいログエントリの確認を継続

注:--follow オプションは、新しいログエントリを定期的に確認します。ライブストリーミング接続は確立しません。

アプリケーションメトリクスを表示

metrics コマンドを使用して、アプリケーションのリソース使用状況を監視します。利用可能なメトリクスは次のとおりです。

メモリ使用量
CPU 使用率
ネットワーク受信レート
ネットワーク送信レート
エフェメラルストレージ使用量
永続ストレージ使用量

コマンド	説明
`hyperlift metrics <app-id>`	利用可能なメトリクスを表示
`hyperlift metrics <app-id> --since 1h`	指定した期間の利用可能なメトリクスを表示
`hyperlift metrics <app-id> --since 1h --interval 5m`	指定したデータポイント内の利用可能なメトリクスを表示

環境変数を管理

envコマンドを使用して、環境変数の表示、追加、更新、削除を行えます。

コマンド	説明
`hyperlift env get <app-id>`	環境変数を表示
`hyperlift env set <app-id> KEY=VALUE`	1 つの環境変数を追加/更新
`hyperlift env set <app-id> KEY1=VALUE1 KEY2=VALUE2`	複数の変数を一度に更新
`hyperlift env unset <app-id> KEY`	環境変数を削除

重要: 環境変数を更新すると、アプリケーションが再起動します。別の環境変数を変更する前に、アプリケーションが再び実行中になるまで待ってください。

Hyperlift は、アプリケーションが利用可能なポートを判断するために APPLICATION_PORT 環境変数を使用します。デフォルト値は 8080 です。

コマンド出力をカスタマイズ

デフォルトでは、Hyperlift CLI コマンドは人が読みやすい形式で情報を表示します。

スクリプトや他のツールで出力を使用する必要がある場合は、次のオプションを使用できます。

コマンド	説明
`hyperlift apps get <app-id> --json`	コマンド出力を JSON 形式で返す
`hyperlift apps list --quiet`	主要な識別子のみを出力
`hyperlift apps get <app-id> --debug`	トラブルシューティング用の追加情報を確認このオプションは、CLI によって行われた HTTP リクエストの秘匿化されたトレースを表示します。

注:--json と --quiet オプションは同時に使用できません。

Hyperlift CLI を更新

コマンド	説明
`hyperlift update --check`	CLI の新しいバージョンが利用可能か確認
`hyperlift update`	最新バージョンをダウンロードしてインストール更新プロセスでは、現在の CLI バージョンを置き換える前に、ダウンロードしたリリースを検証します。
`hyperlift version` または `hyperlift --version`	インストール済みの CLI バージョンを確認

コマンドごとのヘルプを表示

各 Hyperlift CLI コマンドには、それぞれ独自のヘルプ情報があります。

コマンド	説明
`hyperlift --help`	一般的なヘルプを表示
`hyperlift apps --help`	特定のコマンドのヘルプを表示
`hyperlift apps build --help`	個別のアクションのヘルプを表示

ヘルプ出力には、選択したコマンドで利用可能なオプションと引数が含まれます。

最新のコマンド一覧と技術的な詳細については、Hyperlift CLI repositoryを参照してください。