Ferium

Check out ferium's sister projects ferinth and furse
They are Rust wrappers for the official Modrinth and CurseForge APIs respectively

Ferium is a fast and feature rich CLI program for downloading and updating Minecraft mods from Modrinth, CurseForge, and GitHub Releases, and modpacks from Modrinth and CurseForge. Simply specify the mods you use, and in just one command you can download the latest compatible version of all the mods you configured.

Features

• Use the CLI to easily automate your modding experience
• Download mods from multiple sources, namely Modrinth, CurseForge, and GitHub Releases
• Download modpacks from multiple sources, namely Modrinth and CurseForge

• Pleasing and beautiful UI

  • Listing mods
  • Listing mods verbosely
  • Upgrading mods/modpacks

Installation

Ferium builds from GitHub Releases do not require any external dependencies at runtime.
If you compile from source on Linux, using GCC to build will result in binaries that require GCC to be available at runtime.
On Linux, the regular version requires some sort of desktop environment that offers an XDG Desktop Portal to show folder pickers. The nogui versions do not need this as they won't have a GUI folder picker, making these variants suitable for server use.

Packages

Coming to more package managers soon

Arch User Repository for Arch Linux

Warning
From-source builds will install the Rust toolchain and GCC

| Installation method | GUI file dialogue | No GUI | | ----------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- | | Install pre-built binaries from GitHub Releases | ferium-gui-bin | ferium-bin | | Build from source at the latest tag | ferium-gui | ferium | | Build from source using the latest commit | ferium-gui-git | ferium-git |

Homebrew for macOS or Linux

bash brew install ferium

Scoop for Windows

bash scoop bucket add games scoop install ferium

Pacstall for Ubuntu

bash pacstall -I ferium-bin

Nixpkgs for NixOS or Linux

Note See package page for installation instructions

crates.io for the Rust toolchain

bash cargo install ferium

Warning
Remember to use an add-on like cargo-update to keep ferium updated to the latest version!

GitHub Releases

Warning
You will have to manually download and install every time there is a new update

1. Download the asset suitable for your operating system from the latest release
2. Unzip the file and move it to a folder in your path, e.g. ~/bin
3. Remember to check the releases page for any updates!

Overview / Help Page

Note
A lot of ferium's backend is in a separate project libium.
It deals with things such as the config, adding mod(pack)s, upgrading, file pickers, etc.

Config File Location

Ferium stores profile and modpack information in its config file. By default, this is located at ~/.config/ferium/config.json.
You can change this in 2 ways, setting the FERIUM_CONFIG_FILE environment variable, or setting the --config-file global flag. The flag always takes precedence.

You can also set a custom CurseForge API key or GitHub personal access token using the CURSEFORGE_API_KEY and GITHUB_TOKEN environment variables or the --curseforge_api_key and --github-token global flags respectively. Again, the flags take precedence.

First Startup

You can either have your own set of mods in what is called a 'profile', or install a modpack.

• Create a new profile by running ferium profile create and entering the details for your profile
  • Then, add your mods using ferium add
  • Finally, download your mods using ferium upgrade
• Add a modpack by running ferium modpack add <project_id>
  • After which, run ferium modpack upgrade to download and install the modpack

Adding Mods

• Modrinth
  • ferium add project_id
  • Where project_id is the slug or project ID of the mod
  • For example, Sodium has the slug sodium and project ID AANobbMI
  • You can find the slug in the website URL (modrinth.com/mod/<slug>), and the project ID at the bottom of the left sidebar under 'Technical information'
  • So to add Sodium, you can run ferium add sodium or ferium add AANobbMI
• CurseForge
  • ferium add project_id
  • Where project_id is the project ID of the mod
  • For example, Terralith has the project id 513688
  • You can find the project id at the top of the right sidebar under 'About Project'
  • So to add Terralith, you should run ferium add 513688
• GitHub
  • ferium add owner/name
  • Where owner is the username of the owner of the repository and name is the name of the repository (both case-insensitive)
  • For example Sodium's repository has the id CaffeineMC/sodium-fabric
  • You can find these at the top left part of the repository's page as a big 'owner / name'
  • So to add Sodium, you should run ferium add CaffeineMC/sodium-fabric (again, case-insensitive)
  • Note
    The GitHub repository has to release JAR files in their Releases for ferium to download, or else it will refuse to be added

External Mods

If you want to use files that are not downloadable by ferium, place them in the user folder in the output directory. Files here will be copied to the output directory when upgrading.

Warning
Profiles using the Quilt mod loader will not copy their user mods, this is because Quilt loads mods from nested directories (such as the user folder) for loader versions above 0.18.1-beta.3

Adding Modpacks

• Modrinth Modpacks
  • ferium modpack add project_id
  • Where project_id is the slug or project ID of the modpack
  • For example, Fabulously Optimized has the slug fabulously-optimized and project ID 1KVo5zza
  • You can find the slug in the website URL (modrinth.com/modpack/<slug>), and the project id at the bottom of the left sidebar under 'Technical information'
  • So to add Fabulously Optimized, you can run ferium modpack add fabulously-optimized or ferium modpack add 1KVo5zza
• CurseForge Modpacks
  • ferium modpack add project_id
  • Where project_id is the project ID of the modpack
  • For example, Fabulously Optimized has the project ID 396246
  • You can find the project ID at the top of the right sidebar under 'About Project'
  • So to add Fabulously Optimized, you should run ferium modpack add 396246

Upgrading Mods

Note
If your output directory is not empty when setting it, ferium will offer to create a backup. Please do so if it contains any files you would like to keep.

Now after adding all your mods, run ferium upgrade to download all of them to your output directory. This defaults to .minecraft/mods, where .minecraft is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory). You can choose to pick a custom output directory during profile creation or change it later.

If ferium fails to download a mod, it will print its name in red and give the reason. It will continue downloading the rest of the mods and will exit with an error.

Warning
When upgrading, any files not downloaded by ferium will be moved to the .old folder in the output directory

Upgrading Modpacks

Note
If your output directory's mods and resourcepacks are not empty when setting it, ferium will offer to create a backup. Please do so if it contains any files you would like to keep

Now after adding your modpack, run ferium modpack upgrade to download the modpack to your output directory. This defaults to .minecraft, which is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory). You can choose to pick a custom output directory when adding modpacks or change it later.

If ferium fails to download a mod, it will print its name in red and give the reason. It will continue downloading the rest of the mods and will exit with an error.

Warning
If you choose to install modpack overrides, your existing configs may be overwritten

Managing Mods

You can see all the mods in your current profile by running ferium list. If you want to see more information about them, you can run ferium list -v or ferium list --verbose.

You can remove any of your mods by running ferium remove, selecting the ones you would like to remove by using the space key, and pressing enter once you're done. You can also provide the names or IDs of the mods to remove as arguments.

Warning
Mod names with spaces have to be given in quotes (ferium remove "ok zoomer") or the spaces should be escaped (ferium remove ok\ zoomer).
Mod names and GitHub repository identifiers are case insensitive.

Check Overrides

If some mod is compatible with your profile but ferium does not download it, create an issue if you think it's a bug. You can disable the game version or mod loader checks by using the --dont-check-game-version and/or --dont-check-mod-loader flags when adding the mod, or manually setting check_game_version or check_mod_loader to false for the specific mod in the config file.

For example, Just Enough Items does not specify the mod loader for older minecraft versions such as 1.12.2. In this case, you would add JEI by running ferium add 238222 --dont-check-mod-loader so that the mod loader check is disabled. You can also manually disable the mod loader (and/or game version) check(s) in the config like so json { "name": "Just Enough Items (JEI)", "identifier": { "CurseForgeProject": 238222 }, "check_mod_loader": false }

Managing Modpacks

Add

When adding a modpack, you will configure the following:

• Output directory
  • This defaults to .minecraft, which is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory)
• Whether to install modpack overrides

You can also provide these settings as flags.

Ferium will automatically switch to the newly added modpack.

Configure

You can configure these same settings afterwards by running ferium modpack configure. Again, you can provide these settings as flags.

Manage

You can see all the modpacks you have configured by running ferium modpack list. Switch between your modpacks using ferium modpack switch. Delete a modpack by running ferium modpack delete and selecting the modpack you want to delete.

Profiles

Create

You can create a profile by running ferium profile create and configuring the following:

• Output directory
  • This defaults to .minecraft/mods where .minecraft is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory)
• Name of the profile
• Minecraft version
• Mod loader

You can also provide these settings as flags.

If you want to copy the mods from another profile, provide the --import flag. You can also directly provide the profile name to the flag if you don't want a profile picker to be shown.

Ferium will automatically switch to the newly created profile.

Configure

You can configure these same settings afterwards by running ferium profile configure. Again, you can provide these settings as flags.

Manage

You can see all the profiles you have by running ferium profile list. Switch between your profiles using ferium profile switch. Delete a profile by running ferium profile delete and selecting the profile you want to delete.

Feature Requests

If you would like to make a feature request, check the issue tracker to see if the feature has already been added or is planned. If not, create a new issue.

Building from Source or Working on ferium

Firstly you need the Rust toolchain, which includes cargo, rustup, etc. You can install these from the Rust website. You can manually run cargo commands, but I recommend just, a command runner that is basically a much better version of make.

To build the project and install it to your Cargo binary directory, clone the project and run just install. If you want to install it for testing purposes run just (alias to just install-dev), which builds in debug mode.

You can run integration tests using cargo test, linters using cargo clippy, and delete all build and test artefacts using just clean.

If you would like to see instructions for building for specific targets (e.g. Linux ARM), have a look at the workflow file. If you're still confused, create a discussion and I will help you out.