CLIを使う

Stackhero CLIをインストールして使用し、コマンドライン、スクリプト、CI、AIエージェントからstackやserviceを管理します

はじめに

Stackhero CLI は、軽量で自己完結型のコマンドラインツールで、ターミナルから直接stackやserviceを管理するのに役立ちます。serviceの作成と削除、認証情報へのアクセス、設定の更新、そのほか日常的な多くの作業に利用できます。

CLIはLinux（glibc と musl）、macOS、Windowsで動作します。追加の依存関係がない単一のバイナリとして提供されるため、インストールとアップデートを簡単に行えます。

対話的に作業する場合でも、スクリプト、CIパイプライン、AIエージェントでworkflowを自動化する場合でも、Stackhero CLIは人による操作と自動化の両方を想定して設計されています。すべてのコマンドは、機械可読な出力のための --format=json フラグと、shell変数に生の値を取り込みたい場合の --format=script の両方をサポートしています。

インストール

次を実行すると、最新バージョンをインストールできます:

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

このコマンドは、お使いのプラットフォームに適したバイナリをダウンロードし、stackhero としてインストールします。CLIは自動的に自身を最新の状態に保ちます。

認証

認証には主に2つの方法があります:

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

stackhero login

このコマンドを実行すると、CLIはURLを表示し、同時にブラウザで自動的に開きます。そこから、すでにサインイン済みのStackheroダッシュボード上で直接アクセスを承認できます。

二要素認証にも完全に対応しており、CLIでパスワードを入力する必要はありません。

スクリプト、CI、自動化向けの非対話型認証

自動化されたworkflowでは、ダッシュボードの Account > Access tokens でaccess tokenを作成し、STACKHERO_TOKEN 環境変数を使ってCLIに渡すことができます。

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

STACKHERO_TOKEN が設定されている場合、対話型セッションよりも優先されるため、ブラウザの使用は任意になります。この方法は非対話型のユースケースに適しています。tokenはいつでもダッシュボードから確認および無効化できます。

出力形式

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

human (default): 対話的な利用向けに、読みやすいテーブルとテキストを表示します。
json: 機械可読なJSONを返します。スクリプトやAIエージェントで役立ちます。
script: 生の値のみを返すため、出力をshell変数に代入しやすくなります。

例:

stackhero organizations-list --format=json
stackId=$(stackhero --format=script stack-create --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

例: serviceを最初から最後まで作成する

以下は、stackを作成し、serviceを追加し、利用可能になるまで待機し、その認証情報を取得する方法を示すサンプルスクリプトです。この例は完全に非対話型で、STACKHERO_TOKEN 環境変数を使用します。

#!/bin/bash
set -e

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

serviceStore="directus"   # A service store name. See: `stackhero services-store-list`
instance="1GB"            # An instance (size) name. See: `stackhero instances-store-list --service-store=directus`
region="europe"           # A region name. See: `stackhero regions-list`

# Create a stack (uses your only organization, add `--organization` if you have several)
stackId=$(stackhero --format=script stack-create \
  --name="My stack")
echo "Stack: ${stackId}"

# Add a service (names are resolved automatically, and the stack ID above also works)
serviceId=$(stackhero --format=script service-add \
  --stack="My stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service: ${serviceId}"

# Wait for the service to be running
stackhero service-wait-for --service="${serviceId}"

# Retrieve credentials and configuration
stackhero service-configuration-get --service="${serviceId}" --format=json

各serviceのドキュメントページには、そのservice向けに調整された、すぐに実行できる Automate with the CLI ガイドが含まれているため、使い始めるために必要なものがすべて揃っています。

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

CLIは自動的に自身を最新の状態に保ちます。手動で強制的にアップデートしたい場合は、次を実行できます:

stackhero self-update

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