Usare la CLI

Installa e usa la CLI di Stackhero per gestire stack e servizi dalla riga di comando, da script, CI e agenti AI

Introduzione

La CLI di Stackhero è uno strumento da riga di comando leggero e autonomo che ti aiuta a gestire i tuoi stack e servizi direttamente dal terminale. Puoi usarlo per creare ed eliminare servizi, accedere alle credenziali, aggiornare configurazioni e gestire molte altre attività quotidiane.

La CLI funziona su Linux (glibc e musl), macOS e Windows. Viene distribuita come un unico binario senza dipendenze aggiuntive, il che rende semplici l'installazione e gli aggiornamenti.

Che tu stia lavorando in modo interattivo o automatizzando workflow con script, pipeline CI o agenti AI, la CLI di Stackhero è progettata sia per le persone sia per l'automazione. Ogni comando supporta l'opzione --format=json per un output leggibile dalle macchine, insieme a --format=script quando vuoi acquisire valori grezzi in variabili shell.

Installazione

Puoi installare l'ultima versione eseguendo:

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

Questo comando scarica il binario corretto per la tua piattaforma e lo installa come stackhero. La CLI si mantiene anche aggiornata automaticamente.

Autenticazione

Hai due opzioni principali per l'autenticazione:

Accesso interattivo tramite browser

stackhero login

Quando esegui questo comando, la CLI ti fornisce un URL e lo apre automaticamente anche nel browser. Da lì, puoi approvare l'accesso direttamente dalla dashboard di Stackhero, dove hai già effettuato l'accesso.

L'autenticazione a due fattori è pienamente supportata e non devi inserire la password nella CLI.

Autenticazione non interattiva per script, CI e automazione

Per i workflow automatizzati, puoi creare un access token nella dashboard in Account > Access tokens e fornirlo alla CLI con la variabile d'ambiente STACKHERO_TOKEN.

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

Quando STACKHERO_TOKEN è impostata, ha la precedenza sulle sessioni interattive, quindi il browser è facoltativo. Questo approccio funziona bene per i casi d'uso non interattivi. Puoi controllare e revocare i token dalla dashboard in qualsiasi momento.

Formati di output

Ogni comando della CLI accetta un'opzione globale --format:

• human (predefinito): mostra tabelle e testo leggibili per l'uso interattivo.
• json: restituisce JSON leggibile dalle macchine, utile per script e agenti AI.
• script: restituisce solo il valore o i valori grezzi, il che rende semplice assegnare l'output a variabili shell.

Per esempio:

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

Panoramica dei comandi

Se vuoi vedere l'elenco completo dei comandi disponibili, puoi eseguire stackhero --help. Se vuoi i dettagli di un comando specifico, puoi provare stackhero COMMAND --help.

Alcuni comandi usati più comunemente includono:

• 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

Esempio: creare un servizio end-to-end

Ecco uno script di esempio che mostra come creare uno stack, aggiungere un servizio, attendere che sia pronto e recuperarne le credenziali. Questo esempio è completamente non interattivo e usa la variabile d'ambiente STACKHERO_TOKEN.

#!/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

Ogni pagina della documentazione di un servizio include una guida Automate with the CLI pronta all'uso e adattata a quel servizio, così hai tutto ciò che ti serve per iniziare.

Aggiornamento e disinstallazione

La CLI si mantiene aggiornata automaticamente. Se vuoi forzare manualmente un aggiornamento, puoi eseguire:

stackhero self-update

Se vuoi disinstallare la CLI, ti basta eliminare il binario stackhero dal sistema.