Installation

Ralph can be installed using the automated install script or manually from source. This guide covers both methods and helps you verify your installation.

Prerequisites

Before installing Ralph, ensure you have:

Required

Optional (for building from source)

  • Bun or Node.js 18+ — Only needed if building from source

The fastest way to install Ralph is using the automated install script:

curl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | bash

What the Script Does

  1. Detects your operating system and CPU architecture
  2. Downloads the latest release binary for your platform
  3. Installs it to ~/.local/bin (or /usr/local/bin if you have permissions)
  4. Adds the installation directory to your PATH if needed
  5. Verifies the installation

Supported Platforms

  • macOS (Intel and Apple Silicon)
  • Linux (x64 and ARM64)
  • Windows via WSL

Manual Installation

Option 1: Download Binary

Download the appropriate binary for your platform from the releases page:

# macOS (Apple Silicon)
curl -L https://github.com/nitodeco/ralph/releases/latest/download/ralph-macos-arm64 -o ralph

# macOS (Intel)
curl -L https://github.com/nitodeco/ralph/releases/latest/download/ralph-macos-x64 -o ralph

# Linux (x64)
curl -L https://github.com/nitodeco/ralph/releases/latest/download/ralph-linux-x64 -o ralph

# Make it executable
chmod +x ralph

# Move to a directory in your PATH
mv ralph ~/.local/bin/ralph

Option 2: Build from Source

Clone the repository and build:

git clone https://github.com/nitodeco/ralph.git
cd ralph
bun install
bun run build

The build creates platform-specific binaries in the dist/ directory.

Link it globally:

bun link

Or manually copy the binary:

cp dist/ralph-* ~/.local/bin/ralph

Verify Installation

After installation, verify Ralph is working correctly:

ralph --version

Expected output:

ralph version 0.14.5

Verify AI Agent

Ensure your chosen AI agent is installed and accessible:

# For Cursor CLI
which cursor

# For Claude Code
which claude

# For Codex
which codex

Each command should return a path. If not, install the appropriate agent:

Verify Git

git --version

Should output Git version 2.x or higher.

Troubleshooting Installation

”ralph: command not found”

The installation directory isn’t in your PATH. Add it manually:

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

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

“Permission denied” When Running Install Script

The script needs write access to the installation directory. Either:

  1. Run with sudo (installs to /usr/local/bin):

    curl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | sudo bash

  2. Or ensure ~/.local/bin exists and is writable:

    mkdir -p ~/.local/bin

Build Fails with “bun: command not found”

Install Bun first:

curl -fsSL https://bun.sh/install | bash

Or use npm/yarn if you have Node.js:

npm install
npm run build

Updating Ralph

To update to the latest version:

ralph update

This checks for updates and installs the newest release automatically.

Or manually re-run the install script:

curl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | bash

Uninstalling Ralph

Remove the Ralph binary:

rm ~/.local/bin/ralph
# or
rm /usr/local/bin/ralph

Optionally remove Ralph’s data directory:

rm -rf ~/.ralph

This deletes all projects, configurations, and session data.

Next Steps