Catalog

Catalog analyses your plugins folder once the server boots, figuring out which Modrinth plugin each .jar belongs to. Every jar is identified by its hash, so a renamed file is still recognized and nothing has to be mapped by hand. Then you will get your updates in chat and be able to search, install and remove plugins with a click. Every plugin that Catalog does not recognize is left untouched.

Requirements

Paper 1.18.2 and newer, Purpur and Folia included. Java 17 and newer. If either one is missing, Catalog disables itself during startup and prints the reason in the console.

Plugins have to be published on Modrinth to be managed. Custom jars and plugins from other marketplaces keep working as usual, Catalog only ignores them. If you install a plugin that is available on modrinth it will be recognized.

Setup

Download the jar from Modrinth and drop it into your plugins folder. On the first start Catalog scans what you already have and matches it against Modrinth. /catalog list will show all of the recognized plugins and their updates.

Installation

You can search Modrinth without leaving the game. /catalog search <query> gives you the plugins that run on your server, and clicking a result opens its page with the description, author, downloads and what the plugin needs to work.

Installing is one click from there. The .jar goes into your plugins folder and the plugin starts working after the next restart. If the build needs a plugin you do not have, Catalog says which one and offers to bring it along.

Only builds made for your exact Minecraft version are offered. Purpur and Folia builds are recognized separately from plain Paper ones, so if a plugin ships both a Paper and a Purpur build, the Purpur one gets installed on a Purpur server.

/catalog install <plugin> <version> puts a plugin on any other build you want.

Updates

Catalog looks for updates when the server starts and every three hours after that. /catalog list shows what is out of date, and /catalog update <plugin> or /catalog update all fetches the new builds.

Nothing is ever swapped while the plugin runs. Catalog downloads the new build and gives it to the server, which installs it automatically once the next restart happens, before plugins load. /catalog cancel <plugin> drops a downloaded update.

Catalog can automatically handle updates for plugins you trust. Once you enable automatic updates for a plugin, it will stay up-to-date. Catalog waits a couple of hours after a build comes out before installing it. If the author notices a problem and puts out a fix in that time, you get the fixed build and never install the broken one. The pause time, the channel a plugin follows and the auto-update switch are set per each plugin, so you can choose which plugins you want updated immediately and which ones can wait. If an update introduces new dependencies it won't auto update that version until you install the missing dependencies.

Staff with catalog.notify get a summary when they join: updates that did not enable, what the last restart applied, what did not apply, which automatic updates failed and why, and what is waiting. notify_on_join in the config turns it off.

Each downloaded file is being validated before being added to your plugin folder: the right file is expected, the right size is expected and it is being made for the Java version you can use on your server. Anything that does not pass this check will be deleted instead of being placed into your plugin folder.

Files on Modrinth without a hash or with an unsafe file name are refused.

Broken builds

After a restart, Catalog checks that every plugin it installed or updated is enabled. A plugin that isn't loaded or was disabled in startup is reported in the join summary. From there, you can also hit a button to roll back the update, and it will also turn auto-updates off so it won't install the broken build again. Nothing is rolled back automatically.

Uninstallation

Uninstalled plugins are moved to a separate "trash" folder instead of being deleted. Removing one gives you an Undo, and /catalog trash lists everything you have taken out so you can put any of it back. Taking out a plugin that another one depends on asks first. Removals are deleted after 30 days, which you can change or turn off in the config.

History

/catalog history lists what Catalog has done to your server: every install, update, removal and restore, when it happened and who asked for it.

It also records what went wrong and why: automatic updates that were blocked or failed, downloaded updates a restart did not apply, and downloaded updates removed before a restart. /catalog history --event failed shows only those.

Commands

Everything is clickable, so you rarely need to type any command. /catalog help lists all commands. The command also answers to /ctlg, /cata, /ctl and /clg.

Command		Permission
/catalog	Version and credits	catalog.command.about
/catalog help	All commands	catalog.command.help
/catalog list [--updates] [--restart] [--held] [--untracked]	All plugins managed by Catalog, and what needs updating	catalog.command.list
/catalog info <plugin>	All available information about any plugin, whether installed or not	catalog.command.info
/catalog search <query>	Searches Modrinth for plugins compatible with your server	catalog.command.search
/catalog versions <plugin>	Newest release, beta and alpha	catalog.command.info
/catalog dependencies <plugin> [version]	What a plugin declares it needs, optionally for a specific build	catalog.command.info
/catalog history [--plugin <plugin>] [--author <name>] [--event <kind>]	What Catalog has done, and who asked	catalog.command.list
/catalog install <slug> [version]	Install a plugin, optionally a specific build	catalog.command.install
/catalog update <plugin|all>	Download updates, apply them on next restart	catalog.command.update
/catalog cancel <plugin>	Drop a downloaded update	catalog.command.update
/catalog uninstall <plugin>	Move a plugin to trash	catalog.command.uninstall
/catalog untrack <plugin>	Stop managing a plugin, the jar is not removed	catalog.command.untrack
/catalog track <jar>	Manage an untracked plugin again	catalog.command.untrack
/catalog trash	What you have removed	catalog.command.trash
/catalog trash restore <plugin>	Put a removed plugin back	catalog.command.trash
/catalog trash delete <plugin|all>	Delete a removal permanently	catalog.command.trash
/catalog settings <plugin>	Set channels, enable auto-updates, set holds	catalog.command.settings
/catalog reload	Reload config	catalog.command.reload

The settings screen sets everything below by clicking, but these also work as commands, which is what you need from the console.

Command		Permission
/catalog channel <plugin> <channel>	Follow release, beta or alpha	catalog.command.channel
/catalog auto <plugin> <on|off>	Update this plugin automatically	catalog.command.settings
/catalog soak <plugin> <window>	How long to wait before an automatic update, like 30m, 2h or default	catalog.command.settings
/catalog hold <plugin>	Keep the current version and stop offering updates	catalog.command.hold
/catalog unhold <plugin>	Allow updates again	catalog.command.hold

Permissions

Permissions are listed above next to each action/command.

Node
catalog.admin	Everything
catalog.*	Everything
catalog.command.<name>	A single command/action
catalog.notify	The update summary on join

Configuration

plugins/Catalog/config.yml is short and commented. What most people change is the defaults applied to newly tracked plugins, meaning their release channel, whether they update automatically and how long to wait before doing that, then how often updates are checked and how long the trash keeps removals. A Modrinth token is optional: it raises the request limit and allows private projects to be read.

Questions

Does it reload or hot-swap plugins? No. Catalog does not touch plugins while the server is running, which is what prevents classloader leaks and locked files. Builds are downloaded and the server applies them at the next restart, before the plugins load.

What about plugins that are not on Modrinth? They are ignored. Catalog never does anything to them.

Can it install something my server cannot run? Only with allow_incompatible_installs turned on in the config. Otherwise builds are filtered by your Minecraft version and server platform, and every download is checked against the Java version your server runs.

Does it phone home? It talks to the Modrinth API, and reports anonymous server statistics to bStats, which you can turn off in the bStats config.

Made by Vulpine