Mogick
Docs Home

English

简体中文

English

简体中文

Troubleshoot installation and startup ​

Use this guide when mogick cannot run after installation or the command works but the TUI does not open. If Mogick starts normally and fails only during authentication or a model call, troubleshoot authentication or connectivity instead.

Identify the failing stage ​

Run these commands in order:

bash
mogick version
mogick --help
mogick doctor

Then choose the matching symptom:

SymptomStart here
command not found or “mogick is not recognized as a command”The system cannot find the command
The full path works, but mogick alone does notCheck PATH
Permission deniedCheck execution permissions
Prompt that the binary format or architecture is incompatible[Check platform and architecture](#check platform and architecture)
version and doctor work, but the TUI does not openCheck the terminal environment
Mogick exits immediately for an unclear reasonGenerate diagnostic information

The system cannot find the command ​

Confirm that the executable exists, then run it by its full path.

Linux/WSL ​

If you follow the installation documentation and place the files in ~/bin:

bash
ls -l ~/bin/mogick
~/bin/mogick version
  • If ls reports that the file does not exist, copy or reinstall the executable in the expected directory.
  • If the full path prints a version, the executable works; continue to Check PATH.
  • If the file exists but cannot be executed, continue checking execution permissions and platform architecture.

Windows PowerShell ​

If you place the file in %USERPROFILE%\bin:

powershell
Test-Path "$HOME\bin\mogick.exe"
& "$HOME\bin\mogick.exe" version
  • Test-Path returns False, indicating that the file is not in the expected directory.
  • If the full path prints a version, mogick.exe works; continue to Check PATH.
  • If Windows blocks the file, confirm that it came from the official Mogick release channel. Do not disable security checks for an executable from an unknown source.

Check PATH ​

PATH lists the directories where your shell searches for commands. Add the executable's directory, not the executable file itself.

Linux/WSL ​

bash
command -v mogick
echo "$PATH"

If ~/bin is not in the output, add the following line to the current shell's startup file:

bash
export PATH="$HOME/bin:$PATH"

Bash usually uses ~/.bashrc, and Zsh usually uses ~/.zshrc. After saving, reopen the terminal and run:

bash
command -v mogick
mogick version

command -v mogick should return the full path to the binary.

Windows PowerShell ​

powershell
Get-Command mogick -ErrorAction SilentlyContinue
$env:Path -split ';'

Confirm that the directory containing mogick.exe appears in the list. After changing the user PATH in Windows Environment Variables, close and reopen the terminal so it loads the new value. Then run:

powershell
Get-Command mogick
mogick version

Get-Command should show the intended mogick.exe. If it reports an old directory, adjust PATH precedence or remove the outdated installation.

Check execution permissions ​

For Permission denied on Linux or WSL, inspect and add execute permission:

bash
ls -l ~/bin/mogick
chmod +x ~/bin/mogick
~/bin/mogick version

If the file is on a mount with execution disabled, copy it to a user-owned local directory such as ~/bin. Do not use sudo to hide file-permission problems, because generated configuration and session files may then be owned by the wrong user.

Check platform and architecture ​

Mogick CLI provides the following precompiled installation packages:

PlatformSupported architecture
Linuxx64
Windowsx64

On Linux or WSL, check the platform and architecture with:

bash
uname -s
uname -m

In Windows PowerShell, run:

powershell
[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture

An Exec format error, cannot execute binary file, or similar message usually means the package does not match the platform or CPU architecture. Download the correct official build and run mogick version again.

Windows upgrade or replacement failed ​

Windows locks a running mogick.exe. If an upgrade or reinstall reports that the file is in use:

  1. Exit all running Mogick CLI sessions.
  2. Verify that no other terminals are still running mogick or mogick run.
  3. Retry the upgrade or file replacement.
  4. Open a new terminal and run mogick version to confirm the version.

Configuration and session data are stored in ~/.mogick/, separate from the binaries. Do not delete this directory when replacing the binary.

Check the terminal environment ​

If mogick version, mogick --help, and mogick doctor all work but mogick does not open the TUI, a terminal capability check has probably failed.

TUI requires:

  • Standard input and output connected to an interactive terminal, not pipes or files.
  • A valid TERM value and UTF-8 locale.
  • Adequate terminal window size.
  • A Windows terminal with virtual-terminal control-sequence support.

First inspect the terminal section in the doctor report:

bash
mogick doctor
mogick doctor --check-terminal-font

If borders, CJK character widths, or status symbols render incorrectly, --check-terminal-font interactively checks the terminal grid and font. For scripts, pipelines, or CI, use non-interactive execution instead of the TUI:

bash
mogick run "Explain the current project structure"

Generate diagnostic information ​

If the cause is still unclear, generate a detailed report and log:

bash
mogick doctor --verbose --export ./mogick-doctor-report.md
mogick doctor --verbose --logs-path ./mogick-startup.log

When submitting a question, it is recommended to also provide:

  • Operating system and CPU architecture.
  • Output from mogick version; if it cannot run, provide the executable source and path.
  • The complete error message, not only its final line.
  • Checks in mogick-doctor-report.md with status warn or error.
  • The shortest steps to reproduce the problem stably.

Before sharing reports or logs, redact API keys, tokens, proxy credentials, usernames, and private local paths.

Confirm that the problem has been solved ​

The issue is resolved when all three commands succeed:

bash
mogick version
mogick doctor
mogick

You should see the version, no blocking errors in the runtime and terminal checks, and a working interactive TUI.