Skip to content

Upgrade Guide

Jump to bottom
Mo Abualruz edited this page Dec 9, 2025 · 2 revisions

Upgrade Guide

Status: ✅ Complete

Last Updated: December 5, 2025

Overview

This guide helps you upgrade RiceCoder to a newer version while preserving your configuration, sessions, and data.

Table of Contents

Before Upgrading

Check Current Version

rice --version

Backup Your Data

Before upgrading, backup your important data:

# Backup configuration
cp -r ~/.ricecoder ~/.ricecoder.backup

# Backup project configuration
cp -r .agent .agent.backup

Check Release Notes

Review the release notes for the version you're upgrading to:

Check Breaking Changes

Some versions may have breaking changes. Check:

  1. Configuration Changes: New or changed configuration options
  2. API Changes: Changes to CLI commands or APIs
  3. Data Format Changes: Changes to session or configuration formats
  4. Dependency Updates: Updates to dependencies

Upgrade Methods

Method 1: Using Cargo (Recommended)

# Update to latest version
cargo install ricecoder --force

# Verify upgrade
rice --version

Method 2: From Source

# Clone the latest version
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

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

# Verify upgrade
rice --version

Method 3: Pre-built Binaries

When available, download pre-built binaries:

  1. Visit GitHub Releases
  2. Download the binary for your platform
  3. Extract and install
  4. Verify installation: rice --version

Post-Upgrade Steps

1. Verify Installation

# Check version
rice --version

# Check configuration
rice config show

# Test basic functionality
rice chat --help

2. Migrate Configuration (if needed)

Some upgrades may require configuration migration:

# Validate configuration
rice config validate

# If validation fails, check release notes for migration steps

3. Update Configuration

If there are new configuration options, update your configuration:

# Show current configuration
rice config show

# Update specific settings
rice config set new-option value

# Or edit configuration file directly
nano ~/.ricecoder/config.yaml

4. Test Features

Test key features to ensure everything works:

# Test chat
rice chat

# Test code generation
rice gen --spec test-feature --preview

# Test LSP
rice lsp status

# Test completion
rice completion status

5. Update Project Configuration (if needed)

If you have project-specific configuration, update it:

# Check project configuration
cat .agent/config.yaml

# Update if needed
rice config set --project new-option value

Troubleshooting

Issue: Upgrade Fails

Problem: Cargo fails to install the new version.

Solution:

  1. Clear cargo cache:

    cargo clean

  2. Try installing again:

    cargo install ricecoder --force

  3. If still failing, try from source:

    git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder
cargo install --path projects/ricecoder --force

Issue: Configuration Not Working After Upgrade

Problem: Configuration settings are not recognized after upgrade.

Solution:

  1. Validate configuration:

    rice config validate

  2. Check for breaking changes in release notes

  3. Reset to defaults and reconfigure:

    rice config reset
rice config set provider openai
rice config set model gpt-4

  4. Check configuration file for syntax errors:

    cat ~/.ricecoder/config.yaml

Issue: Sessions Not Loading After Upgrade

Problem: Saved sessions don't load after upgrade.

Solution:

  1. Check session directory:

    ls -la ~/.ricecoder/sessions/

  2. Check session file format:

    cat ~/.ricecoder/sessions/my-session.json

  3. If format changed, sessions may need migration (check release notes)

  4. Try creating a new session:

    rice session save new-session

Issue: Performance Issues After Upgrade

Problem: RiceCoder is slower after upgrade.

Solution:

  1. Clear cache:

    rice cache clear

  2. Check system resources:

    top  # macOS/Linux
# or Task Manager (Windows)

  3. Restart RiceCoder

  4. Check release notes for performance-related changes

  5. If issue persists, downgrade and report the issue

Downgrading

If you need to downgrade to a previous version:

Downgrade Using Cargo

# Install specific version
cargo install ricecoder --version 0.1.6 --force

# Verify downgrade
rice --version

Restore from Backup

If you backed up your data before upgrading:

# Restore configuration
rm -rf ~/.ricecoder
cp -r ~/.ricecoder.backup ~/.ricecoder

# Restore project configuration
rm -rf .agent
cp -r .agent.backup .agent

Report Issues

If you need to downgrade due to issues, please report the issue:

  1. GitHub Issues
  2. GitHub Discussions
  3. Discord

Version History

v0.1.6 (Current - Alpha)

Release Date: December 6, 2025

New Features:

  • Multi-Project Orchestration
  • Domain-Specific Agents
  • Learning System with personalization

Breaking Changes: None

Migration Steps: None required

Upgrade Path: From v0.1.5 → v0.1.6

v0.1.5 (Previous - Alpha)

Release Date: December 3, 2025

Features:

  • Code Generation from specs
  • Multi-Agent Framework
  • Workflows and Execution Plans
  • Sessions and Modes

Upgrade Path: From v0.1.1 → v0.1.2

v0.1.1 (Alpha)

Release Date: December 1, 2025

Features:

  • CLI Foundation
  • AI Providers (75+)
  • TUI Interface
  • Spec System
  • File Management
  • Templates and Boilerplates
  • Research System
  • Permissions System
  • Custom Commands
  • Local Models (Ollama)
  • Storage and Configuration

Upgrade Checklist

Before upgrading, ensure you:

  • Check current version: rice --version
  • Backup configuration: cp -r ~/.ricecoder ~/.ricecoder.backup
  • Backup project config: cp -r .agent .agent.backup
  • Review release notes
  • Check for breaking changes
  • Have internet connection (for downloading)
  • Have sufficient disk space

After upgrading, ensure you:

  • Verify installation: rice --version
  • Validate configuration: rice config validate
  • Test basic functionality: rice chat --help
  • Update configuration if needed
  • Test key features
  • Update project configuration if needed
  • Delete backup if everything works

Getting Help

If you encounter issues during upgrade:

  1. Check Troubleshooting: See Troubleshooting above
  2. Check Release Notes: Review release notes for your version
  3. Check FAQ: FAQ
  4. Ask Community: GitHub Discussions
  5. Report Issue: GitHub Issues

See Also

Last updated: December 5, 2025

Clone this wiki locally