Utilizar a CLI

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

Introdução

A CLI Stackhero é uma ferramenta de linha de comandos leve e autónoma que o ajuda a gerir as suas stacks e serviços diretamente a partir do terminal. Pode utilizá-la para criar e eliminar serviços, aceder a credenciais, atualizar configurações e tratar de muitas outras tarefas do dia a dia.

A CLI funciona em Linux (glibc e musl), macOS e Windows. É disponibilizada como um único binário, sem dependências adicionais, o que simplifica a instalação e as atualizações.

Quer esteja a trabalhar de forma interativa ou a automatizar workflows com scripts, pipelines de CI ou agentes de IA, a CLI Stackhero foi concebida tanto para pessoas como para automação. Todos os comandos suportam a opção --format=json para saída legível por máquina, bem como --format=script quando quiser capturar valores brutos em variáveis 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 se mantém atualizada automaticamente.

Autenticação

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

Início de sessão interativo através do navegador

stackhero login

Quando executa este comando, a CLI fornece-lhe um URL e também o abre automaticamente no navegador. A partir daí, pode aprovar o acesso diretamente no seu dashboard Stackhero, onde já tem sessão iniciada.

A autenticação de dois fatores é totalmente suportada e não precisa de introduzir a sua palavra-passe na CLI.

Autenticação não interativa para scripts, CI e automação

Para workflows automatizados, pode criar um access token no seu dashboard em Account > Access tokens e fornecê-lo à CLI com a variável de ambiente STACKHERO_TOKEN.

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

Quando STACKHERO_TOKEN está definido, tem prioridade sobre as sessões interativas, pelo que a utilização de um navegador é opcional. Esta abordagem funciona bem para casos de uso não interativos. Pode consultar e revogar tokens no seu dashboard a qualquer momento.

Formatos de saída

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

• human (predefinido): Mostra tabelas e texto legíveis para utilização interativa.
• json: Devolve JSON legível por máquina, o que é útil para scripts e agentes de IA.
• script: Devolve apenas valor(es) brutos, o que facilita a atribuição da saída a variáveis shell.

Por exemplo:

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

Visão geral dos comandos

Se quiser ver a lista completa dos comandos disponíveis, pode executar stackhero --help. Se quiser detalhes sobre um comando específico, pode experimentar stackhero COMMAND --help.

Alguns comandos frequentemente 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

Eis um exemplo de script que mostra como pode criar uma stack, adicionar um serviço, esperar que fique 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"

serviceStore="directus"   # Um nome de service store. Ver: `stackhero services-store-list`
instance="1GB"            # Um nome de instância (tamanho). Ver: `stackhero instances-store-list --service-store=directus`
region="europe"           # Um nome de região. Ver: `stackhero regions-list`

# Criar uma stack (utiliza a sua única organização, adicione `--organization` se tiver várias)
stackId=$(stackhero --format=script stack-create \
  --name="My stack")
echo "Stack: ${stackId}"

# Adicionar um serviço (os nomes são resolvidos automaticamente, e o ID da stack acima também funciona)
serviceId=$(stackhero --format=script service-add \
  --stack="My stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service: ${serviceId}"

# Esperar que o serviço esteja em execução
stackhero service-wait-for --service="${serviceId}"

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

Cada página de documentação de serviço inclui um guia Automate with the CLI pronto a executar, 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 quiser forçar manualmente uma atualização, pode executar:

stackhero self-update

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