upgrade

Upgrade the moon binary to the latest version

The moon upgrade command can be used to upgrade your current moon binary (if installed globally) to the latest version.

$ moon upgrade

Output:

▪▪▪▪ Upgrading moon to version 1.30.0...
ⓘ Upgraded moon to version 1.30.0!

:::caution

This command will only work if moon was installed in the ~/.moon directory, using our official installation script. If installed another way, you’ll need to upgrade manually.

:::

How It Works

The upgrade process:

1. Checks for updates - Queries the latest version from the manifest
2. Downloads binary - Downloads the appropriate binary for your platform
3. Replaces executable - Safely replaces the running binary
4. Cleans up - Removes temporary files

Installation Requirements

The upgrade command works only when:

Installed via Official Script

# Original installation
$ curl -fsSL https://moonrepo.dev/install/moon.sh | bash

# Now you can upgrade
$ moon upgrade

Installed in ~/.moon Directory

Moon must be in ~/.moon/bin/:

$ which moon
/Users/username/.moon/bin/moon

# ✓ Can upgrade
$ moon upgrade

Installed via proto

If installed via proto, use proto to upgrade:

# Check current version
$ proto list moon

# Upgrade via proto
$ proto install moon latest --pin global

# Or use moon upgrade (it detects proto)
$ moon upgrade

Unsupported Installations

The upgrade command will NOT work for:

System Package Managers

# Homebrew
$ brew upgrade moon

# apt/yum/etc
$ sudo apt update && sudo apt upgrade moon

Docker Containers

Upgrade by updating the container image:

FROM ghcr.io/moonrepo/moon:latest

Custom Installations

If installed to a custom location:

⚠ moon can only upgrade itself when installed in the ~/.moon directory.
  moon is currently installed at /usr/local/bin/moon!

You must upgrade manually.

Version Checking

Before upgrading, moon checks if an update is available:

Already Latest

ⓘ You're already on the latest version of moon!

No upgrade needed.

Update Available

▪▪▪▪ Upgrading moon to version 1.30.0...

Upgrade proceeds automatically.

Offline Mode

If no internet connection:

✗ Upgrade requires an internet connection

Connect to the internet and try again.

Platform Support

The upgrade command supports:

Linux

• x86_64-unknown-linux-gnu
• x86_64-unknown-linux-musl
• aarch64-unknown-linux-gnu
• aarch64-unknown-linux-musl

macOS

• x86_64-apple-darwin (Intel)
• aarch64-apple-darwin (Apple Silicon)

Windows

• x86_64-pc-windows-msvc
• aarch64-pc-windows-msvc

Safety Features

Self-Replacement

The upgrade safely replaces the running binary:

1. Renames current - Moves current binary to .backup
2. Installs new - Downloads and installs new version
3. Preserves permissions - Maintains executable permissions
4. Atomic operation - Uses rename for atomicity

Rollback

If upgrade fails, the backup remains:

# Backup location
~/.moon/bin/moon.backup

# Restore if needed
$ mv ~/.moon/bin/moon.backup ~/.moon/bin/moon

Examples

Basic upgrade

$ moon upgrade

Check current version

$ moon --version
moon 1.29.0

$ moon upgrade
▪▪▪▪ Upgrading moon to version 1.30.0...
ⓘ Upgraded moon to version 1.30.0!

$ moon --version
moon 1.30.0

Upgrade via proto

# If installed via proto
$ proto install moon latest --pin global

# Or let moon handle it
$ moon upgrade

CI/CD Usage

In CI, pin to specific versions instead:

# GitHub Actions
- name: Setup moon
  uses: moonrepo/setup-toolchain@v0
  with:
    version: 1.30.0

Or use proto:

- name: Install moon
  run: proto install moon 1.30.0

Automation

You can automate upgrades:

# Cron job (weekly)
0 0 * * 0 /Users/username/.moon/bin/moon upgrade

# Shell script
#!/bin/bash
moon upgrade && moon --version

Or use Dependabot/Renovate to track versions:

// .github/renovate.json
{
  "extends": ["config:base"],
  "regexManagers": [
    {
      "fileMatch": [".github/workflows/.*\\.yml$"],
      "matchStrings": [
        "moon: (?<currentValue>.*?)\\n"
      ],
      "datasourceTemplate": "github-releases",
      "depNameTemplate": "moonrepo/moon"
    }
  ]
}

Troubleshooting

Permission Denied

If you get permission errors:

# Fix permissions
$ chmod +x ~/.moon/bin/moon

# Try again
$ moon upgrade

Download Fails

If download fails:

1. Check internet connection
2. Verify firewall/proxy settings
3. Try manual download:
   curl -fsSL https://moonrepo.dev/install/moon.sh | bash
   

Unsupported Platform

If you see:

✗ Unsupported os (linux) + architecture (arm)

Your platform isn’t supported. Use:

• Docker containers
• Build from source
• Use a supported platform

Version Information

To check your current version:

$ moon --version
moon 1.29.0

# Or with full details
$ moon --version
moon 1.29.0
commit: a1b2c3d
built: 2024-01-15

Release Notes

View release notes at:

• GitHub Releases
• Changelog

Configuration

The upgrade process can be configured:

# .moon/toolchains.yml
moon:
  # Custom download URL
  downloadUrl: 'https://custom.registry/moon/{version}/{file}'
  
  # Custom manifest URL
  manifestUrl: 'https://custom.registry/moon/manifest.json'

See Also

• moon setup - Setup toolchains
• moon teardown - Teardown environment
• Installation - Install moon
• proto - Toolchain manager