upgrade - moon

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:

Checks for updates - Queries the latest version from the manifest
Downloads binary - Downloads the appropriate binary for your platform
Replaces executable - Safely replaces the running binary
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:

Renames current - Moves current binary to .backup
Installs new - Downloads and installs new version
Preserves permissions - Maintains executable permissions
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:

Check internet connection
Verify firewall/proxy settings

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:

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'

Overview

Core Commands

Project Management

Task Management

Code Generation

Utilities

Advanced

​How It Works

​Installation Requirements

​Installed via Official Script

​Installed in ~/.moon Directory

​Installed via proto

​Unsupported Installations

​System Package Managers

​Docker Containers

​Custom Installations

​Version Checking

​Already Latest

​Update Available

​Offline Mode

​Platform Support

​Linux

​macOS

​Windows

​Safety Features

​Self-Replacement

​Rollback

​Examples

​Basic upgrade

​Check current version

​Upgrade via proto

​CI/CD Usage

​Automation

​Troubleshooting

​Permission Denied

​Download Fails

​Unsupported Platform

​Version Information

​Release Notes

​Configuration

​See Also

Build docs developers (and LLMs) love