Utiliser la CLI

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

Introduction

La CLI Stackhero est un outil léger et autonome en ligne de commande qui vous aide à 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 des configurations et gérer bien d'autres tâches courantes.

La CLI fonctionne sur Linux (glibc et musl), macOS et Windows. Elle est fournie 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 des workflows avec des scripts, des pipelines CI ou des agents IA, la CLI Stackhero est conçue autant pour les utilisateurs que pour l'automatisation. Chaque commande prend en charge l'option --format=json pour une sortie lisible par machine, ainsi que --format=script lorsque 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 bon binaire pour votre plateforme et l'installe sous le nom stackhero. La CLI se maintient aussi automatiquement à jour.

Authentification

Vous avez deux options principales pour l'authentification :

Connexion interactive via le navigateur

stackhero login

Lorsque vous exécutez cette commande, la CLI vous fournit une URL et l'ouvre aussi automatiquement dans votre navigateur. Vous pouvez ensuite 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 les scripts, la CI et l'automatisation

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

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

Lorsque STACKHERO_TOKEN est défini, il est prioritaire sur les sessions interactives, donc l'utilisation d'un navigateur devient optionnelle. Cette approche convient très bien aux usages non interactifs. Vous pouvez consulter et révoquer les tokens depuis votre tableau de bord à tout moment.

Formats de sortie

Chaque commande CLI accepte une option globale --format :

• human (par défaut) : affiche des tableaux et du texte lisibles pour un usage interactif.
• json : renvoie du JSON lisible par machine, utile pour les scripts et les agents IA.
• script : renvoie uniquement la ou les valeurs brutes, ce qui facilite l'assignation de la sortie à des variables shell.

Par exemple :

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

Vue d'ensemble des commandes

Si vous souhaitez voir la liste complète des commandes disponibles, vous pouvez exécuter stackhero --help. Si vous souhaitez obtenir des détails sur une commande précise, vous pouvez essayer 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 une 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"   # Un nom de service store. Voir : `stackhero services-store-list`
instance="1GB"            # Un nom d'instance (taille). Voir : `stackhero instances-store-list --service-store=directus`
region="europe"           # Un nom de région. Voir : `stackhero regions-list`

# Créer une stack (utilise votre seule organization, 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 de 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 cours d'exécution
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 d'un service inclut un guide Automate with the CLI prêt à l'emploi, adapté à ce service, afin que vous ayez tout ce qu'il vous faut pour démarrer.

Mise à jour et désinstallation

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

stackhero self-update

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