# Installation & Setup

Get RiceCoder installed and configured for your system.

## Overview

This guide walks you through installing RiceCoder on your system and configuring it for your first use. It covers system requirements, installation methods for different platforms, post-installation setup, and troubleshooting common installation issues.

## System Requirements

- **OS**: Linux, macOS, or Windows
- **Rust**: 1.75+ (for building from source)
- **Git**: For version control integration
- **Terminal**: Any modern terminal (bash, zsh, fish, PowerShell)

## Installation Methods

### Method 1: Cargo (Recommended)

Install from [crates.io](https://crates.io/crates/ricecoder) - the easiest and most portable method:

```bash
# Install ricecoder
cargo install ricecoder

# Verify installation
rice --version
```

**Updating to the latest version:**

```bash
# Update to the latest version
cargo install --force ricecoder

# Or use the shorter form
cargo install -f ricecoder
```

**Uninstalling:**

```bash
# Remove ricecoder
cargo uninstall ricecoder
```

**Advantages**:
- ✅ Works on all platforms (Linux, macOS, Windows)
- ✅ Easy to update
- ✅ No system dependencies
- ✅ Automatic PATH setup

**Requirements**:
- Rust 1.75+ ([Install Rust](https://rustup.rs/))

**Platforms**: Linux (x86_64, ARM64), macOS (Intel, Apple Silicon), Windows (x86_64, ARM64)

---

### Method 2: Curl Script (Quick Setup)

Build and install from source with a single command:

```bash
# Install
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash

# With custom prefix
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --prefix /usr/local

# Debug build
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --debug

# Verify
rice --version
```

**What it does**:
1. Detects your OS and architecture
2. Downloads the installation script
3. Checks prerequisites (Rust, Cargo, Git)
4. Updates Rust toolchain
5. Builds from source
6. Installs binaries to specified prefix
7. Verifies installation

**Advantages**:
- ✅ Single command
- ✅ Automatic platform detection
- ✅ Prerequisite checking
- ✅ Automatic Rust update
- ✅ Customizable installation prefix
- ✅ Installation verification

**Requirements**:
- curl
- bash or sh
- Rust 1.75+ (will be installed/updated automatically)

**Platforms**: Linux (x86_64, ARM64), macOS (Intel, Apple Silicon)

**Troubleshooting**:
- If script fails, try: `bash -c "$(curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install)"`
- For Windows, use PowerShell script or Cargo instead

---

### Method 3: npm (Node.js Developers)

Install via npm registry:

```bash
# Install globally
npm install -g ricecoder

# Verify
rice --version

# Update
npm install -g ricecoder@latest

# Uninstall
npm uninstall -g ricecoder
```

**What it does**:
1. Downloads pre-built binary for your platform
2. Installs to npm global directory
3. Creates `rice` command in PATH

**Advantages**:
- ✅ Familiar npm workflow
- ✅ Easy version management
- ✅ Works with Node.js projects
- ✅ Cross-platform

**Requirements**:
- Node.js 14+ ([Install Node.js](https://nodejs.org/))
- npm (included with Node.js)

**Platforms**: Linux, macOS, Windows

---

### Method 4: Homebrew (macOS)

Install via Homebrew package manager:

```bash
# Install
brew install ricecoder

# Verify
rice --version

# Update
brew upgrade ricecoder

# Uninstall
brew uninstall ricecoder
```

**Advantages**:
- ✅ Native macOS integration
- ✅ Easy updates
- ✅ System package manager
- ✅ Automatic dependency management

**Requirements**:
- Homebrew ([Install Homebrew](https://brew.sh/))

**Platforms**: macOS only

---

### Method 5: Docker

Run RiceCoder in a Docker container for isolated, reproducible environments:

```bash
# Pull the image
docker pull moabualruz/ricecoder:latest

# Run RiceCoder
docker run --rm moabualruz/ricecoder:latest --version

# Run with volume mounting for workspace access
docker run -it -v $(pwd):/workspace moabualruz/ricecoder:latest chat

# Run with environment variables
docker run -it \
  -e OPENAI_API_KEY="your-key" \
  -v $(pwd):/workspace \
  moabualruz/ricecoder:latest chat
```

**Advantages**:
- ✅ Isolated environment
- ✅ No system dependencies
- ✅ Consistent across platforms
- ✅ Easy cleanup
- ✅ Works on any platform with Docker

**Requirements**:
- Docker ([Install Docker](https://docs.docker.com/get-docker/))

**Platforms**: Any platform with Docker (Linux, macOS, Windows)

**Image Tags**:
- `latest` - Latest stable release
- `v0.1.6` - Specific version
- `dev` - Development version (if available)

**See Also**: [Docker Setup Guide](./Docker-Setup.md) - Comprehensive Docker documentation

---

### Method 6: Build from Source

Clone and build locally for development or customization.

#### Using Installation Scripts (Recommended)

Automated build and installation with prerequisite checking:

**Linux/macOS**:

```bash
# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Make script executable
chmod +x scripts/install.sh

# Run installation script
./scripts/install.sh

# Verify installation
rice --version
```

**Installation Script Options**:

```bash
# Install to custom prefix
./scripts/install.sh --prefix /usr/local

# Debug build (faster compilation)
./scripts/install.sh --debug

# Verbose output
./scripts/install.sh --verbose

# Show help
./scripts/install.sh --help
```

**Windows (PowerShell)**:

```powershell
# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Run installation script
.\scripts\install.ps1

# Verify installation
rice --version
```

**Installation Script Options**:

```powershell
# Install to custom prefix
.\scripts\install.ps1 -Prefix "C:\Program Files\ricecoder"

# Debug build
.\scripts\install.ps1 -Debug

# Verbose output
.\scripts\install.ps1 -Verbose

# Show help
.\scripts\install.ps1 -Help
```

**Windows (CMD)**:

```cmd
# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Run installation script
scripts\install.bat

# Verify installation
rice --version
```

**Installation Script Options**:

```cmd
# Install to custom prefix
scripts\install.bat --prefix "C:\Program Files\ricecoder"

# Debug build
scripts\install.bat --debug

# Verbose output
scripts\install.bat --verbose

# Show help
scripts\install.bat --help
```

#### Manual Build and Install

For advanced users or custom builds:

```bash
# Clone the repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Build and install
cargo install --path projects/ricecoder

# Verify installation
rice --version
```

**Advantages**:
- ✅ Latest development version
- ✅ Full source access
- ✅ Customizable build
- ✅ Contribute to development
- ✅ Automatic prerequisite checking (with scripts)
- ✅ Automatic Rust toolchain update (with scripts)

**Requirements**:
- Rust 1.75+ ([Install Rust](https://rustup.rs/))
- Git
- C compiler (gcc, clang, or MSVC)

**Platforms**: Linux, macOS, Windows

**Development Setup**:

```bash
# Clone with submodules
git clone --recursive https://github.com/moabualruz/ricecoder.git

# Build in debug mode (faster compilation)
cargo build

# Build in release mode (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- chat
```

**Installation Script Features**:

The installation scripts provide:
- ✅ Automatic OS and architecture detection
- ✅ Prerequisite verification (Rust, Cargo, Git)
- ✅ Automatic Rust toolchain update
- ✅ Configurable build mode (release/debug)
- ✅ Automatic binary installation
- ✅ Configuration file installation
- ✅ Documentation installation
- ✅ Installation verification
- ✅ PATH configuration guidance
- ✅ Comprehensive error handling

**See Also**: [Installation Guide](../INSTALLATION.md) - Comprehensive build and installation documentation

---

### Platform Support Matrix

| Platform | Arch | Cargo | Curl | npm | Homebrew | Docker | Source |
|----------|------|-------|------|-----|----------|--------|--------|
| **Linux** | x86_64 | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
| **Linux** | ARM64 | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
| **macOS** | Intel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **macOS** | Apple Silicon | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Windows** | x86_64 | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ |
| **Windows** | ARM64 | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ |

**Legend**: ✅ Supported | ❌ Not available

---

### Choosing an Installation Method

**Use Cargo if**:
- You have Rust installed
- You want the easiest cross-platform method
- You want automatic updates

**Use Curl if**:
- You're on Linux or macOS
- You want a quick one-line install
- You don't have Rust installed

**Use npm if**:
- You're a Node.js developer
- You want npm-style version management
- You're on Windows

**Use Homebrew if**:
- You're on macOS
- You prefer system package managers
- You want native integration

**Use Docker if**:
- You want an isolated environment
- You need consistent setup across machines
- You don't want to install dependencies

**Use Source if**:
- You're contributing to development
- You need the latest development version
- You want to customize the build

## Post-Installation Setup

### 1. Verify Installation

After installation, verify RiceCoder is working:

```bash
# Check version
rice --version

# Show help
rice --help

# Check system information
rice info --system
```

---

### 2. Initialize RiceCoder

Initialize your first project:

```bash
rice init
```

This creates:
- `~/.ricecoder/` - Global configuration directory
- `.agent/` - Project-specific configuration (in current directory)
- `.ricecoder/config.yaml` - Project configuration file

**What gets created**:
- Global config: `~/.ricecoder/config.yaml`
- Project config: `.agent/config.yaml`
- Steering files: `.ai/steering/`
- Hooks: `.ai/hooks/`

### 3. Configure Your AI Provider

Choose one of the following providers:

#### Option A: OpenAI (Recommended)

```bash
# Get your API key from https://platform.openai.com/api-keys
export OPENAI_API_KEY="your-api-key"

# Configure RiceCoder
rice config set provider openai
rice config set model gpt-4

# Verify configuration
rice config show
```

**Supported Models**:
- `gpt-4` - Most capable (recommended)
- `gpt-4-turbo` - Faster, cheaper
- `gpt-3.5-turbo` - Budget option

**Pricing**: See [OpenAI Pricing](https://openai.com/pricing)

---

#### Option B: Anthropic

```bash
# Get your API key from https://console.anthropic.com/
export ANTHROPIC_API_KEY="your-api-key"

# Configure RiceCoder
rice config set provider anthropic
rice config set model claude-3-opus

# Verify configuration
rice config show
```

**Supported Models**:
- `claude-3-opus` - Most capable
- `claude-3-sonnet` - Balanced
- `claude-3-haiku` - Fast, budget

**Pricing**: See [Anthropic Pricing](https://www.anthropic.com/pricing)

---

#### Option C: Local Models (Ollama)

Use local models for offline-first development:

```bash
# Install Ollama
# macOS:
brew install ollama

# Linux:
curl https://ollama.ai/install.sh | sh

# Windows:
# Download from https://ollama.ai/download

# Start Ollama service
ollama serve

# In another terminal, pull a model
ollama pull mistral

# Configure RiceCoder
rice config set provider ollama
rice config set model mistral
rice config set ollama-url http://localhost:11434

# Verify configuration
rice config show
```

**Recommended Models**:
- `mistral` - Fast, good quality
- `neural-chat` - Optimized for chat
- `llama2` - General purpose
- `codellama` - Code generation

**Advantages**:
- ✅ Offline-first (no internet required)
- ✅ No API costs
- ✅ Full privacy
- ✅ Unlimited usage

**See Also**: [Local Models Guide](./Local-Models.md) - Detailed Ollama setup

---

#### Option D: Other Providers

RiceCoder supports 75+ AI providers. See [AI Providers Guide](./AI-Providers.md) for complete list.

---

### 4. Verify Configuration

```bash
# Show current configuration
rice config show

# Validate configuration
rice config validate

# Test connection to provider
rice chat --test

# Show system information
rice info --system
```

**Expected output**:
```
✅ Configuration valid
✅ Provider connected
✅ Model available
✅ Ready to use
```

## Environment Variables

### Required

- `OPENAI_API_KEY` - For OpenAI provider
- `ANTHROPIC_API_KEY` - For Anthropic provider

### Optional

- `RICECODER_HOME` - Custom location for global config (default: `~/.ricecoder/`)
- `RICECODER_LOG_LEVEL` - Logging level (debug, info, warn, error)
- `RICECODER_OFFLINE` - Enable offline mode (true/false)

### Example

```bash
# Set environment variables
export OPENAI_API_KEY="sk-..."
export RICECODER_HOME="$HOME/.config/ricecoder"
export RICECODER_LOG_LEVEL="debug"

# Start RiceCoder
rice chat
```

## Configuration Files

### Global Configuration

Located at `~/.ricecoder/config.yaml`:

```yaml
# AI Provider Configuration
provider: openai
model: gpt-4
api-key: ${OPENAI_API_KEY}

# UI Configuration
theme: dracula
colors: true

# Behavior Configuration
offline-mode: false
auto-approve: false
```

### Project Configuration

Located at `.agent/config.yaml`:

```yaml
# Project-specific settings
project-name: my-project
language: rust

# Custom commands
commands:
  test:
    command: cargo test
    description: Run tests
  build:
    command: cargo build --release
    description: Build release binary

# Permissions
permissions:
  file-write: ask
  file-delete: deny
  shell-execute: ask
```

### Steering Files

Located at `.ai/steering/`:

```yaml
# Project-level rules and standards
standards:
  language: rust
  style: idiomatic
  testing: comprehensive

# AI behavior customization
ai:
  model: gpt-4
  temperature: 0.7
  max-tokens: 2000
```

## Installation Troubleshooting

### "Command not found: rice"

**Problem**: After installation, `rice` command is not found.

**Solution**:

1. Restart your terminal
2. Verify installation completed: `rice --version`
3. Check PATH environment variable:
   - Linux/macOS: `echo $PATH`
   - Windows: `echo %PATH%`
4. Verify binary location:
   - Linux/macOS: `which rice`
   - Windows: `where rice`
5. If using custom shell (zsh, fish), reload configuration:
   - zsh: `source ~/.zshrc`
   - fish: `source ~/.config/fish/config.fish`
6. Reinstall if needed: `cargo install ricecoder`

**See Also**: [Full Troubleshooting Guide](./Troubleshooting.md#command-not-found-after-installation)

---

### "Permission denied"

**Problem**: Installation fails with permission errors.

**Solution**:

1. Check file permissions:
   ```bash
   ls -la ~/.cargo/bin/rice
   ```

2. Fix permissions:
   ```bash
   chmod +x ~/.cargo/bin/rice
   chmod 755 .agent/
   chmod 644 .agent/config.yaml
   ```

3. Ensure directory is in PATH
4. Try installing to home directory instead of system directories

**See Also**: [Full Troubleshooting Guide](./Troubleshooting.md#permission-denied)

---

### "Build failed" (Curl)

**Problem**: Curl installation fails during build.

**Solution**:

1. Re-run installation script:
   ```bash
   curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash
   ```

2. Check network connection:
   ```bash
   ping github.com
   ```

3. Try alternative installation method (Cargo, Docker, npm)

4. Check available disk space:
   ```bash
   df -h
   ```

5. Try with reduced parallelism:
   ```bash
   curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --debug
   ```

---

### "API key not found"

**Problem**: RiceCoder can't find API key for AI provider.

**Solution**:

1. Set API key as environment variable:
   ```bash
   # For OpenAI
   export OPENAI_API_KEY="your-api-key"

   # For Anthropic
   export ANTHROPIC_API_KEY="your-api-key"

   # Verify
   echo $OPENAI_API_KEY
   ```

2. Or set in configuration file:
   ```bash
   rice config set api-key "your-api-key"
   ```

3. Verify API key is valid:
   - OpenAI: https://platform.openai.com/api-keys
   - Anthropic: https://console.anthropic.com/

4. Check for extra whitespace or quotes

**See Also**: [Full Troubleshooting Guide](./Troubleshooting.md#api-key-invalid)

---

### "Connection refused" (Ollama)

**Problem**: Can't connect to Ollama service.

**Solution**:

1. Start Ollama service:
   ```bash
   ollama serve
   ```

2. In another terminal, verify it's running:
   ```bash
   curl http://localhost:11434/api/tags
   ```

3. Check Ollama is installed:
   ```bash
   ollama --version
   ```

4. Check firewall isn't blocking port 11434

5. Verify configuration:
   ```bash
   rice config show
   ```

**See Also**: [Local Models Guide](./Local-Models.md)

---

### "Model not found"

**Problem**: Ollama model is not available.

**Solution**:

1. List available models:
   ```bash
   ollama list
   ```

2. Pull a model:
   ```bash
   ollama pull mistral
   ```

3. Verify model is installed:
   ```bash
   ollama list
   ```

4. Update Ollama to latest version:
   ```bash
   ollama update
   ```

**Recommended Models**:
- `mistral` - Fast, good quality
- `neural-chat` - Optimized for chat
- `llama2` - General purpose
- `codellama` - Code generation

**See Also**: [Local Models Guide](./Local-Models.md)

---

### "Out of memory"

**Problem**: RiceCoder uses too much memory or crashes.

**Solution**:

1. Reduce context size:
   ```bash
   rice config set max-context 4000
   ```

2. Use a smaller model:
   ```bash
   rice config set model gpt-3.5-turbo
   ```

3. Use local models (Ollama) for lower memory usage:
   ```bash
   rice config set provider ollama
   ```

4. Close other applications to free memory

5. Check available memory:
   ```bash
   free -h  # Linux
   vm_stat  # macOS
   ```

---

### "Docker image not found"

**Problem**: Docker can't find RiceCoder image.

**Solution**:

1. Pull the image:
   ```bash
   docker pull moabualruz/ricecoder:latest
   ```

2. Verify Docker is running:
   ```bash
   docker ps
   ```

3. Check internet connection:
   ```bash
   ping docker.io
   ```

4. List available images:
   ```bash
   docker images
   ```

**See Also**: [Docker Setup Guide](./Docker-Setup.md)

---

### "Installation fails on Windows"

**Problem**: Installation fails with permission or path errors on Windows.

**Solution**:

1. Run terminal as Administrator
2. Disable antivirus temporarily during installation
3. Check Windows PATH is not corrupted
4. Try installing to directory without spaces
5. If using WSL, ensure WSL2 is properly configured
6. Restart terminal after installation

---

### "Installation fails on macOS"

**Problem**: Installation fails with Homebrew or permission errors.

**Solution**:

1. Verify Homebrew is installed:
   ```bash
   brew --version
   ```

2. Update Homebrew:
   ```bash
   brew update
   ```

3. Fix permission issues:
   ```bash
   sudo chown -R $(whoami) /usr/local/Cellar
   ```

4. For M1/M2 Mac, ensure ARM64 version is used

5. Try installing from source if binary fails

---

### "Installation fails on Linux"

**Problem**: Installation fails with missing dependencies.

**Solution**:

1. Install required dependencies:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install build-essential libssl-dev

   # Fedora/RHEL
   sudo dnf install gcc openssl-devel

   # Arch
   sudo pacman -S base-devel openssl
   ```

2. Check available disk space:
   ```bash
   df -h
   ```

3. Verify Linux distribution is supported (Ubuntu 18.04+, Fedora 30+, etc.)

4. Try installing to home directory instead of system directories

## Uninstallation

### Remove RiceCoder

```bash
# If installed via cargo
cargo uninstall ricecoder

# If built from source
cd ricecoder
cargo uninstall --path projects/ricecoder
```

### Remove Configuration

```bash
# Remove global configuration
rm -rf ~/.ricecoder/

# Remove project configuration
rm -rf .agent/
```

## Next Steps

1. **[Quick Start Guide](./Quick-Start)** - Your first project
2. **[Configuration Guide](./Configuration)** - Customize RiceCoder
3. **[CLI Commands](./CLI-Commands)** - Learn all commands
4. **[Spec-Driven Development](./Spec-Driven-Development)** - Master specs

## Getting Help

- **Documentation**: [RiceCoder Wiki](./Home)
- **Issues**: [GitHub Issues](https://github.com/moabualruz/ricecoder/issues)
- **Discussions**: [GitHub Discussions](https://github.com/moabualruz/ricecoder/discussions)

## See Also

- [Quick Start Guide](./Quick-Start.md) - Get started in 5 minutes
- [Configuration Guide](./Configuration.md) - Detailed configuration options
- [AI Providers Guide](./AI-Providers.md) - Provider setup and comparison
- [Local Models Guide](./Local-Models.md) - Using Ollama for local models
- [Troubleshooting Guide](./Troubleshooting.md) - Common issues and solutions

---

*Last updated: December 3, 2025*