upgrade Command

Update your mods, Minecraft version, or mod loader to the latest versions.

📝 Synopsis

clicraft upgrade [mod] [options]

📖 Description

The upgrade command helps you keep your Minecraft instance up-to-date by upgrading:

Individual mods - Update a specific mod to its latest compatible version
All mods - Update all installed mods at once
Minecraft version - Upgrade to a newer Minecraft version
Mod loader - Update Fabric or Forge to a newer version

The command shows an interactive menu where you can choose what to upgrade.

🎯 Arguments

Argument	Description	Required
`[mod]`	Specific mod name to upgrade	No

If no mod is specified, shows an interactive upgrade menu.

🎯 Options

Option	Description	Default
`-i, --instance <path>`	Path to instance directory	Current directory
`-f, --force`	Force upgrade even if already up-to-date	false
`--verbose`	Enable verbose output	false

📋 Examples

cd my-instance
clicraft upgrade

Upgrade specific mod

clicraft upgrade sodium

Upgrade with instance path

clicraft upgrade --instance ./my-instance

Force upgrade

clicraft upgrade sodium --force

Forces upgrade even if the mod is already at the latest version.

Verbose upgrade

clicraft upgrade --verbose

See detailed information about version checks and downloads.

When you run clicraft upgrade without arguments, you’ll see:

$ clicraft upgrade

What would you like to upgrade?

❯ All mods
  Specific mod
  Minecraft version
  Mod loader (Fabric)
  Cancel

Options

1. All Mods

Updates all installed mods to their latest compatible versions:

Checking for mod updates...

Updates available:
  - Sodium: 0.5.0 → 0.6.0
  - Lithium: 0.11.0 → 0.12.0
  - Iris: 1.7.0 → 1.8.0

Proceed with updates? (y/n)

2. Specific Mod

Select a mod from your installed mods:

Select mod to upgrade:

❯ Sodium (0.5.0)
  Lithium (0.11.0)
  Iris (1.7.0)
  Fabric API (0.95.0)
  Mod Menu (8.0.0)

3. Minecraft Version

Upgrade to a different Minecraft version:

Current version: 1.20.1
Available versions:

❯ 1.21.1 (Latest Release)
  1.21
  1.20.6
  1.20.4
  Keep current version

Warning: Upgrading Minecraft may break mod compatibility.

4. Mod Loader

Update the mod loader version:

Current: Fabric 0.15.0
Available:

❯ 0.16.5 (Latest)
  0.16.0
  0.15.11
  Keep current version

🎮 Example Sessions

Upgrade All Mods

$ cd my-instance
$ clicraft upgrade

What would you like to upgrade? All mods

Checking for mod updates...

Updates available (3):
  - Sodium: 0.5.0 → 0.6.0
  - Lithium: 0.11.0 → 0.12.0
  - Iris: 1.7.0 → 1.8.0

No updates available (2):
  - Fabric API: 0.100.0 (latest)
  - Mod Menu: 9.0.0 (latest)

Proceed with updates? (y/n) y

✓ Downloading Sodium 0.6.0...
✓ Downloading Lithium 0.12.0...
✓ Downloading Iris 1.8.0...
✓ Removing old versions...
✓ Installing new versions...

Successfully upgraded 3 mods!

Upgrade Specific Mod

$ clicraft upgrade sodium

Checking for Sodium updates...

Current version: 0.5.0
Latest version:  0.6.0

Changelog:
  - Improved rendering performance
  - Fixed memory leak
  - Updated for Minecraft 1.21.1

Upgrade to 0.6.0? (y/n) y

✓ Downloading Sodium 0.6.0...
✓ Installing...
✓ Cleaning up...

Sodium upgraded successfully!
Old version removed: sodium-fabric-0.5.0.jar
New version installed: sodium-fabric-0.6.0.jar

No Updates Available

$ clicraft upgrade

Checking for mod updates...

All mods are up-to-date!
  - Sodium: 0.6.0 (latest)
  - Lithium: 0.12.0 (latest)
  - Iris: 1.8.0 (latest)

No updates available.

🔍 How It Works

Version Detection

Reads your current Minecraft version and loader from mcconfig.json
Scans installed mods in mods/ directory
Queries Modrinth API for latest compatible versions
Compares versions and shows available updates

Compatibility Checking

Ensures updates are compatible with:

Your Minecraft version
Your mod loader (Fabric/Forge)
Other installed mods (dependency checking)

Safe Upgrade Process

Downloads new version first
Verifies download integrity
Backs up old version (temporarily)
Installs new version
Removes old version
Updates instance configuration

🎯 Use Cases

Monthly Maintenance

# Check for updates regularly
cd my-instance
clicraft upgrade
# Select "All mods"

After Minecraft Update

# Upgrade Minecraft first
clicraft upgrade
# Select "Minecraft version"

# Then update mods for new version
clicraft upgrade
# Select "All mods"

Fix Mod Issues

# Force reinstall problematic mod
clicraft upgrade sodium --force

Keep Loader Updated

# Update Fabric/Forge
clicraft upgrade
# Select "Mod loader"

Selective Updates

# Update only specific mods
clicraft upgrade sodium
clicraft upgrade lithium
# Leave other mods as-is

⚙️ Version Management

Semantic Versioning

Mods typically use semantic versioning: MAJOR.MINOR.PATCH

Patch (0.5.0 → 0.5.1): Bug fixes, safe to upgrade
Minor (0.5.0 → 0.6.0): New features, usually safe
Major (0.5.0 → 1.0.0): Breaking changes, test carefully

Version Compatibility

# Check compatibility before upgrading
clicraft info --verbose
# Note Minecraft and loader versions

clicraft upgrade
# Upgrades respect compatibility

📋 Backup Recommendations

Before upgrading, backup your instance:

# Create backup
cd ..
tar -czf my-instance-backup.tar.gz my-instance/

# Then upgrade
cd my-instance
clicraft upgrade

Or backup just your worlds:

cd my-instance
tar -czf saves-backup.tar.gz saves/

⚠️ Common Issues

“No updates available”

All mods are already at latest versions:

This is good! Nothing to do.
Use --force to reinstall anyway

“Incompatible version”

The latest mod version doesn’t support your Minecraft version:

Upgrade Minecraft first
Or wait for mod to be updated
Or use an older Minecraft version

“Download failed”

Network or Modrinth issues:

Check internet connection
Try again later
Check Modrinth status

“Mod not found”

The mod isn’t in your instance:

# Check installed mods
clicraft info

# Install it first
clicraft install sodium

Broken After Upgrade

If the game doesn’t work after upgrading:

# Restore from backup
cd ..
rm -rf my-instance
tar -xzf my-instance-backup.tar.gz

# Or reinstall problematic mod
cd my-instance
rm mods/problematic-mod*.jar
clicraft install problematic-mod

💡 Best Practices

1. Check Before Upgrading

clicraft info
clicraft upgrade  # Just to see what's available
# Exit without upgrading to review

2. Read Changelogs

Review what changed before upgrading:

Look at mod pages on Modrinth
Check for breaking changes
Read about new features

3. Upgrade Gradually

Don’t upgrade everything at once:

# Upgrade one mod
clicraft upgrade sodium

# Test the game
clicraft launch

# If OK, upgrade another
clicraft upgrade lithium

4. Test After Upgrades

# After upgrading
clicraft upgrade

# Test launch
clicraft launch --offline

# Check everything works
# Then play normally

5. Keep Loader Updated

Update your mod loader regularly:

# Every few weeks
clicraft upgrade
# Select "Mod loader"

🔄 Downgrading

To downgrade a mod, manually remove and reinstall:

# Remove current version
rm mods/sodium-*.jar

# Install older version
# (manually download from Modrinth)
# or wait for clicraft downgrade support

📊 Update Frequency

How often to run upgrades:

Performance mods: Check weekly (often updated)
Stable mods: Check monthly
Mod loader: Check bi-weekly
Minecraft: Upgrade when stable versions release

🎮 Minecraft Version Upgrades

Careful Upgrading

Upgrading Minecraft version can break mods:

# Before upgrading Minecraft
clicraft info --verbose > pre-upgrade-info.txt

# Upgrade Minecraft
clicraft upgrade
# Select "Minecraft version"

# Test each mod
clicraft launch --offline

# Some mods may not work - reinstall
clicraft upgrade  # To get compatible versions

Rolling Back

If Minecraft upgrade breaks things:

Restore from backup
Or manually edit mcconfig.json:

{
  "minecraftVersion": "1.20.1"  // Change back
}

Then reinstall mods for old version.

clicraft install - Install mods before upgrading
clicraft info - Check current versions
clicraft search - Find mods to upgrade to
clicraft create - Instance with specific versions

🔍 Version Checking

Check versions without upgrading:

# Current versions
clicraft info

# Available versions (via search)
clicraft search sodium --version 1.21.1

🆘 Troubleshooting

Upgrade Stuck

If upgrade hangs:

Press Ctrl+C to cancel
Check network connection
Try again with --verbose

Partial Upgrade

If some mods upgrade but others fail:

Check clicraft info to see what upgraded
Try upgrading failed mods individually
Use --verbose to see errors

Game Won’t Launch After Upgrade

Check logs: cat logs/latest.log
Check mod compatibility
Restore from backup
Downgrade problematic mods

🔗 See Also

← Back to Commands