Troubleshooting

If moon starts, begin with moon doctor: it checks the installation, the network and your account, and tells you what to fix. Otherwise, find your case below. Each case gives the message you see, its cause and the commands to copy, for Windows (PowerShell and Command Prompt), macOS and Linux.

Moon CLI and its installer display their messages in French. This page quotes them exactly as they appear, followed by their meaning in English.

• moon is not recognized after the installation
• The installer won’t run: execution policy, antivirus, missing curl or irm, proxy
• The checksum or signature doesn’t match
• Sign-in doesn’t work
• Updates and versions
• Uninstall or reinstall cleanly
• WSL, macOS and Linux
• Messages at startup and during a session
• Remote control (moon rc)

Run a diagnostic#Link to the Run a diagnostic section

moon doctor

Each line is marked ✓ (fine), ! (worth checking), ✗ (needs fixing) or · (information), with advice after “→” when you need to act. The last line sums it up: “✓ Tout est en ordre” (everything is fine), “! N points à vérifier” (N things to check) or “✗ N problèmes à corriger” (N problems to fix). The exit code is 1 if a problem still needs fixing.

When you ask for help, attach the JSON version. It doesn’t contain your token:

moon doctor --json > diagnostic.json

“moon” is not recognized after the installation#Link to the “moon” is not recognized after the installation section

The installation ended with “Moon CLI … est installe.” (Moon CLI … is installed), but the terminal answers:

PowerShell : moon : The term 'moon' is not recognized as the name of a cmdlet, function, script file, or operable program.
cmd :        'moon' is not recognized as an internal or external command, operable program or batch file.
bash :       bash: moon: command not found
zsh :        zsh: command not found: moon

The cause is almost always the same: the binary is installed, but the folder that holds it is not in the PATH of the terminal you are using. The terminal was opened before the installation, Windows hasn’t reread the PATH yet, the installer set up a different shell than yours, or adding to the PATH was turned off (MOON_NO_MODIFY_PATH=1, --no-modify-path).

On Windows#Link to the On Windows section

1. Close every terminal window, including all Windows Terminal windows and your editor’s built-in terminal, then open a new one. The installer says so: “Ouvrez un NOUVEAU terminal” (open a NEW terminal).
2. Check that the binary is there, in %LOCALAPPDATA%\Moon (the AppData\Local\Moon folder of your profile):

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

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

If the file is missing (False, “File Not Found”), the installation didn’t finish: run it again (see Reinstall). If it answers “Moon CLI …”, only the PATH is at fault.

3. Check whether the folder is in your account’s PATH:

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

reg query HKCU\Environment /v Path

4. If it’s missing, add it through Windows Settings, which is the most reliable way: press the Windows key, type “environment variables” and open “Edit environment variables for your account”; under “User variables”, select Path, then “Edit…”; click “New”, paste %LOCALAPPDATA%\Moon, then “OK” in both windows. That “OK” notifies Windows: terminals opened afterward see the new PATH.

Or in PowerShell, without touching the other entries (the installer does the same):

$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()

Writing directly to the registry doesn’t notify Windows: afterward, sign out of Windows and back in, or open the environment variables window and click “OK”.

5. In the meantime, for the window that’s already open only:

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

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

Good to know:

• If you installed with MOON_INSTALL_DIR, replace %LOCALAPPDATA%\Moon with that folder.
• Install with your usual account, without “Run as administrator”: Moon CLI doesn’t need administrator rights, and a console opened with another account would install it in that account’s profile.

On macOS and Linux#Link to the On macOS and Linux section

The command is the ~/.local/bin/moon link (or the MOON_INSTALL_DIR folder you chose), which points to ~/.local/share/moon/versions/<version>/moon.

1. Check the link and run it by its path:

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

If the link is missing, reinstall. If it answers “Moon CLI …”, only the PATH is at fault.

2. Check whether the folder is in the PATH:

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

If nothing is printed, it’s missing. The installer adds it to the startup file of the shell given by $SHELL (echo $SHELL), between # >>> moon cli >>> and # <<< moon cli <<<: ~/.zshrc for zsh (the default shell on macOS), ~/.bashrc for bash on Linux, ~/.bash_profile for bash on macOS, ~/.profile for others, ~/.config/fish/conf.d/moon.fish for fish. If your terminal runs a different shell than $SHELL, the block is in the wrong file.

3. Add the folder to your shell’s file, then reload it:

zsh

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

bash (Linux)

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

bash (macOS)

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

fish

fish_add_path ~/.local/bin

4. If moon runs an old version or another program, list everything named moon in the PATH:

which -a moon
hash -r

moon --version must print “Moon CLI …”. Another tool may also be called moon: put ~/.local/bin first in the PATH, or remove the other program.

The installer won’t run#Link to the The installer won’t run section

The installer shows its errors in red, without accents, after “ERREUR :” (error:). Nothing is replaced until it has finished: a version that’s already installed stays in place.

PowerShell execution policy#Link to the PowerShell execution policy section

File C:\...\install.ps1 cannot be loaded because running scripts is disabled on this system.

This message comes from an install.ps1 file that was downloaded and then run with .\install.ps1. The usual installation command doesn’t create a file and isn’t affected:

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

To run the file anyway, lift the restriction for that one command, or for the open window only:

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

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

Don’t change the policy for the whole computer (Set-ExecutionPolicy Unrestricted or -Scope LocalMachine): it isn’t needed. The Command Prompt installer (install.cmd) already does the equivalent of the first line. On a computer managed by your company, if PowerShell stays blocked, ask your IT department to allow the installation.

Antivirus, SmartScreen and Smart App Control#Link to the Antivirus, SmartScreen and Smart App Control section

Since Moon CLI 0.5.3, the Moon CLI binary for Windows is signed in the name of STELLARR STUDIO (timestamped Authenticode signature): see Verify the checksums. The installer downloads and runs it from PowerShell, without going through the browser, so the SmartScreen window “Windows protected your PC” normally doesn’t appear. However, you may see this (error: the binary doesn’t start on this machine):

ERREUR : Le binaire ne demarre pas sur cette machine.

• Smart App Control (Windows 11) may refuse an unknown executable that isn’t signed, such as Moon CLI 0.5.2 and earlier versions. The installer then stops at its startup test, without replacing anything: install the latest version, which is signed. If Windows still refuses a signed version, check that the signer is STELLARR STUDIO, then contact support. Smart App Control can’t allow a single program: don’t turn it off for Moon CLI. In the meantime, use Moon CLI in WSL.
• An antivirus may quarantine moon.exe. Check the alert in “Windows Security” › “Virus & threat protection” › “Protection history”. Before allowing the file, compare its checksum with the published list: see Verify the checksums. If in doubt, don’t allow anything and contact support.
• A binary downloaded by hand from the browser may trigger SmartScreen. Don’t install Moon CLI by hand: the installation command verifies the checksums and tests the binary.

curl or irm not found#Link to the curl or irm not found section

• irm in the Command Prompt: “’irm’ is not recognized…”. irm is a PowerShell command. Open PowerShell, or use the Command Prompt command:

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

• curl -fsSL in Windows PowerShell 5.1: there, curl is an alias for Invoke-WebRequest, which rejects the -fsSL options. In PowerShell, use irm https://realmoon.ai/install.ps1 | iex.
• Windows without curl.exe (Windows 10 versions older than 1803): use the PowerShell command.
• macOS and Linux: “curl: command not found” or “ERREUR : curl est requis.” (error: curl is required). Install curl, then run the installation again:

sudo apt install curl

sudo dnf install curl

apk add curl

sudo pacman -S curl

The installer also needs gzip (“ERREUR : gzip est requis.”, error: gzip is required) and sha256sum or shasum (“ERREUR : sha256sum ou shasum introuvable.”, error: sha256sum or shasum not found): install the gzip package, or coreutils for sha256sum.

Corporate network and proxy#Link to the Corporate network and proxy section

The installer may stop with one of these messages (error: Moon AI unreachable, check your connection and error: download failed, try again in a few minutes):

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

On macOS and Linux, the first message stops at “Moon AI injoignable (https://realmoon.ai/dl).”; only the Windows installer adds “Verifiez votre connexion.” (check your connection).

During the installation

• macOS, Linux, WSL: curl reads the HTTPS_PROXY variable. Set your proxy, then run the installation again in the same terminal:

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

• Windows PowerShell (5.1) uses the system proxy (“Settings” › “Network & internet” › “Proxy”). If the proxy asks for your Windows credentials, pass them before the installation, in the same window:

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

• If your network filters websites, ask for HTTPS access to realmoon.ai (downloads) and chat.realmoon.ai (the service).

Then, for Moon CLI

Moon CLI reads HTTPS_PROXY and NO_PROXY. Keep local addresses out of the proxy: Moon CLI goes through a component that runs on your computer.

macOS, Linux, WSL

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

Windows

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

Then open a new terminal (with bash, write to ~/.bashrc instead of ~/.zshrc).

The checksum or signature doesn’t match#Link to the The checksum or signature doesn’t match section

  ! 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.

In order, these messages say: unexpected checksum, trying again; invalid binary checksum; update failed because of an invalid download checksum, an invalid binary checksum, an invalid manifest signature, a channel serving a manifest older than the last one seen, or a channel serving another channel’s manifest.

What it means: the file you received is not the one Stellarr Studio published. The installer checks the SHA-256 checksum of the download, then of the binary; updates also check a manifest signed with a key built into Moon CLI. At the slightest mismatch, nothing is installed and your current version stays in place. Most often, the download was cut off, or a proxy or antivirus changed the file along the way; more rarely, someone tried to serve you a different binary.

Never force it: don’t download the binary by hand from another address, don’t edit any Moon CLI file, and don’t turn off the checks or your antivirus to push the installation through.

1. Try again a few minutes later: the installer already makes three attempts.
2. Try from another network, without a proxy (your phone’s hotspot, for example).
3. If your company inspects HTTPS traffic, check with its IT department.
4. If the message comes back, contact support with the exact message and moon doctor --json (see Contact support).

An installation older than 0.2.1 may refuse a version signed with a new release key (“signature du manifeste invalide”, invalid manifest signature). Go through 0.2.1 first, which contains the new keys, or run the installer again:

moon update --to 0.2.1
moon update

Sign-in doesn’t work#Link to the Sign-in doesn’t work section

The browser doesn’t open#Link to the The browser doesn’t open section

moon login prints “Ouverture du navigateur pour vous connecter à Moon AI…” (opening the browser to sign you in to Moon AI), then “Si rien ne s’ouvre, ouvrez ce lien :” (if nothing opens, open this link) followed by an address. Open that address in a browser on the same computer: the page sends the sign-in back to Moon CLI through 127.0.0.1, the computer itself. From another device, sign in with a code.

Over SSH, on a server or in a container#Link to the Over SSH, on a server or in a container section

In an SSH session, or on Linux without a graphical display, Moon CLI switches to sign-in with a code on its own. To force it:

moon login --device

The terminal shows “Sur un appareil avec navigateur, ouvrez :” (on a device with a browser, open), an address, then “Et entrez le code :” (and enter the code). Open the address on your phone or another computer, enter the code and authorize the device. The code stays valid for 10 minutes: after “Échec de la connexion par code (expired)” (code sign-in failed, expired), run moon login --device again. Details: Sign in without a browser.

In WSL#Link to the In WSL section

Moon CLI runs xdg-open: depending on the distribution, the Windows browser opens, or nothing happens. If nothing opens, copy the link shown into your Windows browser: WSL 2 usually relays 127.0.0.1 between Windows and Linux. If the page keeps waiting or fails, use moon login --device.

Timeout#Link to the Timeout section

“Échec de la connexion navigateur (timeout).” (browser sign-in failed, timeout): Moon CLI waits 5 minutes at most. The browser page then shows “Moon CLI is no longer responding”. Run moon login again. With Safari, if the terminal doesn’t react, use the link “My terminal is open but nothing happens (Safari). Send the code manually”.

Plan#Link to the Plan section

Moon CLI may refuse to start with one of these messages (Moon CLI requires an Étoile subscription or higher and the workspace … doesn’t have the Étoile plan Moon CLI requires):

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

Moon CLI is included from the Étoile plan up, on the session’s workspace. Since Moon CLI 0.4.1, if only one of your workspaces includes it (your organization’s license, for example), Moon CLI picks it on its own at startup and says so: “Workspace de Moon CLI : …, le seul de vos workspaces qui inclut Moon CLI.” (Moon CLI workspace: …, the only one of your workspaces that includes Moon CLI). If several do, choose one; otherwise, change your plan at chat.realmoon.ai/billing (see pricing).

moon workspace
moon workspace use <name or number>

Other refusals at startup: the workspace’s subscription payment failed, the subscription has ended, or no workspace is linked to the session. See Startup messages.

Expired or revoked token#Link to the Expired or revoked token section

• moon doctor shows “Session expirée” (session expired) or “Session refusée par Moon AI (expirée ou révoquée)” (session rejected by Moon AI, expired or revoked): run moon login.
• When you start moon, a rejected session triggers a new sign-in on its own.
• A session renews itself, but asks for a new browser sign-in 90 days after you signed in: “Votre connexion à Moon CLI date de plus de 90 jours.” (your Moon CLI sign-in is more than 90 days old). See Session length.
• A session revoked from the app (“Settings” › “Account and security”) or with “Sign out everywhere” also needs moon login.

The wrong account#Link to the The wrong account section

moon whoami shows the session’s account and workspace. The authorization page uses the account signed in to your browser: to switch, first sign in to chat.realmoon.ai with the right account, then:

moon logout
moon login

Updates and versions#Link to the Updates and versions section

moon --version
moon update
moon rollback

• moon --version prints “Moon CLI …” on its first line.
• Moon CLI updates itself, at most once a day, during a session; the new version is used the next time you start moon. See Automatic updates.

If a new version gets in your way, go back to the previous one: moon rollback asks “Revenir à la version précédente de Moon CLI ? [o/N]” (go back to the previous version of Moon CLI?), then prints “Moon CLI … est de nouveau la version active (au prochain lancement).” (Moon CLI … is the active version again, from the next start). Any answer other than o (oui, yes) prints “Retour arrière annulé.” (rollback canceled). Without an interactive terminal (script, continuous integration), add --yes: moon rollback --yes. If there is no previous version on the machine, you get “Retour arrière impossible : aucune version précédente sur cette machine.” (rollback impossible: no previous version on this machine); use moon update --to <version> instead.

Uninstall or reinstall cleanly#Link to the Uninstall or reinstall cleanly section

Reinstall: run the installation command again. It replaces the binary and keeps your settings, your sign-in and the session history.

Windows (PowerShell)

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

macOS, Linux, WSL

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

Start from scratch: uninstall and erase everything, then reinstall.

moon uninstall --purge --yes

moon uninstall first revokes your session with Moon AI, then removes the binary, the installed versions and the PATH entry. Without --purge, your settings and the session history are kept. On Windows, open a new terminal afterward.

If moon doesn’t start at all: revoke the session in the app under “Settings” › “Account and security”, then delete the folders by hand: see Uninstall by hand. For where the files are, see Where the files live.

WSL, macOS and Linux#Link to the WSL, macOS and Linux section

Ten platforms are published: Windows x64 (and its build without AVX2) and ARM64, macOS Apple Silicon and Intel, Linux x64 (glibc, musl, without AVX2) and ARM64 (glibc, musl). The installer picks the right one. See Supported platforms.

WSL#Link to the WSL section

• In WSL, install Moon CLI with the Linux command (curl -fsSL https://realmoon.ai/install.sh | sh). It is a separate installation from the Windows one, with its own sign-in.
• In Git Bash or MSYS, the Linux installer stops: “ERREUR : Sous Windows, utilisez PowerShell : irm https://realmoon.ai/install.ps1 | iex” (error: on Windows, use PowerShell).
• Preferably work in a Linux folder (~/projects): Windows folders (/mnt/c/…) are slower to browse from WSL.
• For signing in, see In WSL.

macOS#Link to the macOS section

• When installed with curl … | sh, the binary isn’t flagged as coming from the internet, so Gatekeeper doesn’t stop it. A binary downloaded by hand in the browser, on the other hand, would be blocked. Don’t bypass Gatekeeper: use the installation command.
• “Killed: 9” at startup: macOS refused a binary whose signature no longer matches (a copied or modified file). Reinstall with the installation command.
• On an Intel Mac, the installer uses the Intel build; in a terminal running under Rosetta on an Apple Silicon Mac, it still uses the Apple Silicon build.

Linux#Link to the Linux section

The installer detects glibc or musl on its own, as well as processors without AVX2 (the “baseline” build).

Startup messages#Link to the Startup messages section

Messages during a session#Link to the Messages during a session section

Response cut off#Link to the Response cut off section

A model that reasons a lot can spend the entire length allowed for a response on its reasoning. Since Moon CLI 0.5.5:

• More room: Moon CLI leaves more room for the response of a model that has reasoning levels, reasoning included. This also applies in Auto mode, when the chosen model reasons.
• One retry: when the reasoning takes up all the room before the first word and before any action, Moon CLI sends the same request once more at the model’s lowest reasoning level, without asking you. Moon Blur applies to the retry just as it does to the original request.
• Otherwise, a message: the response ends with “Réponse interrompue : elle a atteint la longueur maximale d’une réponse, réflexion du modèle comprise.” (response cut off: it reached the maximum length of a response, including the model’s reasoning), or “…, même après un nouvel essai avec moins de réflexion.” (even after a retry with less reasoning) when the retry happened, then “Écrivez « continue » pour la suite.” (type continue for the rest). When a lower level exists and hasn’t been tried yet, the message also suggests choosing one (/variants).
• A cut-off action is not run: if the limit hits while the model is writing an action, a half-written file for example, the action is not run and the message names it, with this advice: “Un long contenu s’écrit mieux en plusieurs étapes.” (long content is better written in several steps). “continue” picks up where it left off.

A response can also stop because the model breaks off partway through. Since Moon CLI 0.6.1:

• The text is no longer rewritten: when the connection to the model drops after some text has already been shown, Moon keeps that text instead of starting the response over, and adds “(La connexion au modèle s’est coupée à la fin de cette réponse. Si elle vous semble incomplète, écrivez « continue ».)” (the connection to the model dropped at the end of this response; if it looks incomplete, type continue).
• An empty response is requested again once, without asking you. If it comes back empty again, Moon stops with “Le modèle n’a rien répondu, deux fois de suite (réponse vide de son fournisseur). Rien n’est perdu : réessayez, ou choisissez un autre modèle.” (the model returned nothing twice in a row, an empty response from its provider; nothing is lost, try again or choose another model), instead of looping or ending without a word.
• On Windows, a command that runs past its time limit (a development server started in the foreground, for example) is reported as stopped by the time limit, rather than by an obscure error. Moon is told that it may still be running: a command that doesn’t stop on its own should run in the background (see Background commands).

Remote control (moon rc)#Link to the Remote control (moon rc) section

moon rc [folder] lets you drive a session on this computer from the Code page of Moon AI; the agent and the files stay on the computer. To start a session, resume it and read refusal codes, see Remote control. If it refuses to start:

With /rc in the Moon CLI interface, a refusal from Moon AI or from the launcher shows in the terminal; the messages specific to /rc are in /rc won’t start.

Headless tasks#Link to the Headless tasks section

Slow startup#Link to the Slow startup section

• In your home folder or at the root of a drive, the agent goes through every file: move to a project folder first.
• Heavy instructions files: an AGENTS.md or CLAUDE.md larger than 40 KB is sent with every call. Shorten it: see Instructions files.

Variables left in the environment#Link to the Variables left in the environment section

moon doctor reports the environment variables that change how Moon CLI normally works, such as MOON_BLUR_MODE, and the variables reserved for Moon CLI development. If you didn’t mean to set them, remove them from your shell profile. List of variables: Configuration.

Contact support#Link to the Contact support section

Write to contact@stellarrstudio.com and attach diagnostic.json (the output of moon doctor --json), the exact message shown and your system (Windows, macOS or Linux, with its version). If moon doesn’t start, attach the installer’s output. You can also go through “Help and support” in the app: see Get help.

See also#Link to the See also section

• Install Moon CLI
• Sign in
• Updates and uninstalling
• Command reference
• Configuration