Skip to main content

Windows User Special Guide

This guide provides detailed instructions and notes specifically for Windows users using Lovrabet CLI.

Important Recommendations​

For the best experience, we recommend Windows users use one of the following environments. Support status across different terminals:

  • ✅ WSL (Windows Subsystem for Linux) - Native Linux experience, complete functionality, excellent performance
  • ✅ Cmder - Portable and beautiful, complete functionality, works out of the box
  • ✅ Git Bash - Fully tested and verified, complete functionality, best experience
  • ⚠️ Windows CMD - Basic functions available, but not fully tested
  • ⚠️ PowerShell - Basic functions available, may have some limitations
  • ⚠️ Windows Terminal - Depends on the specific shell type configured

Environment Preparation​

You can choose one of the following three environments:

WSL provides a native Linux environment and is the best choice for development on Windows.

1. Install WSL​

Windows 10 (version 2004+) / Windows 11:

  1. Open PowerShell as administrator
  2. Run the installation command:
wsl --install
  1. Restart your computer
  2. On first launch, you will be asked to create a username and password

Manual Installation (if automatic installation fails):

# Enable WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# After restarting your computer, download and install a Linux distribution
# Visit Microsoft Store, search for "Ubuntu" and install

2. Install Node.js​

Run in WSL:

# Install Node.js 20.x using NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Or use nvm to manage Node.js versions:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload configuration
source ~/.bashrc

# Install Node.js
nvm install --lts
nvm use --lts

3. Verify Environment​

# Check WSL environment
uname -a
# Should output Linux kernel information

# Check Node.js
node --version
# Should output v20.x.x or higher

# Check npm
npm --version
# Should output version number

Option 2: Use Cmder​

Cmder is a portable and beautiful terminal emulator that works out of the box.

1. Download Cmder​

  1. Visit https://cmder.app/
  2. Download the latest version of Cmder (Full version recommended, includes Git for Windows)
  3. Extract to any directory (e.g., C:\Tools\cmder\ or a USB drive)
  4. Run Cmder.exe to start

Features:

  • Fully Portable - Can be placed on USB and carried with you, settings follow you
  • Works Out of the Box - No installation required, extract and run
  • Beautiful - Uses Monokai color scheme, modern appearance
  • Unix Command Support - Built-in Git for Windows, supports common Unix commands
  • Multi-tab - Supports multi-tab management and keyboard shortcuts

2. Install Node.js​

  1. Visit https://nodejs.org/
  2. Download the latest LTS version (version >= 20)
  3. Run the installer
  4. Important: After installation, restart your computer or reopen all terminal windows

3. Verify Environment​

Open Cmder and run the following commands:

# Check Cmder environment
echo $SHELL
# Should output something like /usr/bin/bash or containing bash

# Check Node.js
node --version
# Should output v20.x.x or higher

# Check npm
npm --version
# Should output version number

Option 3: Use Git Bash​

1. Install Git for Windows​

This is a necessary step for using Lovrabet CLI:

  1. Visit https://git-scm.com/download/win
  2. Download the latest version of Git for Windows
  3. Run the installer, default settings are fine
  4. After installation, you have Git Bash

2. Install Node.js​

  1. Visit https://nodejs.org/
  2. Download the latest LTS version (version >= 20)
  3. Run the installer
  4. Important: After installation, restart your computer or reopen all terminal windows

3. Verify Environment​

Open Git Bash and run the following commands:

# Check Git Bash environment
echo $0
# Should output something like "-bash" or containing "bash"

# Check Node.js
node --version
# Should output v20.x.x or higher

# Check npm
npm --version
# Should output version number

Install Lovrabet CLI​

Run in your terminal (WSL / Cmder / Git Bash):

npm install --global @lovrabet/cli

WSL Users​

If you encounter permission issues:

  1. Use sudo (not recommended for global use):
sudo npm install --global @lovrabet/cli
  1. Or modify npm global directory permissions (recommended):
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install --global @lovrabet/cli

Cmder Users​

Cmder usually does not require special permission settings, just run:

If you encounter permission issues:

  1. Run Cmder as administrator:

    • Right-click Cmder.exe
    • Select "Run as administrator"
    • Re-run the installation command

  2. Or modify npm global directory permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install --global @lovrabet/cli

Git Bash Users​

If you encounter permission issues, try running Git Bash as administrator:

  1. Right-click the Git Bash icon
  2. Select "Run as administrator"
  3. Re-run the installation command

Windows 10 Compatibility Optimization v1.3.4+​

Lovrabet CLI has undergone comprehensive compatibility optimization for Windows 10 environments to ensure normal operation across all terminals.

Fixed Issues​

v1.3.4 fixed the following Windows 10 compatibility issues:

1. Path Separator Compatibility​

  • ✅ Uses path.join() instead of hardcoded / separators
  • ✅ Configuration file paths now correctly use \ separators on Windows
  • ✅ Cookie file paths are cross-platform compatible

2. Process Execution Optimization​

  • ✅ Uses execa instead of spawn for better cross-platform support
  • ✅ Automatically handles PATH configuration in Windows environments
  • ✅ Unified process execution method, avoiding shell dependencies

3. Emoji Display Fix​

  • ✅ Removed Windows 10 incompatible emojis (🚀, ❌, 💡, etc.)
  • ✅ Uses ASCII characters instead (*, [ERROR], [OK], etc.)
  • ✅ Ensures correct display in CMD, PowerShell, and Git Bash

Fix Example:

# Before fix (may display as boxes)
🚀 Generating documentation...
❌ Generation failed
💡 Tip: Please login first

# After fix (displays correctly in all terminals)
* Generating documentation...
[ERROR] Generation failed
* Tip: Please login first

Test Verification​

After comprehensive testing, the CLI now works correctly in the following Windows 10 terminals:

  • ✅ Windows CMD - All functions working
  • ✅ PowerShell - All functions working
  • ✅ Git Bash - All functions working (recommended)
  • ✅ WSL - All functions working (recommended)
  • ✅ Cmder - All functions working

Known Limitations​

The following features may have limitations on Windows:

  • OpenAPI Mode Delete Operations: OpenAPI mode does not support delete() operations (cross-platform limitation)
  • Certain Advanced Terminal Features: May lack color display in older versions of CMD

Feedback and Support​

If you encounter any issues on Windows 10:

  1. Prefer using Git Bash or WSL
  2. Check Node.js version (recommended >= 18)
  3. Submit an Issue and include:
    • Windows 10 version
    • Terminal type and version used
    • Error message screenshot

Complete Usage Example​

Here is a complete Windows usage flow (using WSL as example, also applies to Cmder and Git Bash):

# 1. Open terminal (WSL / Cmder / Git Bash)

# 2. Verify environment
node --version
lovrabet --version

# 3. Login authentication
lovrabet auth
# Browser will automatically open, complete login then return to terminal and press q to exit

# 4. Create project
lovrabet create my-project
cd my-project

# 5. Configure application
lovrabet config set app my-app-code

# 6. Generate API
lovrabet api pull

# 7. Start development server
lovrabet start
# Browser will automatically open http://localhost:5173

WSL Specific Tips​

  • Project files are recommended to be stored in the WSL file system (e.g., ~/projects/) for better performance
  • To access Windows files, path is /mnt/c/Users/your-username/
  • Use code . command to open current directory in VS Code (requires VS Code WSL extension)

Cmder Specific Tips​

  • Portability: Can be installed on a USB drive, carry your development environment with you
  • Multi-tab: Use Ctrl + T to quickly create new tab, Ctrl + W to close tab
  • Shortcuts: Ctrl + Alt + U to traverse up directory structure, Ctrl + R for history search
  • Alias Support: Can define common command aliases in config\user-aliases.cmd
  • First Run: Recommended to run Cmder.exe /REGISTER ALL on first use to register right-click menu

Git Bash Specific Tips​

  • Right-click folder and select "Git Bash Here" to quickly open terminal in current directory
  • Windows paths are automatically converted to Unix style (e.g., /c/Users/...)

Getting Help​

If you encounter other issues:

  1. View troubleshooting: Troubleshooting Guide
  2. Try different terminal:
    • If you encounter issues in CMD/PowerShell, try repeating the operation in WSL, Cmder, or Git Bash
    • WSL, Cmder, and Git Bash provide better compatibility and user experience
  3. Collect information: Provide detailed error information and system information to technical support

When providing information, please include:

  • Windows version: Run winver to view
  • Terminal environment: WSL / Cmder / Git Bash / CMD / PowerShell
  • Git version: Run git --version to view
  • Node.js version: Run node --version to view
  • CLI version: Run lovrabet --version to view
  • Complete error message screenshot