Utilizar a CLI

Instale e utilize a Stackhero CLI para gerir os seus stacks e serviços a partir da linha de comandos, scripts, CI e agentes de IA

Introdução

A Stackhero CLI é uma ferramenta de linha de comandos leve e autónoma, concebida para o ajudar a gerir stacks e serviços de forma simples. Com ela, pode criar e eliminar serviços, aceder a credenciais, atualizar configurações e muito mais, tudo a partir do seu terminal. A CLI é compatível com Linux (glibc e musl), macOS e Windows, e é disponibilizada como um único binário sem dependências, facilitando a instalação e as atualizações.

Quer esteja a trabalhar de forma interativa ou a automatizar fluxos de trabalho com scripts, pipelines de CI ou agentes de IA, a Stackhero CLI foi desenvolvida tanto para utilização humana como para automação. Todos os comandos suportam a flag --format=json para saída legível por máquina, bem como --format=script para capturar valores brutos em variáveis de shell.

Instalação

Pode instalar a versão mais recente executando:

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

Este comando transfere o binário correto para a sua plataforma e instala-o como stackhero. A CLI também trata de se manter atualizada automaticamente.

Autenticação

Tem duas opções principais para autenticação:

Interativa (login via browser)

stackhero login

Ao executar este comando, receberá um URL (que também é aberto automaticamente no seu browser). A partir daí, pode aprovar o acesso diretamente no seu dashboard Stackhero, onde já está autenticado. A autenticação de dois fatores é totalmente suportada e nunca terá de introduzir a sua palavra-passe na CLI.

Não interativa (para scripts, CI e automação)

Para fluxos de trabalho automatizados, pode criar um access token no seu dashboard (Conta > Access tokens) e fornecê-lo à CLI através da variável de ambiente STACKHERO_TOKEN.

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

Quando STACKHERO_TOKEN está definido, tem prioridade sobre sessões interativas, pelo que não é necessário browser. Esta é a abordagem recomendada para utilizações não interativas. Pode consultar e revogar tokens a qualquer momento no seu dashboard.

Formatos de saída

Todos os comandos da CLI aceitam a opção global --format:

• human (predefinido): Produz tabelas e texto legíveis para utilização interativa.
• json: Gera JSON legível por máquina, ideal para scripts e agentes de IA.
• script: Devolve apenas o(s) valor(es) bruto(s), facilitando a atribuição a variáveis de shell.

Por exemplo:

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

Visão geral dos comandos

Se procura a lista completa de comandos disponíveis, pode executar stackhero --help. Para obter informações detalhadas sobre um comando específico, utilize stackhero COMANDO --help.

Alguns dos comandos mais utilizados incluem:

• 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

Exemplo: Criar um serviço de ponta a ponta

Segue-se um exemplo de script que demonstra como pode criar um stack, adicionar um serviço, aguardar que esteja pronto e obter as respetivas credenciais. Este exemplo é totalmente não interativo e utiliza a variável de ambiente STACKHERO_TOKEN.

#!/bin/bash
set -e

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

organizationId="org-xxxxxx"
serviceStoreId="svs-xxxxxx"   # Pode encontrar este valor com: stackhero services-store-list --organization-id=org-xxxxxx
instanceStoreId="ist-xxxxxx"  # Pode encontrar este valor com: stackhero instances-store-list --organization-id=org-xxxxxx --service-store-id=svs-xxxxxx
regionId="europe"             # Pode encontrar este valor com: stackhero regions-list

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

# Adicionar um serviço
serviceId=$(stackhero --format=script service-add \
  --stack-id="${stackId}" \
  --service-store-id="${serviceStoreId}" \
  --instance-store-id="${instanceStoreId}" \
  --region-id="${regionId}")
echo "Service: ${serviceId}"

# Aguardar que o serviço esteja operacional
stackhero service-wait-for --service-id="${serviceId}"

# Obter credenciais e configuração
stackhero service-configuration-get --service-id="${serviceId}" --format=json

A documentação de cada serviço inclui um guia "Automatizar com a CLI" pronto a usar, adaptado a esse serviço, para que tenha tudo o que precisa para começar.

Atualização e desinstalação

A CLI mantém-se atualizada automaticamente. Se pretender forçar uma atualização manualmente, pode executar:

stackhero self-update

Se quiser desinstalar a CLI, basta eliminar o binário stackhero do seu sistema.