Gestion des ressources Medusa Cloud

Guide opérationnel pour les agents IA gérant l'infrastructure Medusa Cloud via la CLI mcloud. Couvre l'installation, les déploiements, le débogage, les environnements et les variables.

Contraintes

Toujours passer --json lors de l'analyse de la sortie CLI. La sortie en texte brut est destinée aux humains et peut changer sans avertissement.
Confirmer le contexte avant toute mutation. Exécuter mcloud whoami --json avant tout changement d'état.
Lire avant d'écrire. Exécuter une commande get ou list avant toute delete, redeploy ou trigger-build.
Utiliser --yes pour les opérations destructrices. Les commandes delete nécessitent --yes en mode non-interactif.
Les environnements de production ne peuvent pas être supprimés. mcloud environments delete génère une erreur sur la production par conception.
Ne jamais passer --reveal sauf si l'utilisateur le demande explicitement. Les valeurs secrètes apparaissent dans l'historique du terminal et les logs.
--json et --follow sont incompatibles. Utiliser des fenêtres de temps limitées (--from/--to) avec --json pour l'ingestion programmatique de logs.

CRITIQUE : Charger les fichiers de référence si nécessaire

Charger ces références selon ce que vous faites :

Configuration de la CLI ? → DOIT charger setup.md en premier
Débogage d'un déploiement échoué ? → DOIT charger debugging-deployments.md en premier
Gestion des environnements ou variables ? → DOIT charger environments-and-variables.md en premier

Exigence minimale : Charger au moins un fichier de référence avant d'exécuter des workflows multi-étapes.

Référence rapide

Vérification d'authentification

Toujours vérifier l'auth et le scope avant de muter l'état :

mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'

Code de sortie 0 = authentifié et scopé. Non-zéro = arrêter et demander à l'utilisateur.

Définir le contexte une fois

mcloud use \
  --organization org_123 \
  --project proj_123 \
  --environment production

CRITIQUE : mcloud use sans flags est interactif et échoue en CI/Docker/entrée pipée. Toujours passer les flags.

Routage du statut de déploiement

Router sur backend_status (ou storefront_status) :

Statut	Sens	Logs à vérifier
`build-failed`	Étape de build échouée	`mcloud deployments build-logs <id>`
`deployment-failed`	Runtime crashed après build	`mcloud logs --deployment <id>`
`timed-out`	Dépassement du budget de temps	Les deux : build-logs d'abord, puis logs runtime

Décision de redéploiement

Commande	Quand l'utiliser
`mcloud environments redeploy <env>`	Le fix est côté environnement (changement de variable, infra) — réexécute le build existant
`mcloud environments trigger-build <env>`	Le fix est dans le code source sur la branche tracée — démarre un nouveau build

Pièges courants

Commandes TTY uniquement. mcloud login, mcloud use (sans flags) et delete sans --yes nécessitent un TTY. Ils échouent en CI, Docker ou entrée pipée.
Précédence de MCLOUD_TOKEN. Quand défini, les credentials basées sur des fichiers sont ignorées et mcloud login est rejeté. Le décommenter pour changer de compte.
Clés d'accès personnelles vs org. Les clés personnelles nécessitent --organization ; les clés org sont pré-scopées.
organizations list nécessite l'auth personnelle. Les clés d'accès org retournent 401 sur cette commande.
IDs de build vs IDs de déploiement. depl_* = ID de déploiement ; tout le reste = ID de build (résolu au dernier déploiement). mcloud logs --deployment accepte les deux ; les autres commandes prennent uniquement les IDs de build.

Fichiers de référence

setup.md                       - Installation CLI, authentification, configuration du contexte
debugging-deployments.md       - Recettes d'échecs de build/déploiement et analyse de logs
environments-and-variables.md  - Cycle de vie des environnements et gestion des variables

using-medusa-cloud