Usar la CLI

Instale y use 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 que le ayuda a gestionar sus stacks y servicios directamente desde su terminal. Puede usarla para crear y eliminar servicios, acceder a credenciales, actualizar configuraciones y gestionar muchas otras tareas cotidianas.

La CLI funciona en Linux (glibc y musl), macOS y Windows. Se distribuye como un único binario sin dependencias adicionales, lo que simplifica la instalación y las actualizaciones.

Tanto si trabaja de forma interactiva como si automatiza workflows con scripts, pipelines de CI o agentes de IA, la CLI de Stackhero está diseñada tanto para personas como para la automatización. Cada comando admite la opción --format=json para una salida legible por máquina, así como --format=script cuando quiera capturar valores sin procesar 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 correcto para su plataforma y lo instala como stackhero. La CLI también se mantiene actualizada automáticamente.

Autenticación

Tiene dos opciones principales de autenticación:

Inicio de sesión interactivo mediante navegador

stackhero login

Cuando ejecuta este comando, la CLI le proporciona una URL y también la abre 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 de dos factores es totalmente compatible, y no necesita introducir su contraseña en la CLI.

Autenticación no interactiva para scripts, CI y automatización

Para workflows automatizados, puede crear un token de acceso en su panel, en Account > Access tokens, y proporcionárselo a la CLI con la variable de entorno STACKHERO_TOKEN.

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

Cuando STACKHERO_TOKEN está definido, tiene prioridad sobre las sesiones interactivas, por lo que el navegador pasa a ser opcional. Este enfoque funciona muy bien para casos de uso no interactivos. Puede revisar y revocar tokens desde su panel en cualquier momento.

Formatos de salida

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

• human (predeterminado): Muestra tablas y texto legibles para uso interactivo.
• json: Devuelve JSON legible por máquina, lo que resulta útil para scripts y agentes de IA.
• script: Devuelve solo el valor o los valores sin procesar, lo que facilita asignar la salida a variables de shell.

Por ejemplo:

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

Resumen de comandos

Si quiere ver la lista completa de comandos disponibles, puede ejecutar stackhero --help. Si quiere ver detalles de un comando concreto, puede probar con stackhero COMMAND --help.

Algunos comandos de uso habitual 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

Aquí tiene un script de ejemplo que muestra cómo puede crear un stack, añadir un servicio, esperar a que esté listo y recuperar sus credenciales. Este ejemplo es totalmente no interactivo y utiliza la variable de entorno STACKHERO_TOKEN.

#!/bin/bash
set -e

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

serviceStore="directus"   # Un nombre de service store. Ver: `stackhero services-store-list`
instance="1GB"            # Un nombre de instancia (tamaño). Ver: `stackhero instances-store-list --service-store=directus`
region="europe"           # Un nombre de región. Ver: `stackhero regions-list`

# Crear un stack (usa su única organización, añada `--organization` si tiene varias)
stackId=$(stackhero --format=script stack-create \
  --name="My stack")
echo "Stack: ${stackId}"

# Añadir un servicio (los nombres se resuelven automáticamente, y el ID del stack anterior también funciona)
serviceId=$(stackhero --format=script service-add \
  --stack="My stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service: ${serviceId}"

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

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

Cada página de documentación de servicio incluye una guía Automate with the CLI lista para usar y adaptada a ese servicio, para que tenga todo lo necesario para empezar.

Actualización y desinstalación

La CLI se mantiene actualizada automáticamente. Si alguna vez quiere forzar una actualización manualmente, puede ejecutar:

stackhero self-update

Si quiere desinstalar la CLI, solo tiene que eliminar el binario stackhero de su sistema.