Dépannage

Si moon démarre, commencez par moon doctor : il vérifie l’installation, le réseau et votre compte, et dit quoi corriger. Sinon, cherchez votre cas ci-dessous : chaque cas donne le message affiché, sa cause et les commandes à copier, pour Windows (PowerShell et invite de commandes), macOS et Linux.

• « moon » n’est pas reconnu après l’installation
• L’installeur ne s’exécute pas : politique d’exécution, antivirus, curl ou irm absent, proxy
• L’empreinte ou la signature ne correspond pas
• La connexion ne marche pas
• Mises à jour et version
• Désinstaller ou réinstaller proprement
• WSL, macOS et Linux
• Messages au lancement et pendant une session
• Contrôle à distance (moon rc)

Lancer un diagnostic#Lien vers la section Lancer un diagnostic

moon doctor

Chaque ligne est marquée ✓ (en ordre), ! (à vérifier), ✗ (à corriger) ou · (information), avec un conseil après « → » quand il faut agir. La dernière ligne résume : « ✓ Tout est en ordre », « ! N points à vérifier » ou « ✗ N problèmes à corriger ». Le code de sortie vaut 1 s’il reste un problème à corriger.

Pour une demande d’aide, joignez la version JSON. Elle ne contient pas votre jeton :

moon doctor --json > diagnostic.json

« moon » n’est pas reconnu après l’installation#Lien vers la section « moon » n’est pas reconnu après l’installation

L’installation s’est terminée par « Moon CLI … est installe. », mais le terminal répond :

PowerShell : moon : Le terme «moon» n'est pas reconnu comme nom d'applet de commande, fonction, fichier de script ou programme exécutable.
cmd :        'moon' n'est pas reconnu en tant que commande interne ou externe, un programme exécutable ou un fichier de commandes.
bash :       bash: moon: command not found
zsh :        zsh: command not found: moon

La cause est presque toujours la même : le binaire est bien installé, mais le dossier qui le contient n’est pas dans le PATH du terminal que vous utilisez. Le terminal a été ouvert avant l’installation, Windows n’a pas encore relu le PATH, l’installeur a configuré un autre shell que le vôtre, ou l’ajout au PATH a été désactivé (MOON_NO_MODIFY_PATH=1, --no-modify-path).

Sous Windows#Lien vers la section Sous Windows

1. Fermez toutes les fenêtres de terminal, y compris toutes les fenêtres de Windows Terminal et le terminal intégré de votre éditeur, puis ouvrez-en une nouvelle. L’installeur l’annonce : « Ouvrez un NOUVEAU terminal ».
2. Vérifiez que le binaire est bien là, dans %LOCALAPPDATA%\Moon (le dossier AppData\Local\Moon de votre profil) :

Test-Path "$env:LOCALAPPDATA\Moon\moon.exe"
& "$env:LOCALAPPDATA\Moon\moon.exe" --version

dir "%LOCALAPPDATA%\Moon\moon.exe"
"%LOCALAPPDATA%\Moon\moon.exe" --version

Si le fichier est absent (False, « Fichier introuvable »), l’installation n’est pas allée au bout : relancez-la (voir Réinstaller). S’il répond « Moon CLI … », seul le PATH est en cause.

3. Regardez si le dossier est dans le PATH de votre compte :

[Environment]::GetEnvironmentVariable('Path', 'User') -split ';'

reg query HKCU\Environment /v Path

4. S’il manque, ajoutez-le par les Paramètres, c’est le plus sûr : touche Windows, tapez « variables d’environnement » et ouvrez « Modifier les variables d’environnement pour votre compte » ; dans « Variables utilisateur », sélectionnez Path, puis « Modifier… » ; cliquez sur « Nouveau », collez %LOCALAPPDATA%\Moon, puis « OK » dans les deux fenêtres. Ce « OK » prévient Windows : les terminaux ouverts ensuite voient le nouveau PATH.

Ou dans PowerShell, sans toucher aux autres entrées (l’installeur fait de même) :

$dir = "$env:LOCALAPPDATA\Moon"
$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
$path = [string]$key.GetValue('Path', '', 'DoNotExpandEnvironmentNames')
if (($path -split ';') -notcontains $dir) { $key.SetValue('Path', "$(if ($path) { $path.TrimEnd(';') + ';' })$dir", 'ExpandString') }
$key.Close()

Cette écriture directe dans le registre ne prévient pas Windows : ensuite, fermez votre session Windows et rouvrez-la, ou ouvrez la fenêtre des variables d’environnement et cliquez sur « OK ».

5. En attendant, pour la fenêtre déjà ouverte seulement :

$env:Path += ";$env:LOCALAPPDATA\Moon"
moon --version

set "PATH=%PATH%;%LOCALAPPDATA%\Moon"
moon --version

À savoir :

• Si vous avez installé avec MOON_INSTALL_DIR, remplacez %LOCALAPPDATA%\Moon par ce dossier.
• Installez avec votre compte habituel, sans « Exécuter en tant qu’administrateur » : Moon CLI n’a pas besoin de droits d’administrateur, et une console ouverte avec un autre compte l’installerait dans le profil de ce compte.

Sous macOS et Linux#Lien vers la section Sous macOS et Linux

La commande est le lien ~/.local/bin/moon (ou le dossier MOON_INSTALL_DIR choisi), qui pointe vers ~/.local/share/moon/versions/<version>/moon.

1. Vérifiez le lien et lancez-le par son chemin :

ls -l ~/.local/bin/moon
~/.local/bin/moon --version

Si le lien est absent, réinstallez. S’il répond « Moon CLI … », seul le PATH est en cause.

2. Regardez si le dossier est dans le PATH :

echo "$PATH" | tr ':' '\n' | grep -x "$HOME/.local/bin"

Rien ne s’affiche : il manque. L’installeur l’ajoute dans le fichier de démarrage du shell indiqué par $SHELL (echo $SHELL), entre # >>> moon cli >>> et # <<< moon cli <<< : ~/.zshrc pour zsh (le shell par défaut de macOS), ~/.bashrc pour bash sous Linux, ~/.bash_profile pour bash sous macOS, ~/.profile pour les autres, ~/.config/fish/conf.d/moon.fish pour fish. Si votre terminal lance un autre shell que $SHELL, le bloc est dans le mauvais fichier.

3. Ajoutez le dossier dans le fichier de votre shell, puis relisez-le :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

fish_add_path ~/.local/bin

4. Si moon lance une ancienne version ou un autre programme, listez tout ce qui s’appelle moon dans le PATH :

which -a moon
hash -r

moon --version doit afficher « Moon CLI … ». Un autre outil peut aussi s’appeler moon : placez ~/.local/bin en tête du PATH, ou retirez l’autre programme.

L’installeur ne s’exécute pas#Lien vers la section L’installeur ne s’exécute pas

L’installeur affiche ses erreurs en rouge, sans accents, après « ERREUR : ». Rien n’est remplacé tant qu’il n’est pas allé au bout : une version déjà installée reste en place.

Politique d’exécution de PowerShell#Lien vers la section Politique d’exécution de PowerShell

Impossible de charger le fichier C:\...\install.ps1, car l'exécution de scripts est désactivée sur ce système.

Ce message vient d’un fichier install.ps1 téléchargé puis lancé par .\install.ps1. La commande d’installation habituelle ne crée pas de fichier et n’est pas concernée :

irm https://realmoon.ai/install.ps1 | iex

Pour lancer le fichier quand même, levez la restriction pour cette seule commande, ou pour la seule fenêtre ouverte :

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

Ne changez pas la politique de tout l’ordinateur (Set-ExecutionPolicy Unrestricted ou -Scope LocalMachine) : ce n’est pas nécessaire. L’installeur de l’invite de commandes (install.cmd) fait déjà l’équivalent de la première ligne. Sur un ordinateur géré par votre entreprise, si PowerShell reste bloqué, demandez à votre service informatique d’autoriser l’installation.

Antivirus, SmartScreen et Smart App Control#Lien vers la section Antivirus, SmartScreen et Smart App Control

Le binaire de Moon CLI pour Windows n’a pas encore de signature Authenticode. L’installeur le télécharge et le lance depuis PowerShell, sans passer par le navigateur : la fenêtre SmartScreen « Windows a protégé votre ordinateur » ne s’affiche normalement pas. En revanche :

ERREUR : Le binaire ne demarre pas sur cette machine.

• Smart App Control (Windows 11) peut refuser un exécutable non signé. L’installeur s’arrête alors à son test de démarrage, sans rien remplacer. Smart App Control ne permet pas d’autoriser un seul programme : ne le désactivez pas pour Moon CLI. Utilisez Moon CLI dans WSL, ou écrivez au support.
• Un antivirus peut mettre moon.exe en quarantaine. Dans « Sécurité Windows » › « Protection contre les virus et menaces » › « Historique de protection », vérifiez l’alerte. Avant d’autoriser le fichier, comparez son empreinte avec la liste publiée : voir Vérifier les empreintes. En cas de doute, n’autorisez rien et écrivez au support.
• Un binaire téléchargé à la main depuis le navigateur peut déclencher SmartScreen. N’installez pas Moon CLI à la main : la commande d’installation vérifie les empreintes et teste le binaire.

curl ou irm introuvable#Lien vers la section curl ou irm introuvable

• irm dans l’invite de commandes : « ’irm’ n’est pas reconnu… ». irm est une commande de PowerShell. Ouvrez PowerShell, ou utilisez la commande de l’invite de commandes :

curl -fsSL https://realmoon.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

• curl -fsSL dans Windows PowerShell 5.1 : curl y est un autre nom d’Invoke-WebRequest, qui refuse les options -fsSL. Dans PowerShell, utilisez irm https://realmoon.ai/install.ps1 | iex.
• Windows sans curl.exe (versions de Windows 10 antérieures à 1803) : utilisez la commande PowerShell.
• macOS et Linux : « curl: command not found » ou « ERREUR : curl est requis. ». Installez curl, puis relancez l’installation :

sudo apt install curl

sudo dnf install curl

apk add curl

sudo pacman -S curl

L’installeur demande aussi gzip (« ERREUR : gzip est requis. ») et sha256sum ou shasum (« ERREUR : sha256sum ou shasum introuvable. ») : installez le paquet gzip, ou coreutils pour sha256sum.

Réseau d’entreprise et proxy#Lien vers la section Réseau d’entreprise et proxy

ERREUR : Moon AI injoignable (https://realmoon.ai/dl). Verifiez votre connexion.
ERREUR : Telechargement impossible. Reessayez dans quelques minutes.

Sous macOS et Linux, le premier message s’arrête à « Moon AI injoignable (https://realmoon.ai/dl). » ; « Verifiez votre connexion. » n’est écrit que par l’installeur de Windows.

Pendant l’installation

• macOS, Linux, WSL : curl lit la variable HTTPS_PROXY. Indiquez votre proxy, puis relancez l’installation dans le même terminal :

export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://realmoon.ai/install.sh | sh

• Windows PowerShell (5.1) utilise le proxy du système (« Paramètres » › « Réseau et Internet » › « Proxy »). Si le proxy demande votre identifiant Windows, transmettez-le avant l’installation, dans la même fenêtre :

[System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials
irm https://realmoon.ai/install.ps1 | iex

• Si votre réseau filtre les sites, demandez l’accès en HTTPS à realmoon.ai (téléchargements) et à chat.realmoon.ai (le service).

Ensuite, pour Moon CLI

Moon CLI lit HTTPS_PROXY et NO_PROXY. Gardez les adresses locales hors du proxy : Moon CLI passe par un composant qui tourne sur votre ordinateur.

echo 'export HTTPS_PROXY=http://proxy.example.com:8080' >> ~/.zshrc
echo 'export NO_PROXY=127.0.0.1,localhost' >> ~/.zshrc

[Environment]::SetEnvironmentVariable('HTTPS_PROXY', 'http://proxy.example.com:8080', 'User')
[Environment]::SetEnvironmentVariable('NO_PROXY', '127.0.0.1,localhost', 'User')

Ouvrez ensuite un nouveau terminal (avec bash, écrivez dans ~/.bashrc au lieu de ~/.zshrc).

L’empreinte ou la signature ne correspond pas#Lien vers la section L’empreinte ou la signature ne correspond pas

  ! empreinte inattendue, nouvelle tentative
ERREUR : Empreinte du binaire invalide.
Mise à jour impossible : empreinte du téléchargement invalide.
Mise à jour impossible : empreinte du binaire invalide.
Mise à jour impossible : signature du manifeste invalide : mise à jour refusée.
Mise à jour impossible : le canal de mise à jour sert un manifeste plus ancien que le dernier vu : mise à jour refusée.
Mise à jour impossible : le canal de mise à jour « … » sert le manifeste du canal « … » : mise à jour refusée.

Ce que cela veut dire : le fichier reçu n’est pas celui que Stellarr Studio a publié. L’installeur vérifie l’empreinte SHA-256 du téléchargement puis du binaire ; les mises à jour vérifient en plus un manifeste signé avec une clé intégrée à Moon CLI. Au moindre écart, rien n’est installé et votre version actuelle reste en place. Le plus souvent, le téléchargement a été coupé, ou un proxy ou un antivirus a modifié le fichier en route ; plus rarement, quelqu’un a tenté de vous servir un autre binaire.

Ne forcez jamais : ne téléchargez pas le binaire à la main depuis une autre adresse, ne modifiez aucun fichier de Moon CLI, ne coupez pas les vérifications ni votre antivirus pour faire passer l’installation.

1. Réessayez quelques minutes plus tard : l’installeur fait déjà trois essais.
2. Essayez depuis un autre réseau, sans proxy (partage de connexion du téléphone, par exemple).
3. Si votre entreprise inspecte le HTTPS, voyez avec son service informatique.
4. Si le message revient, écrivez au support avec le message exact et moon doctor --json (voir Contacter le support).

Une installation antérieure à la 0.2.1 peut refuser une version signée par une nouvelle clé de publication (« signature du manifeste invalide »). Passez d’abord par la 0.2.1, qui contient les nouvelles clés, ou relancez l’installeur :

moon update --to 0.2.1
moon update

La connexion ne marche pas#Lien vers la section La connexion ne marche pas

Le navigateur ne s’ouvre pas#Lien vers la section Le navigateur ne s’ouvre pas

moon login écrit « Ouverture du navigateur pour vous connecter à Moon AI… », puis « Si rien ne s’ouvre, ouvrez ce lien : » suivi d’une adresse. Ouvrez cette adresse dans un navigateur du même ordinateur : la page renvoie la connexion à Moon CLI par 127.0.0.1, l’ordinateur lui-même. Depuis un autre appareil, utilisez la connexion par code.

En SSH, sur un serveur ou dans un conteneur#Lien vers la section En SSH, sur un serveur ou dans un conteneur

Dans une session SSH, ou sous Linux sans affichage graphique, Moon CLI passe de lui-même à la connexion par code. Pour la forcer :

moon login --device

Le terminal affiche « Sur un appareil avec navigateur, ouvrez : », une adresse, puis « Et entrez le code : ». Ouvrez l’adresse sur votre téléphone ou un autre ordinateur, saisissez le code et autorisez l’appareil. Le code reste valable 10 minutes : après « Échec de la connexion par code (expired) », relancez moon login --device. Détails : Se connecter sans navigateur.

Dans WSL#Lien vers la section Dans WSL

Moon CLI lance xdg-open : selon la distribution, le navigateur de Windows s’ouvre, ou rien ne se passe. Si rien ne s’ouvre, copiez le lien affiché dans votre navigateur Windows : WSL 2 relaie en général 127.0.0.1 entre Windows et Linux. Si la page reste en attente ou échoue, utilisez moon login --device.

Délai dépassé#Lien vers la section Délai dépassé

« Échec de la connexion navigateur (timeout). » : Moon CLI attend 5 minutes au plus. La page du navigateur affiche alors « Moon CLI ne répond plus ». Relancez moon login. Avec Safari, si le terminal ne réagit pas, utilisez le lien « Mon terminal est ouvert mais rien ne se passe (Safari). Transmettre le code manuellement ».

Forfait#Lien vers la section Forfait

! Moon CLI requiert un abonnement Étoile ou supérieur.
! Le workspace « … » (…) n’a pas le forfait Étoile requis pour Moon CLI.

Moon CLI est inclus à partir du forfait Étoile, sur le workspace de la session. Si un autre de vos workspaces l’inclut, choisissez-le ; sinon, changez de forfait sur chat.realmoon.ai/billing (voir les tarifs).

moon workspace
moon workspace use <nom ou numéro>

Autres refus au lancement : le paiement de l’abonnement du workspace a échoué, l’abonnement est terminé, ou aucun workspace n’est associé à la session. Voir Messages au lancement.

Jeton expiré ou révoqué#Lien vers la section Jeton expiré ou révoqué

• moon doctor affiche « Session expirée » ou « Session refusée par Moon AI (expirée ou révoquée) » : lancez moon login.
• Au lancement de moon, une session refusée déclenche une nouvelle connexion d’elle-même.
• Une session se renouvelle seule, mais demande une nouvelle connexion par le navigateur 90 jours après la connexion : « Votre connexion à Moon CLI date de plus de 90 jours. ». Voir Durée de la session.
• Une session révoquée depuis l’application (« Réglages » › « Sécurité ») ou par « déconnecter partout » demande aussi moon login.

Le mauvais compte#Lien vers la section Le mauvais compte

moon whoami montre le compte et le workspace de la session. La page d’autorisation utilise le compte connecté dans votre navigateur : pour changer, connectez-vous d’abord à chat.realmoon.ai avec le bon compte, puis :

moon logout
moon login

Mises à jour et version#Lien vers la section Mises à jour et version

moon --version
moon update
moon rollback

• moon --version affiche « Moon CLI … » en première ligne.
• Moon CLI se met à jour seul, au plus une fois par jour, pendant une session ; la nouvelle version sert au lancement suivant de moon. Voir Mises à jour automatiques.

Si une nouvelle version vous gêne, revenez à la précédente : moon rollback demande « Revenir à la version précédente de Moon CLI ? [o/N] », puis affiche « Moon CLI … est de nouveau la version active (au prochain lancement). ». Une autre réponse que « o » affiche « Retour arrière annulé. ». Sans terminal interactif (script, intégration continue), ajoutez --yes : moon rollback --yes. Sans version précédente sur la machine : « Retour arrière impossible : aucune version précédente sur cette machine. », utilisez alors moon update --to <version>.

Désinstaller ou réinstaller proprement#Lien vers la section Désinstaller ou réinstaller proprement

Réinstaller : relancez la commande d’installation. Elle remplace le binaire et garde vos réglages, votre connexion et l’historique des sessions.

irm https://realmoon.ai/install.ps1 | iex

curl -fsSL https://realmoon.ai/install.sh | sh

Repartir de zéro : désinstallez en effaçant tout, puis réinstallez.

moon uninstall --purge --yes

moon uninstall révoque d’abord votre session auprès de Moon AI, puis retire le binaire, les versions installées et l’ajout au PATH. Sans --purge, vos réglages et l’historique des sessions sont gardés. Sous Windows, ouvrez ensuite un nouveau terminal.

Si moon ne démarre plus du tout : révoquez la session dans « Réglages » › « Sécurité » de l’application, puis supprimez les dossiers à la main : voir Désinstaller à la main. Où sont les fichiers : voir Emplacements des fichiers.

WSL, macOS et Linux#Lien vers la section WSL, macOS et Linux

Dix plateformes sont publiées : Windows x64 (et sa variante sans AVX2) et ARM64, macOS Apple Silicon et Intel, Linux x64 (glibc, musl, sans AVX2) et ARM64 (glibc, musl). L’installeur choisit la bonne. Voir Plateformes servies.

WSL#Lien vers la section WSL

• Dans WSL, installez Moon CLI avec la commande de Linux (curl -fsSL https://realmoon.ai/install.sh | sh). C’est une installation à part de celle de Windows, avec sa propre connexion.
• Dans Git Bash ou MSYS, l’installeur de Linux s’arrête : « ERREUR : Sous Windows, utilisez PowerShell : irm https://realmoon.ai/install.ps1 | iex ».
• Travaillez de préférence dans un dossier de Linux (~/projets) : les dossiers de Windows (/mnt/c/…) sont plus lents à parcourir depuis WSL.
• Pour la connexion, voir Dans WSL.

macOS#Lien vers la section macOS

• Installé par curl … | sh, le binaire n’est pas marqué comme venant d’Internet : Gatekeeper ne l’arrête pas. Un binaire téléchargé à la main par le navigateur, lui, serait bloqué. Ne contournez pas Gatekeeper : utilisez la commande d’installation.
• « Killed: 9 » au lancement : macOS a refusé un binaire dont la signature ne correspond plus (fichier copié ou modifié). Réinstallez avec la commande d’installation.
• Sur un Mac Intel, l’installeur prend la version Intel ; dans un terminal lancé sous Rosetta sur un Mac Apple Silicon, il prend quand même la version Apple Silicon.

Linux#Lien vers la section Linux

L’installeur détecte seul glibc ou musl, et les processeurs sans AVX2 (variante « baseline »).

Messages au lancement#Lien vers la section Messages au lancement

Messages pendant une session#Lien vers la section Messages pendant une session

Contrôle à distance (moon rc)#Lien vers la section Contrôle à distance (moon rc)

moon rc [dossier] rend une session de cet ordinateur pilotable depuis la page Code de Moon AI ; l’agent et les fichiers restent sur l’ordinateur. Lancer une session, la reprendre, codes de refus : voir Contrôle à distance. S’il refuse de démarrer :

Avec /rc dans l’interface de Moon CLI, un refus de Moon AI ou du lanceur s’affiche dans le terminal ; les messages propres à /rc sont dans /rc ne démarre pas.

Tâches sans interface#Lien vers la section Tâches sans interface

Démarrage lent#Lien vers la section Démarrage lent

• Dans votre dossier personnel ou à la racine d’un disque, l’agent parcourt tous les fichiers : placez-vous dans le dossier d’un projet.
• Fichiers d’instructions lourds : un AGENTS.md ou CLAUDE.md de plus de 40 Ko est envoyé à chaque appel. Raccourcissez-le : voir Fichiers d’instructions.

Variables restées dans l’environnement#Lien vers la section Variables restées dans l’environnement

moon doctor signale les variables d’environnement qui changent le fonctionnement normal de Moon CLI, comme MOON_BLUR_MODE, et les variables réservées au développement de Moon CLI. Si vous ne les avez pas voulues, retirez-les de votre profil de shell. Liste des variables : Configuration.

Contacter le support#Lien vers la section Contacter le support

Écrivez à contact@stellarrstudio.com en joignant diagnostic.json (sortie de moon doctor --json), le message exact affiché et votre système (Windows, macOS ou Linux, avec la version). Si moon ne démarre pas, joignez la sortie de l’installeur. Vous pouvez aussi passer par « Aide et support » dans l’application : voir Obtenir de l’aide.

Voir aussi#Lien vers la section Voir aussi

• Installer Moon CLI
• Se connecter
• Mises à jour et désinstallation
• Référence des commandes
• Configuration