📦 Installation

Time needed: About 5 minutes
Difficulty: Easy - just copy and paste commands

🎯 Before You Start

You need Python installed on your computer. Here's how to check:

python --version

✅ Good: You see something like Python 3.10.0 or higher
❌ Problem: You see "command not found" → Download Python first

📥 Step 1: Install Ranex

Open your Terminal (Mac/Linux) or Command Prompt (Windows) and type:

pip install ranex

💡 Tip: If that doesn't work, try pip3 install ranex or python -m pip install ranex

✅ Step 2: Check It Worked

Type this command:

ranex doctor

What you should see:

✅ Python 3.12.3
✅ Ranex Core: INSTALLED (Rust binary)
✅ MCP Server: /path/to/ranex_mcp
✅ PyYAML: INSTALLED
✅ Integrity Registry: LOADED (42 files tracked)

🎉 All green checkmarks? You're ready! Skip to Quick Start

🔴 Common Problems & Fixes

Problem: "pip: command not found"

What it means: Python isn't installed properly

Fix:

1. Download Python from python.org/downloads
2. During install, check ✅ "Add Python to PATH"
3. Restart your terminal
4. Try again

Problem: "Permission denied"

What it means: You need admin rights

Fix: Add --user to install just for yourself:

pip install --user ranex

Problem: "ranex: command not found" (after install)

What it means: Python scripts folder isn't in your PATH

Fix for Mac/Linux:

export PATH="$HOME/.local/bin:$PATH"

Fix for Windows:

1. Search "Environment Variables" in Start menu
2. Add %APPDATA%\Python\Python3x\Scripts to PATH

Problem: Still stuck?

Run this command - it tells you exactly what's wrong:

ranex doctor

📂 Step 3: Set Up Your Project

Go to your project folder and initialize Ranex:

cd your-project-folder
ranex init

This creates:

🔌 IDE Setup (Optional)

For Cursor / Windsurf Users

Good news! Ranex works automatically. The .windsurfrules file you created tells these IDEs how to behave.

For Other IDEs

You can connect Ranex to any AI assistant that supports MCP:

{
  "mcpServers": {
    "ranex": {
      "command": "ranex_mcp",
      "args": ["--stdio"]
    }
  }
}

🧪 Test Your Setup

Run this to make sure everything works:

ranex doctor
ranex --help

You should see a list of all available commands.

⏭️ What's Next?

You're all set! Now let's build something:

→ Quick Start Guide - Create your first feature with AI governance

📚 Reference

What Got Installed

Useful Commands

ranex --version     # Check version
ranex doctor        # Check system health
ranex --help        # See all commands