> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade

# vers upgrade

Check for and install the latest version of the vers CLI from GitHub releases.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade                    # Check and upgrade to latest version
vers upgrade --check-only       # Only check for updates, don't install
vers upgrade --prerelease       # Include pre-release versions
```

## Options

| Option            | Description                                         |
| ----------------- | --------------------------------------------------- |
| `--check-only`    | Only check for updates without installing           |
| `--prerelease`    | Include pre-release versions                        |
| `--skip-checksum` | Skip SHA256 checksum verification (not recommended) |

## Examples

### Check and upgrade

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
Current version: v1.2.0
Latest version: v1.3.0

Upgrade from v1.2.0 to v1.3.0?
Do you want to continue? [y/N]: y

Downloading vers-darwin-arm64...
Progress: 100.0% (15728640/15728640 bytes)
Verifying download integrity...
✓ Checksum verification passed
✓ Successfully upgraded to version v1.3.0!
Please restart any running vers processes to use the new version.
```

### Check for updates only

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade --check-only
Current version: v1.2.0
Latest version: v1.3.0
A new version is available: v1.2.0 -> v1.3.0
Run 'vers upgrade' to install the update.
```

### Already up to date

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
Current version: v1.3.0
Latest version: v1.3.0
You are already running the latest version!
```

### Include pre-releases

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade --prerelease
Current version: v1.3.0
Latest version: v1.4.0-beta.1

Upgrade from v1.3.0 to v1.4.0-beta.1?
Do you want to continue? [y/N]: y
```

## How it works

The `upgrade` command:

1. **Version check**: Compares current version against GitHub releases
2. **User confirmation**: Prompts before downloading and installing
3. **Download**: Fetches appropriate binary for your platform
4. **Verification**: Validates download using SHA256 checksums
5. **Backup**: Creates backup of current binary before replacement
6. **Installation**: Replaces current binary with new version
7. **Cleanup**: Removes temporary files and backup on success

## Platform support

The upgrade system supports multiple platforms:

* **macOS**: `vers-darwin-amd64`, `vers-darwin-arm64`
* **Linux**: `vers-linux-amd64`, `vers-linux-arm64`, `vers-linux-386`
* **Windows**: `vers-windows-amd64.exe`, `vers-windows-arm64.exe`

The command automatically detects your platform and downloads the appropriate binary.

## Security features

### Checksum verification

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
...
Verifying download integrity...
✓ Checksum verification passed
```

By default, the command verifies SHA256 checksums to ensure download integrity. This prevents corruption or tampering.

### Backup and recovery

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Automatic backup creation
Creating backup at: /usr/local/bin/vers.backup

# Automatic restoration on failure
Installation failed, restoring backup
```

The command creates a backup before upgrade and restores it if installation fails.

## Error handling

### Development version

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
Error: cannot upgrade development or unknown versions
```

**Solution**: Use a released version of vers CLI.

### No compatible binary

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
Error: no compatible binary found for linux-riscv64
```

The platform isn't supported by the current release.

### Checksum mismatch

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
Error: checksum verification failed: checksum mismatch
```

**Solution**: Try again or use `--skip-checksum` (not recommended).

### Permission issues

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
Error: failed to install update: permission denied
```

**Solution**: Run with appropriate permissions or use a package manager.

### Network failures

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
Error: failed to check for updates: connection timeout
```

**Solution**: Check internet connection and try again.

## Advanced usage

### Skip checksum verification

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade --skip-checksum
...
⚠️  Skipping checksum verification (not recommended)
```

**Warning**: Only use this if checksum verification fails and you trust the source.

### Check pre-releases

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade --prerelease
```

Includes beta and release candidate versions in the update check.

### Automated workflows

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check for updates in scripts
if vers upgrade --check-only | grep -q "A new version is available"; then
  echo "Update available"
  # Optionally auto-upgrade
  vers upgrade --skip-checksum
fi
```

## Troubleshooting

### Stuck downloads

If download appears stuck, cancel and retry. The command uses a 32KB buffer for progress display.

### Permission errors

Ensure you have write access to the vers binary location:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ls -la $(which vers)
```

### Manual recovery

If upgrade fails and automatic recovery doesn't work:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Find the backup
ls -la /path/to/vers.backup

# Restore manually if needed
cp /path/to/vers.backup /path/to/vers
chmod +x /path/to/vers
```

## Prerequisites

* Internet connectivity to reach GitHub API
* Write permissions to the vers binary location
* Sufficient disk space for download and backup

## Common Patterns

### Upgrade and verify

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers upgrade
vers --version
```

### Pin to a specific version

`vers upgrade` always pulls the latest release. To downgrade or pin, re-run the installer with `VERS_VERSION`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
VERS_VERSION=v0.5.0 \
  curl -fsSL https://raw.githubusercontent.com/hdresearch/vers-cli/main/install.sh | sh
```

## See Also

* [vers status](/cli-reference/status) - Check environment after upgrading