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, conçu pour vous permettre de gérer facilement vos stacks et services. Avec cet outil, vous pouvez créer et supprimer des services, accéder aux identifiants, mettre à jour les configurations et bien plus encore, directement depuis votre terminal. La CLI est compatible avec Linux (glibc et musl), macOS et Windows, et se présente sous la forme d'un binaire unique sans dépendances, ce qui facilite son installation et ses mises à jour.

Que vous travailliez de manière interactive ou que vous automatisiez vos workflows avec des scripts, des pipelines CI ou des agents IA, la CLI Stackhero est pensée 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 pour capturer 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 charge également de se maintenir à jour automatiquement.

Authentification

Vous disposez de deux principales options pour l'authentification :

Mode interactif (connexion via navigateur)

stackhero login

Lorsque vous exécutez cette commande, une URL vous est fournie (et s'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 jamais à saisir votre mot de passe dans la CLI.

Mode non interactif (pour scripts, CI et automatisation)

Pour les workflows automatisés, vous pouvez créer un access token dans votre tableau de bord (Compte > Access tokens) et 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, aucun navigateur n'est donc nécessaire. C'est la méthode recommandée pour les usages non interactifs. Vous pouvez consulter et révoquer vos tokens à 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 une utilisation interactive.
• json : Produit du JSON lisible par une machine, idéal 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 --organization-id=org-xxxxxx --name="My stack")

Vue d'ensemble des commandes

Pour obtenir la liste complète des commandes disponibles, exécutez stackhero --help. Pour des informations détaillées sur une commande spécifique, utilisez stackhero COMMANDE --help.

Voici quelques commandes fréquemment 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"

organizationId="org-xxxxxx"
serviceStoreId="svs-xxxxxx"   # Vous pouvez lister avec : stackhero services-store-list --organization-id=org-xxxxxx
instanceStoreId="ist-xxxxxx"  # Vous pouvez lister avec : stackhero instances-store-list --organization-id=org-xxxxxx --service-store-id=svs-xxxxxx
regionId="europe"             # Vous pouvez lister avec : stackhero regions-list

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

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

# Attendre que le service soit opérationnel
stackhero service-wait-for --service-id="${serviceId}"

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

La documentation de chaque service inclut un guide "Automatiser avec la CLI" prêt à l'emploi, adapté à ce service, pour que vous disposiez de 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 manuellement, vous pouvez exécuter :

stackhero self-update

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