Utiliser la CLI

Installez et utilisez la CLI Stackhero pour gérer vos stacks et services depuis la ligne de commande, des scripts, du CI et des agents IA

Introduction

La CLI Stackhero est un outil en ligne de commande léger et autonome qui vous permet de gérer vos stacks et services directement depuis votre terminal. Vous pouvez l'utiliser pour créer et supprimer des services, accéder aux identifiants, mettre à jour les configurations et effectuer de nombreuses tâches courantes.

La CLI fonctionne sous Linux (glibc et musl), macOS et Windows. Elle est distribuée sous la forme d'un binaire unique sans dépendances supplémentaires, ce qui simplifie l'installation et les mises à jour.

Que vous travailliez de façon interactive ou que vous automatisiez vos workflows avec des scripts, des pipelines CI ou des agents IA, la CLI Stackhero est conçue aussi bien pour les utilisateurs que pour l'automatisation. Chaque commande prend en charge l'option --format=json pour un affichage lisible par une machine, ainsi que --format=script si vous souhaitez récupérer des valeurs brutes dans des variables shell.

Installation

Vous pouvez installer la dernière version en exécutant :

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

Cette commande télécharge le binaire adapté à votre plateforme et l'installe sous le nom stackhero. La CLI se met également à jour automatiquement.

Authentification

Vous disposez de deux principales options pour l'authentification :

Connexion interactive via le navigateur

stackhero login

Lorsque vous lancez cette commande, la CLI vous fournit une URL et l'ouvre automatiquement dans votre navigateur. Vous pouvez alors approuver l'accès directement depuis votre tableau de bord Stackhero, où vous êtes déjà connecté.

L'authentification à deux facteurs est entièrement prise en charge et vous n'avez pas besoin de saisir votre mot de passe dans la CLI.

Authentification non interactive pour scripts, CI et automatisation

Pour les workflows automatisés, vous pouvez créer un jeton d'accès dans votre tableau de bord, sous Account > Access tokens, puis le fournir à la CLI via la variable d'environnement STACKHERO_TOKEN.

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

Lorsque STACKHERO_TOKEN est défini, il prend le dessus sur les sessions interactives, donc l'utilisation du navigateur devient facultative. Cette méthode est idéale pour les usages non interactifs. Vous pouvez consulter et révoquer vos jetons à tout moment depuis votre tableau de bord.

Formats de sortie

Chaque commande de la CLI accepte une option globale --format :

• human (par défaut) : Affiche des tableaux et du texte lisibles pour un usage interactif.
• json : Retourne du JSON lisible par une machine, pratique pour les scripts et agents IA.
• script : Retourne uniquement la ou les valeurs brutes, ce qui facilite l'affectation à des variables shell.

Par exemple :

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

Aperçu des commandes

Pour afficher la liste complète des commandes disponibles, vous pouvez exécuter stackhero --help. Pour obtenir des détails sur une commande spécifique, essayez stackhero COMMAND --help.

Voici quelques commandes couramment utilisées :

• 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

Exemple : Créer un service de bout en bout

Voici un exemple de script qui montre comment créer un stack, ajouter un service, attendre qu'il soit prêt et récupérer ses identifiants. Cet exemple est entièrement non interactif et utilise la variable d'environnement STACKHERO_TOKEN.

#!/bin/bash
set -e

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

serviceStore="directus"   # Nom d'un service store. Voir : `stackhero services-store-list`
instance="1GB"            # Nom d'une instance (taille). Voir : `stackhero instances-store-list --service-store=directus`
region="europe"           # Nom d'une région. Voir : `stackhero regions-list`

# Créer un stack (utilise votre seule organisation, ajoutez `--organization` si vous en avez plusieurs)
stackId=$(stackhero --format=script stack-create \
  --name="My stack")
echo "Stack: ${stackId}"

# Ajouter un service (les noms sont résolus automatiquement, et l'ID du stack ci-dessus fonctionne aussi)
serviceId=$(stackhero --format=script service-add \
  --stack="My stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service: ${serviceId}"

# Attendre que le service soit en fonctionnement
stackhero service-wait-for --service="${serviceId}"

# Récupérer les identifiants et la configuration
stackhero service-configuration-get --service="${serviceId}" --format=json

Chaque page de documentation de service inclut un guide Automatiser avec la CLI prêt à l'emploi, adapté à ce service, pour que vous ayez tout ce qu'il vous faut pour démarrer.

Mise à jour et désinstallation

La CLI se met à jour automatiquement. Si vous souhaitez forcer une mise à jour manuelle, vous pouvez exécuter :

stackhero self-update

Pour désinstaller la CLI, il suffit de supprimer le binaire stackhero de votre système.