Installation

This guide covers all installation methods for Ralph Orchestrator.

Prerequisites

AI CLI Tools

Ralph needs at least one AI CLI tool to function. Install one of the following:

=== "Claude Code (Recommended)"

```bash
# Via npm
npm install -g @anthropic-ai/claude-code

# Or visit https://claude.ai/code for setup instructions
```

=== "Kiro"

```bash
# Visit https://kiro.dev/ for installation
```

=== "Gemini CLI"

```bash
npm install -g @google/gemini-cli
```

=== "Codex"

```bash
# Visit https://github.com/openai/codex
```

=== "Amp"

```bash
# Visit https://github.com/sourcegraph/amp
```

=== "Copilot CLI"

```bash
npm install -g @github/copilot
```

=== "OpenCode"

```bash
curl -fsSL https://opencode.ai/install | bash
```

Installing Ralph

Via npm (Recommended)

The easiest way to install Ralph:

# Install globally
npm install -g @ralph-orchestrator/ralph-cli

# Or run directly with npx
npx @ralph-orchestrator/ralph-cli --version

Via GitHub Releases installer

curl --proto '=https' --tlsv1.2 -LsSf \\
  https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh

Via Cargo

If you have Rust installed:

cargo install ralph-cli

From Source

For the latest development version:

# Clone the repository
git clone https://github.com/mikeyobrien/ralph-orchestrator.git
cd ralph-orchestrator

# Build release binary
cargo build --release

# Add to PATH

# Or create symlink
sudo ln -s $(pwd)/target/release/ralph /usr/local/bin/ralph

Verify Installation

# Check version
ralph --version

# Show help
ralph --help

# List available presets
ralph init --list-presets

Migrating from v1 (Legacy)

If you have the legacy Ralph v1 installed, uninstall it first:

# If installed via pip
pip uninstall ralph-orchestrator

# If installed via pipx
pipx uninstall ralph-orchestrator

# If installed via uv
uv tool uninstall ralph-orchestrator

# Verify removal
which ralph  # Should return nothing or point to new Rust version

The v1 release is no longer maintained. See Migration from v1 for details.

Troubleshooting

Command Not Found

If ralph is not found after installation:

# For npm global installs, ensure npm bin is in PATH

# For cargo installs

No AI Agents Detected

Ralph auto-detects available AI CLI tools. If none are found:

1. Install one of the supported AI CLI tools (see Prerequisites)
2. Ensure the tool is in your PATH
3. Try running the AI CLI directly to verify it works

Permission Denied

If you get permission errors:

# For npm
sudo npm install -g @ralph-orchestrator/ralph-cli

# For symlinks
sudo ln -s $(pwd)/target/release/ralph /usr/local/bin/ralph

Next Steps

Now that Ralph is installed, proceed to the Quick Start guide.