使用 CLI

安装并使用 Stackhero CLI，通过命令行、脚本、CI 和 AI agent 管理您的 stack 和服务

简介

Stackhero CLI 是一款轻量级、独立的命令行工具，旨在帮助您轻松管理 stack 和服务。通过该工具，您可以在终端中创建和删除服务、访问凭证、更新配置等。CLI 兼容 Linux（glibc 和 musl）、macOS 以及 Windows，作为单一二进制文件分发，无需依赖，安装和升级都非常便捷。

无论您是交互式操作，还是通过脚本、CI 流水线或 AI agent 实现自动化，Stackhero CLI 都适用于人工和自动化场景。每个命令都支持 --format=json 参数，便于机器读取输出，同时也支持 --format=script，方便将原始值赋给 shell 变量。

安装

您可以通过以下命令安装最新版：

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

此命令会自动下载适合您平台的二进制文件，并以 stackhero 名称安装。CLI 还会自动保持自身为最新版本。

认证

您有两种主要的认证方式：

交互式（基于浏览器登录）

stackhero login

运行该命令后，您会收到一个 URL（也会自动在浏览器中打开）。您可以直接在已登录的 Stackhero 控制台中授权访问。完全支持双因素认证，您无需在 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 agent。
script：仅返回原始值，便于赋值给 shell 变量。

例如：

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

示例：端到端创建服务

以下是一个示例脚本，演示如何创建 stack、添加服务、等待服务就绪并获取凭证。该示例为全自动化，使用 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 获取

# 创建 stack
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 二进制文件即可。