> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/user-guide/installation/migration-guide.md).

# Migration Guide

This guide explains how to migrate from previous versions of Orbitron to the auto-update system.

## 🔍 When Migration Is Needed

Migration is recommended if Orbitron is installed in any of the following locations:

* `~/.orbitron/bin/`
* `/usr/local/bin/` (manual installation)
* Other custom locations

The new installation location is `~/.local/bin/orbitron` and uses a version management system (`~/.local/share/orbitron/versions/`).

## 🚀 Automatic Migration (Recommended)

The automated installation script detects existing installations and provides interactive migration.

### Step 1: Run the Installation Script

```bash
# macOS / Linux
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash

# Windows (PowerShell)
irm https://orbitron.megaone.com/api/install.ps1 | iex
```

### Step 2: Migration Prompt

When an existing installation is detected, you'll see the following message:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Old Installation Detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Old version: v0.1.11 (in ~/.orbitron/bin/)
New version: v0.1.12 (will be installed to ~/.local/bin/)

Would you like to migrate the old installation?
  YES: Backup old version, install new version, update PATH
  NO:  Keep both versions (you can remove old version later)

Migrate old installation? (Y/n):
```

### Step 3: Choose an Option

#### Option A: Migrate (Y or Enter - Recommended)

Press `Y`, `yes`, or `Enter`:

```
Migrating old installation...

✅ Backed up v0.1.11 to ~/.local/share/orbitron/versions/0.1.11
✅ Removed old binary from ~/.orbitron/bin/
✅ Removed old PATH from ~/.zshrc
```

Then the new version installation proceeds:

```
✅ Installed to ~/.local/share/orbitron/versions/0.1.12
✅ Updated symlink at ~/.local/bin/orbitron
✅ Added PATH to ~/.zshrc
```

#### Option B: Keep Both Versions (N or n)

Press `N` or `n`:

```
Keeping both versions...

⚠️  Old version will remain at: ~/.orbitron/bin/
    New version will be installed to: ~/.local/bin/
```

After installation completes:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Installation Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  Both old and new versions are installed

To use the new version:
  1. Make sure ~/.local/bin is in your PATH
  2. Remove or rename the old binary:
     rm ~/.orbitron/bin/orbitron

To verify which version is running:
  orbitron --version
  which orbitron
```

### Step 4: Auto-Update Configuration

After the migration choice, you'll be prompted to configure auto-update:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Auto-Update Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Would you like to enable automatic updates?
You can change this setting later with: orbitron config set autoUpdate <true|false>

Enable auto-update? (Y/n):
```

* `Y`, `yes`, or `Enter`: Enable auto-update
* `N` or `n`: Disable auto-update

### Step 5: Installation Complete and Verification

If PATH configuration succeeds:

```bash
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ⚡ Next Steps
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

To start using orbitron, reload your shell:

  source ~/.zshrc

Then verify the installation:

  orbitron --version
```

For Windows:

```
To start using orbitron, reload your PowerShell profile:

  . C:\Users\username\Documents\PowerShell\Microsoft.PowerShell_profile.ps1

Or simply open a new PowerShell window.

Then verify the installation:

  orbitron --version
```

## 🎯 Post-Migration Verification

After restarting your terminal or reloading the configuration file:

```
# Check version
orbitron --version

# Check installation location
which orbitron
# Output: /Users/username/.local/bin/orbitron

# Check auto-update setting
orbitron config get autoUpdate
```

## ⚠️ Important Notes

### If You Selected YES for Migration

* The old binary is automatically backed up to: `~/.local/share/orbitron/versions/{old_version}/`
* The binary is removed from the old installation location (`~/.orbitron/bin/` or `/usr/local/bin/`)
* The old PATH is automatically removed from shell configuration files (Unix/Linux/macOS only)
* The `~/.orbitron/bin/` directory is automatically removed if empty

### If You Selected NO for Migration

You can manually remove the old version later:

```
# Remove old binary
rm ~/.orbitron/bin/orbitron

# Remove directory if empty
rmdir ~/.orbitron/bin
rmdir ~/.orbitron  # If no other files exist
```

### Configuration File

The existing configuration file (`~/.orbitron.json`) is automatically compatible, so no changes are needed.

For more troubleshooting, see the [Troubleshooting Guide](/orbitron-docs/user-guide/installation/troubleshooting.md).

## 🔗 Related Documentation

* [Installation Guide](/orbitron-docs/user-guide/installation.md) - How to install Orbitron
* [Auto-Update Guide](/orbitron-docs/user-guide/installation/auto-update.md) - Auto-update configuration and usage
* [Troubleshooting](/orbitron-docs/user-guide/installation/troubleshooting.md) - Common issues and solutions