CLIの利用方法

Stackhero CLIをインストールして、コマンドライン、スクリプト、CI、AIエージェントからスタックやサービスを管理する方法

はじめに

Stackhero CLI は、スタックやサービスの管理を簡単に行うために設計された、軽量かつ自己完結型のコマンドラインツールです。これを使えば、サービスの作成・削除、認証情報へのアクセス、設定の更新など、さまざまな操作をターミナルから実行できます。CLIはLinux（glibcおよびmusl）、macOS、Windowsに対応しており、依存関係のない単一バイナリとして提供されるため、インストールやアップデートも容易です。

対話的な操作はもちろん、スクリプトやCIパイプライン、AIエージェントによる自動化にも最適化されています。すべてのコマンドは、マシンリーダブルな出力を得るための --format=json フラグや、シェル変数への値の格納に便利な --format=script フラグに対応しています。

インストール

最新バージョンは以下のコマンドでインストールできます：

curl -fsSL https://www.stackhero.io/install.sh | sh

このコマンドは、ご利用のプラットフォームに適したバイナリをダウンロードし、stackhero としてインストールします。CLIは自動的に自身のアップデートも行います。

認証

認証方法は主に2つあります：

対話型（ブラウザベースのログイン）

stackhero login

このコマンドを実行すると、URLが表示され（自動的にブラウザも開きます）、すでにサインインしているStackheroダッシュボードからアクセスを承認できます。2要素認証にも完全対応しており、CLIにパスワードを入力する必要はありません。

非対話型（スクリプト、CI、自動化向け）

自動化されたワークフローの場合は、ダッシュボードからアクセストークン（Account > Access tokens）を作成し、STACKHERO_TOKEN 環境変数を使ってCLIに渡します。

export STACKHERO_TOKEN="usr-xxxxxx:your-token"
stackhero organizations-list

STACKHERO_TOKEN が設定されている場合、対話型セッションよりも優先されるため、ブラウザは不要です。非対話型の利用にはこの方法が推奨されます。トークンの確認や失効は、いつでもダッシュボードから行えます。

出力フォーマット

CLIのすべてのコマンドは、グローバルな --format オプションを受け付けます：

human（デフォルト）：対話的な利用向けに、読みやすいテーブルやテキストを出力します。
json：マシンリーダブルなJSONを出力し、スクリプトやAIエージェントに最適です。
script：生の値のみを返し、シェル変数への代入が容易です。

例：

stackhero organizations-list --format=json
stackId=$(stackhero --format=script stack-create --organization-id=org-xxxxxx --name="My stack")

コマンド概要

利用可能なコマンドの全リストは stackhero --help で確認できます。特定のコマンドの詳細は stackhero COMMAND --help をご利用ください。

よく使われるコマンド例：

Organizations: organizations-list
Stacks: stacks-list, stack-create, stack-rename, stack-delete
Services: services-list, service-add, service-wait-for, service-rename, service-delete
Configuration: service-configuration-get, service-configuration-set, service-configuration-example
Store: services-store-list, instances-store-list, regions-list
Upgrades: service-upgrade-instances-store-list, service-upgrade-instance
Account: login, logout
Maintenance: self-update

例：サービスをエンドツーエンドで作成する

以下は、スタックの作成、サービスの追加、サービスの起動待ち、認証情報の取得までを自動化するサンプルスクリプトです。この例は完全に非対話型で、STACKHERO_TOKEN 環境変数を利用しています。

#!/bin/bash
set -e

export STACKHERO_TOKEN="usr-xxxxxx:your-token"

organizationId="org-xxxxxx"
serviceStoreId="svs-xxxxxx"   # これは次のコマンドで確認できます: stackhero services-store-list --organization-id=org-xxxxxx
instanceStoreId="ist-xxxxxx"  # これは次のコマンドで確認できます: stackhero instances-store-list --organization-id=org-xxxxxx --service-store-id=svs-xxxxxx
regionId="europe"             # これは次のコマンドで確認できます: stackhero regions-list

# スタックを作成
stackId=$(stackhero --format=script stack-create \
  --organization-id="${organizationId}" \
  --name="My stack")
echo "Stack: ${stackId}"

# サービスを追加
serviceId=$(stackhero --format=script service-add \
  --stack-id="${stackId}" \
  --service-store-id="${serviceStoreId}" \
  --instance-store-id="${instanceStoreId}" \
  --region-id="${regionId}")
echo "Service: ${serviceId}"

# サービスの起動を待機
stackhero service-wait-for --service-id="${serviceId}"

# 認証情報と設定を取得
stackhero service-configuration-get --service-id="${serviceId}" --format=json

各サービスのドキュメントには、そのサービス専用の「CLIによる自動化」ガイドが用意されているため、すぐに始めることができます。

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

CLIは自動的に最新状態を保ちます。手動でアップデートを強制したい場合は、以下のコマンドを実行してください：

stackhero self-update

CLIをアンインストールしたい場合は、stackhero バイナリをシステムから削除するだけです。