使用 CLI

安装并使用 Stackhero CLI，从命令行、脚本、CI 和 AI agents 管理您的 stacks 和 services

介绍

Stackhero CLI 是一个轻量级、独立的命令行工具，可帮助您直接在终端中管理您的 stacks 和 services。您可以用它来创建和删除 services、访问凭据、更新配置，以及处理许多其他日常任务。

CLI 可在 Linux（glibc 和 musl）、macOS 和 Windows 上运行。它以单个二进制文件的形式提供，无需额外依赖，因此安装和更新都很简单。

无论您是在交互式使用，还是通过脚本、CI pipelines 或 AI agents 自动化 workflows，Stackhero CLI 都同时为人工操作和自动化而设计。每条命令都支持 --format=json 标志，以提供机器可读的输出；当您希望在 shell 变量中获取原始值时，还支持 --format=script。

安装

您可以运行以下命令来安装最新版本：

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

此命令会下载适用于您平台的正确二进制文件，并将其安装为 stackhero。CLI 还会自动保持最新。

身份验证

您有两种主要的身份验证方式：

基于浏览器的交互式登录

stackhero login

运行此命令时，CLI 会向您提供一个 URL，并且还会自动在您的浏览器中打开它。然后，您可以直接在已登录的 Stackhero dashboard 中批准访问。

完全支持双因素身份验证，并且您无需在 CLI 中输入密码。

用于脚本、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，这对脚本和 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

下面是一个示例脚本，展示了如何创建一个 stack、添加一个 service、等待其就绪并获取其凭据。此示例完全是非交互式的，并使用 STACKHERO_TOKEN 环境变量。

#!/bin/bash
set -e

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

serviceStore="directus"   # 服务 store 名称。参见：`stackhero services-store-list`
instance="1GB"            # 实例（大小）名称。参见：`stackhero instances-store-list --service-store=directus`
region="europe"           # 区域名称。参见：`stackhero regions-list`

# 创建一个 stack（使用您唯一的 organization，如果您有多个，请添加 `--organization`）
stackId=$(stackhero --format=script stack-create \
  --name="My stack")
echo "Stack: ${stackId}"

# 添加一个 service（名称会自动解析，上面的 stack ID 也同样可用）
serviceId=$(stackhero --format=script service-add \
  --stack="My stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service: ${serviceId}"

# 等待 service 进入运行状态
stackhero service-wait-for --service="${serviceId}"

# 获取凭据和配置
stackhero service-configuration-get --service="${serviceId}" --format=json

每个 service 文档页面都包含一个可直接运行的 Automate with the CLI 指南，并且针对该 service 进行了定制，因此您可以获得开始所需的一切。

更新和卸载

CLI 会自动保持最新。如果您想手动强制更新，可以运行：

stackhero self-update

如果您想卸载 CLI，只需从系统中删除 stackhero 二进制文件即可。