Usar la CLI

Instale y utilice la CLI de Stackhero para gestionar sus stacks y servicios desde la línea de comandos, scripts, CI y agentes de IA

Introducción

La CLI de Stackhero es una herramienta de línea de comandos ligera y autónoma, diseñada para ayudarle a gestionar sus stacks y servicios de forma sencilla. Con ella, puede crear y eliminar servicios, acceder a credenciales, actualizar configuraciones y mucho más, todo desde su terminal. La CLI es compatible con Linux (glibc y musl), macOS y Windows, y se distribuye como un único binario sin dependencias, lo que facilita tanto la instalación como las actualizaciones.

Tanto si trabaja de forma interactiva como si automatiza flujos de trabajo mediante scripts, pipelines de CI o agentes de IA, la CLI de Stackhero está pensada para personas y para la automatización. Cada comando admite la opción --format=json para obtener una salida legible por máquina, así como --format=script para capturar valores en bruto en variables de shell.

Instalación

Puede instalar la última versión ejecutando:

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

Este comando descarga el binario adecuado para su plataforma e instala la CLI como stackhero. Además, la CLI se encarga de mantenerse actualizada automáticamente.

Autenticación

Dispone de dos opciones principales para autenticarse:

Interactiva (inicio de sesión mediante navegador)

stackhero login

Al ejecutar este comando, recibirá una URL (que también se abrirá automáticamente en su navegador). Desde ahí, puede aprobar el acceso directamente desde su panel de Stackhero, donde ya ha iniciado sesión. La autenticación en dos factores está totalmente soportada y nunca tendrá que introducir su contraseña en la CLI.

No interactiva (para scripts, CI y automatización)

Para flujos de trabajo automatizados, puede crear un access token en su panel (Cuenta > Access tokens) y proporcionarlo a la CLI mediante la variable de entorno STACKHERO_TOKEN.

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

Cuando se define STACKHERO_TOKEN, tiene prioridad sobre las sesiones interactivas, por lo que no es necesario utilizar el navegador. Este es el método recomendado para casos de uso no interactivos. Puede consultar y revocar sus tokens en cualquier momento desde su panel.

Formatos de salida

Cada comando de la CLI acepta la opción global --format:

• human (por defecto): Muestra tablas y texto legibles para uso interactivo.
• json: Devuelve JSON legible por máquina, ideal para scripts y agentes de IA.
• script: Devuelve únicamente los valores en bruto, facilitando su asignación a variables de shell.

Por ejemplo:

stackhero organizations-list --format=json
stackId=$(stackhero --format=script stack-create --organization-id=org-xxxxxx --name="My stack")

Resumen de comandos

Si desea ver la lista completa de comandos disponibles, puede ejecutar stackhero --help. Para información detallada sobre un comando específico, utilice stackhero COMANDO --help.

Algunos de los comandos más utilizados son:

• 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

Ejemplo: Crear un servicio de principio a fin

A continuación, se muestra un script de ejemplo que demuestra cómo crear un stack, añadir un servicio, esperar a que esté listo y recuperar sus credenciales. Este ejemplo es completamente no interactivo y utiliza la variable de entorno STACKHERO_TOKEN.

#!/bin/bash
set -e

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

organizationId="org-xxxxxx"
serviceStoreId="svs-xxxxxx"   # Puede encontrarlo con: stackhero services-store-list --organization-id=org-xxxxxx
instanceStoreId="ist-xxxxxx"  # Puede encontrarlo con: stackhero instances-store-list --organization-id=org-xxxxxx --service-store-id=svs-xxxxxx
regionId="europe"             # Puede encontrarlo con: stackhero regions-list

# Crear un stack
stackId=$(stackhero --format=script stack-create \
  --organization-id="${organizationId}" \
  --name="My stack")
echo "Stack: ${stackId}"

# Añadir un servicio
serviceId=$(stackhero --format=script service-add \
  --stack-id="${stackId}" \
  --service-store-id="${serviceStoreId}" \
  --instance-store-id="${instanceStoreId}" \
  --region-id="${regionId}")
echo "Service: ${serviceId}"

# Esperar a que el servicio esté en funcionamiento
stackhero service-wait-for --service-id="${serviceId}"

# Recuperar credenciales y configuración
stackhero service-configuration-get --service-id="${serviceId}" --format=json

La documentación de cada servicio incluye una guía "Automatizar con la CLI" lista para usar y adaptada a ese servicio, por lo que dispondrá de todo lo necesario para empezar.

Actualización y desinstalación

La CLI se actualiza automáticamente. Si en algún momento desea forzar una actualización manualmente, puede ejecutar:

stackhero self-update

Si desea desinstalar la CLI, simplemente elimine el binario stackhero de su sistema.