使用 CLI

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

介紹

Stackhero CLI 是一個輕量、獨立的命令列工具，可協助您直接從終端機管理您的 stacks 與 services。您可以用它來建立與刪除 services、存取 credentials、更新 configurations，以及處理許多其他日常工作。

CLI 可在 Linux（glibc 與 musl）、macOS 和 Windows 上運作。它以單一 binary 的形式提供，無需額外相依套件，因此安裝與更新都很簡單。

無論您是以互動方式操作，還是使用 scripts、CI pipelines 或 AI agents 來自動化 workflows，Stackhero CLI 都同時為人員操作與自動化而設計。每個命令都支援 --format=json 旗標，可提供機器可讀的輸出；當您想在 shell 變數中擷取原始值時，也可使用 --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 環境變數提供給 CLI。

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

設定 STACKHERO_TOKEN 後，它會優先於互動式工作階段，因此是否使用瀏覽器就變成可選。這種方式非常適合非互動式使用情境。您可以隨時在 dashboard 中檢視並撤銷 tokens。

輸出格式

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

human（預設）：顯示適合互動式使用的可讀表格與文字。
json：回傳機器可讀的 JSON，對 scripts 與 AI agents 很有幫助。
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

以下是一個範例 script，示範如何建立 stack、加入 service、等待其就緒，並擷取其 credentials。此範例完全採用非互動方式，並使用 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 文件頁面都包含一份可直接執行的 Automate with the CLI 指南，並依該 service 量身打造，讓您擁有開始使用所需的一切。

更新與解除安裝

CLI 會自動保持在最新狀態。如果您想手動強制更新，可以執行：

stackhero self-update

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