使用 CLI

安裝並使用 Stackhero CLI，從命令列、scripts、CI 及 AI agents 管理您的 stacks 和 services

介紹

Stackhero CLI 是一個輕量、獨立的 command-line 工具，協助您直接在 terminal 管理您的 stacks 和 services。您可以用它來建立及刪除 services、存取 credentials、更新 configurations，以及處理許多其他日常工作。

CLI 可在 Linux (glibc 和 musl)、macOS 及 Windows 上運作。它以單一 binary 形式提供，無需額外相依套件，令安裝和更新都更簡單。

無論您是以互動方式操作，還是使用 scripts、CI pipelines 或 AI agents 自動化 workflows，Stackhero CLI 都同時為人手操作和自動化而設。每個指令都支援 --format=json 旗標，以提供 machine-readable 輸出；當您想在 shell variables 中擷取原始值時，亦可使用 --format=script。

安裝

您可以執行以下指令安裝最新版本：

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

此指令會下載適用於您平台的正確 binary，並將其安裝為 stackhero。CLI 亦會自動保持為最新版本。

驗證

您有兩個主要的驗證方式：

透過瀏覽器進行互動式登入

stackhero login

當您執行此指令時，CLI 會提供一個 URL，並自動在您的瀏覽器中開啟。之後，您可以直接在已登入的 Stackhero dashboard 批准存取。

它完全支援雙重驗證，而您無需在 CLI 中輸入密碼。

用於 scripts、CI 和自動化的非互動式驗證

對於自動化 workflows，您可以在 dashboard 的 Account > Access tokens 建立 access token，然後透過 STACKHERO_TOKEN environment variable 提供給 CLI。

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

當設定了 STACKHERO_TOKEN 後，它會優先於互動式 sessions，因此瀏覽器便屬可選。這種方式非常適合非互動式使用情境。您亦可隨時在 dashboard 檢視及撤銷 tokens。

輸出格式

每個 CLI 指令都接受全域 --format 選項：

human (預設)：顯示易讀的表格和文字，適合互動式使用。
json：回傳 machine-readable JSON，對 scripts 和 AI agents 很有幫助。
script：只回傳原始值，方便將輸出指派給 shell variables。

例如：

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

以下是一個範例 script，示範如何建立 stack、加入 service、等待它準備就緒，以及擷取其 credentials。此範例完全以非互動方式運作，並使用 STACKHERO_TOKEN environment variable。

#!/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 文件頁面都包含一份可直接執行的 Automate with the CLI 指南，並按該 service 度身訂造，讓您具備開始所需的一切。

更新與解除安裝

CLI 會自動保持為最新版本。如果您想手動強制更新，可以執行：

stackhero self-update

如果您想解除安裝 CLI，只需從您的系統中刪除 stackhero binary 即可。