使用 CLI

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

简介

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

CLI 可在 Linux (glibc 和 musl)、macOS 和 Windows 上运行。它以单一 binary 的形式提供，无需额外 dependencies，因此安装和更新都很简单。

无论您是在交互式操作，还是通过脚本、CI pipelines 或 AI agents 自动化 workflows，Stackhero CLI 都同时为人工使用和自动化而设计。每个命令都支持 --format=json 参数，用于 machine-readable output；同时也支持 --format=script，当您想把原始值捕获到 shell variables 时会很方便。

安装

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

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

此命令会下载适用于您平台的正确 binary，并将其安装为 stackhero。CLI 也会自动保持最新状态。

身份验证

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

基于浏览器的交互式登录

stackhero login

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

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

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

以下是一个示例脚本，展示如何创建一个 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 即可。