kg6-codex
Getting Started

Upgrading & Migration

Learn how to upgrade AI Developer Assistant and migrate between versions

Upgrading & Migration

This guide covers upgrading AI Developer Assistant to newer versions and migrating between different LLM providers.

Upgrading AI Developer Assistant

Global Installation Upgrade

# Update to the latest version
npm update -g kg6-codex

# Or install specific version
npm install -g kg6-codex@latest

Local Installation Upgrade

# Navigate to your project directory
cd ai-developer-assistant

# Pull latest changes
git pull origin main

# Install updated dependencies
npm install

# Rebuild the project
npm run build

Verify Upgrade

# Check version
ai-dev --version

# Test functionality
ai-dev --help

Configuration Migration

Version-Specific Changes

From v1.0.x to v1.1.x

Breaking Changes:

  • Configuration file format updated
  • New LLM provider options added
  • Security scanning categories expanded

Migration Steps:

  1. Backup your configuration:
cp ai-dev.config.local.yaml ai-dev.config.local.yaml.backup
  1. Update configuration format:
# Old format (v1.0.x)
llm:
  provider: "openai"
  apiKey: "your-key"

# New format (v1.1.x)
llm:
  provider: "openai"
  model: "gpt-4"
  temperature: 0.7

openai:
  apiKey: "your-key"
  baseUrl: "https://api.openai.com/v1"
  1. Test new configuration:
ai-dev config validate

From v1.1.x to v1.2.x

New Features:

  • Gemini support added
  • Enhanced file pattern matching
  • New output formats

Migration Steps:

  1. Add Gemini configuration:
gemini:
  apiKey: "${GEMINI_API_KEY}"
  model: "gemini-pro"
  1. Update file patterns:
# Enhanced pattern support
filePatterns:
  - "**/*.ts"
  - "**/*.js"
  - "**/*.{ts,tsx}"  # Multiple extensions

LLM Provider Migration

Switching from OpenAI to Gemini

  1. Get Gemini API key:
  2. Update environment variables:
# Remove OpenAI key
unset OPENAI_API_KEY

# Add Gemini key
export GEMINI_API_KEY="your-gemini-key"
export LLM_PROVIDER="gemini"
  1. Update configuration:
llm:
  provider: "gemini"
  model: "gemini-pro"

gemini:
  apiKey: "${GEMINI_API_KEY}"
  1. Test migration:
ai-dev review --help

Switching from Cloud to Local (Ollama)

  1. Install Ollama:
curl -fsSL https://ollama.ai/install.sh | sh
  1. Pull a model:
ollama pull llama2
  1. Update configuration:
llm:
  provider: "ollama"
  model: "llama2"

ollama:
  enabled: true
  baseUrl: "http://localhost:11434"
  1. Test local setup:
ai-dev review --verbose

Switching from Gemini to OpenAI

  1. Get OpenAI API key:
  2. Update environment variables:
# Remove Gemini key
unset GEMINI_API_KEY

# Add OpenAI key
export OPENAI_API_KEY="your-openai-key"
export LLM_PROVIDER="openai"
  1. Update configuration:
llm:
  provider: "openai"
  model: "gpt-4"

openai:
  apiKey: "${OPENAI_API_KEY}"
  baseUrl: "https://api.openai.com/v1"

Command Migration

Deprecated Commands

Some commands may be deprecated in newer versions. Check the changelog for details:

# Old command (deprecated)
ai-dev analyze --type security

# New command
ai-dev security-scan

New Command Options

New versions may introduce additional options:

# New options in v1.2.x
ai-dev review --output-format html
ai-dev test-suggest --include-setup --include-teardown
ai-dev docs --include-parameters --include-return-types

Troubleshooting Upgrades

Common Upgrade Issues

Configuration errors after upgrade:

# Validate configuration
ai-dev config validate

# Reset to defaults
cp ai-dev.config.yaml ai-dev.config.local.yaml

Missing dependencies:

# Reinstall dependencies
npm install

# Clear cache and reinstall
npm cache clean --force
npm install

Permission issues:

# Fix permissions
chmod +x $(which ai-dev)

# Reinstall globally
npm uninstall -g kg6-codex
npm install -g kg6-codex

Rollback Process

If you need to rollback to a previous version:

# Install specific version
npm install -g kg6-codex@1.0.0

# Or restore from backup
cp ai-dev.config.local.yaml.backup ai-dev.config.local.yaml

Best Practices for Upgrades

Before Upgrading

  1. Backup your configuration:
cp ai-dev.config.local.yaml ai-dev.config.backup.yaml
  1. Check the changelog:
    • Review breaking changes
    • Note new features
    • Check migration requirements
  2. Test in development:
    • Upgrade in a test environment first
    • Verify all commands work
    • Test with your typical workflows

After Upgrading

  1. Verify installation:
ai-dev --version
ai-dev config show
  1. Test core functionality:
ai-dev review --help
ai-dev explain --help
ai-dev security-scan --help
  1. Update documentation:
    • Update team documentation
    • Share new features with team
    • Update CI/CD scripts if needed

Version Compatibility

Node.js Compatibility

AI Developer Assistant VersionNode.js Version
v1.0.x>= 16.0.0
v1.1.x>= 18.0.0
v1.2.x>= 18.0.0

Package Manager Compatibility

All versions support:

  • npm >= 7.0.0
  • pnpm >= 7.0.0
  • yarn >= 1.22.0
Always test upgrades in a development environment before applying to production workflows.

Getting Help

If you encounter issues during upgrade:

  1. Check the Troubleshooting Guide
  2. Review the GitHub Issues
  3. Join our Discord Community
  4. Open a new issue with upgrade details

CLI Usage Guide

Learn how to use AI Developer Assistant from the command line

Troubleshooting

Common issues and solutions for AI Developer Assistant