使用 CLI

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

简介

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

无论您是交互式操作，还是通过脚本、CI 流水线或 AI 代理自动化流程，Stackhero CLI 都为人工与自动化场景而设计。所有命令均支持 --format=json 参数，便于机器读取输出，同时也支持 --format=script，方便将原始值赋给 shell 变量。

安装

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

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 代理。
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 二进制文件即可。