Utilizzare la CLI

Installa e utilizza la Stackhero CLI per gestire i tuoi stack e servizi dalla riga di comando, tramite script, CI e agenti AI

Introduzione

La Stackhero CLI è uno strumento da riga di comando leggero e autonomo, progettato per aiutarti a gestire facilmente i tuoi stack e servizi. Con questa CLI puoi creare ed eliminare servizi, accedere alle credenziali, aggiornare le configurazioni e molto altro, tutto direttamente dal terminale. La CLI è compatibile con Linux (glibc e musl), macOS e Windows, ed è distribuita come un unico file binario senza dipendenze, rendendo l'installazione e gli aggiornamenti semplici e veloci.

Che tu stia lavorando in modo interattivo o automatizzando i flussi di lavoro tramite script, pipeline CI o agenti AI, la Stackhero CLI è pensata sia per l'utilizzo umano che per l'automazione. Ogni comando supporta il flag --format=json per un output leggibile dalle macchine, così come --format=script per acquisire valori grezzi da assegnare a 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 occupa anche di mantenersi aggiornata automaticamente.

Autenticazione

Hai due opzioni principali per l'autenticazione:

Interattiva (login tramite browser)

stackhero login

Quando esegui questo comando, riceverai un URL (che si apre anche automaticamente nel browser). Da lì puoi approvare l'accesso direttamente dalla dashboard di Stackhero, dove sei già autenticato. L'autenticazione a due fattori è pienamente supportata e non dovrai mai inserire la password nella CLI.

Non interattiva (per script, CI e automazione)

Per i flussi di lavoro automatizzati, puoi creare un access token dalla dashboard (Account > Access tokens) e fornirlo alla CLI tramite la variabile d'ambiente STACKHERO_TOKEN.

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

Quando STACKHERO_TOKEN è impostato, ha la precedenza sulle sessioni interattive, quindi non è necessario il browser. Questo è l'approccio raccomandato per gli utilizzi non interattivi. Puoi visualizzare e revocare i token dalla dashboard in qualsiasi momento.

Formati di output

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

• human (predefinito): Produce tabelle e testo leggibili per l'uso interattivo.
• json: Restituisce JSON leggibile dalle macchine, ideale per script e agenti AI.
• script: Restituisce solo i valori grezzi, facilitando l'assegnazione a variabili shell.

Ad esempio:

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

Panoramica dei comandi

Per ottenere l'elenco completo dei comandi disponibili, puoi eseguire stackhero --help. Per informazioni dettagliate su un comando specifico, prova stackhero COMANDO --help.

Alcuni dei comandi più utilizzati 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 recuperare le sue credenziali. Questo esempio è completamente non interattivo e utilizza la variabile d'ambiente STACKHERO_TOKEN.

#!/bin/bash
set -e

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

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

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

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

# Attendi che il servizio sia operativo
stackhero service-wait-for --service-id="${serviceId}"

# Recupera credenziali e configurazione
stackhero service-configuration-get --service-id="${serviceId}" --format=json

La documentazione di ogni servizio include una guida "Automatizza con la CLI" pronta all'uso e specifica per quel servizio, così avrai tutto il necessario per iniziare.

Aggiornamento e disinstallazione

La CLI si aggiorna automaticamente. Se desideri forzare manualmente un aggiornamento, puoi eseguire:

stackhero self-update

Se vuoi disinstallare la CLI, è sufficiente eliminare il binario stackhero dal sistema.