vers upgrade

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

Usage

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

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

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

vers upgrade
Current version: v1.3.0
Latest version: v1.3.0
You are already running the latest version!

Include pre-releases

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:

Version check: Compares current version against GitHub releases
User confirmation: Prompts before downloading and installing
Download: Fetches appropriate binary for your platform
Verification: Validates download using SHA256 checksums
Backup: Creates backup of current binary before replacement
Installation: Replaces current binary with new version
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

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

# 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

vers upgrade
Error: cannot upgrade development or unknown versions

Solution: Use a released version of vers CLI.

No compatible binary

vers upgrade
Error: no compatible binary found for linux-riscv64

The platform isn’t supported by the current release.

Checksum mismatch

vers upgrade
Error: checksum verification failed: checksum mismatch

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

Permission issues

vers upgrade
Error: failed to install update: permission denied

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

Network failures

vers upgrade
Error: failed to check for updates: connection timeout

Solution: Check internet connection and try again.

Advanced usage

Skip checksum verification

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

vers upgrade --prerelease

Includes beta and release candidate versions in the update check.

Automated workflows

# 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:

ls -la $(which vers)

Manual recovery

If upgrade fails and automatic recovery doesn’t work:

# 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

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:

VERS_VERSION=v0.5.0 \
  curl -fsSL https://raw.githubusercontent.com/hdresearch/vers-cli/main/install.sh | sh

​vers upgrade

​Usage

​Options

​Examples

​Check and upgrade

​Check for updates only

​Already up to date

​Include pre-releases

​How it works

​Platform support

​Security features

​Checksum verification

​Backup and recovery

​Error handling

​Development version

​No compatible binary

​Checksum mismatch

​Permission issues

​Network failures

​Advanced usage

​Skip checksum verification

​Check pre-releases

​Automated workflows

​Troubleshooting

​Stuck downloads

​Permission errors

​Manual recovery

​Prerequisites

​Common Patterns

​Upgrade and verify

​Pin to a specific version

​See Also