MineCLI is a command-line tool for Minecraft server administrators. Its goal is to install, update, list, edit, and remove server-side mods, datapacks, and plugins across multiple Minecraft server types.
The CLI is designed to be package-source agnostic. Modrinth is the first implemented source for discovery and version metadata, but commands should stay generic enough to support local files, folders, and other registries later.
This repository is in Phase 4: polish and distribution for production testing.
The current executable supports:
Install from the GitHub release:
curl -fsSL https://raw.githubusercontent.com/vincentsaluzzo/mine-cli/main/scripts/install-release.sh | shInstall globally with Cargo from Git:
cargo install --git https://github.com/vincentsaluzzo/mine-cli minecliOnce MineCLI is published to crates.io, installation will become:
cargo install mineclicargo run -- --help
cargo run -- --version
cargo run -- --path /srv/minecraft/survival init --type fabric --minecraft 1.21.5
cargo run -- --path /srv/minecraft/survival init
cargo run -- --path /srv/minecraft/survival search fabric-api --kind mod
cargo run -- --path /srv/minecraft/survival search minimap --all-sides
cargo run -- --path /srv/minecraft/survival --dry-run install fabric-api --kind mod
cargo run -- --path /srv/minecraft/survival install --file ./mods/example.jar --kind mod
cargo run -- --path /srv/minecraft/survival install --folder ./mods-to-install --kind mod
cargo run -- --path /srv/minecraft/survival import --dry-run
cargo run -- --path /srv/minecraft/survival export --output survival.minecli.toml
cargo run -- --path /srv/minecraft/staging restore survival.minecli.toml
cargo run -- --path /srv/minecraft/staging sync /srv/minecraft/survival
cargo run -- --path /srv/minecraft/survival modpack inspect ./pack.mrpack
cargo run -- --path /srv/minecraft/survival --dry-run modpack install ./pack.mrpack
cargo run -- --path /srv/minecraft/survival datapacks list
cargo run -- --path /srv/minecraft/survival datapacks disable example-pack
cargo run -- --path /srv/minecraft/survival datapacks enable example-pack
cargo run -- --path /srv/minecraft/survival list
cargo run -- --path /srv/minecraft/survival outdated
cargo run -- --path /srv/minecraft/survival --dry-run update --all
cargo run -- --path /srv/minecraft/survival update fabric-api
cargo run -- --path /srv/minecraft/survival backups list
cargo run -- --path /srv/minecraft/survival rollback <operation-id>
cargo run -- --path /srv/minecraft/survival edit
cargo run -- --path /srv/minecraft/survival status
cargo run -- --path /srv/minecraft/survival doctor --fix
cargo run -- servers add survival /srv/minecraft/survival
cargo run -- --server survival statusMineCLI stores per-server state in .minecli/ inside the server folder:
.minecli/
server.toml
lock.toml
history.log
backups/
MineCLI can initialize directly from standard Minecraft server folders and from the Docker volume layout used by TheRemote/Legendary-Minecraft-Purpur-Geyser.
For that image, MineCLI detects:
purpur.jarandpurpur.ymlas a Purpur serverversion_history.json,versions/, andcache/as version hintsserver.propertieslevel-namefor the world/datapack pathplugins/as the plugin target
Example:
cargo run -- --path /path/to/docker/volume/_data init --name survivalThe implementation roadmap is tracked in:
- docs/GETTING_STARTED.md
- docs/SUPPORTED_SERVERS.md
- docs/SAFETY.md
- docs/MODRINTH.md
- docs/PACKAGING.md
- PROJECT_PLAN.md
- TASKS.md
- docs/SOURCES.md
MineCLI can remember server folders globally:
cargo run -- servers add survival /srv/minecraft/survival
cargo run -- servers list
cargo run -- servers show survival
cargo run -- --server survival status
cargo run -- servers remove survivalBy default the registry is stored in the platform config directory as servers.toml. Use --config <path> or MINECLI_CONFIG_DIR to override the config directory.
Registry installs are not the only supported source. You can also install local files and folders:
cargo run -- --server survival install --file ./voicechat.jar --kind plugin
cargo run -- --server survival install --folder ./mods-to-install --kind mod
cargo run -- --server survival install --file ./datapack.zip --kind datapackLocal installs are copied into the server's configured mods, plugins, or datapacks directory and tracked in .minecli/lock.toml with SHA-512/SHA-1 hashes.
When a package source reports a broad project type, MineCLI tries to infer the right install kind from versions compatible with the current server. For example, a project listed as a mod can still install as a Paper/Purpur plugin when a compatible plugin artifact exists.
Existing server folders can be imported into MineCLI. Files are matched to source metadata by hash when possible; unmatched files stay unmanaged and visible in status.
cargo run -- --server survival import --dry-run
cargo run -- --server survival importMineCLI can also export a portable manifest, restore registry-backed packages into another server, or sync another local server's manifest and local files:
cargo run -- --server survival export --output survival.minecli.toml
cargo run -- --path /srv/minecraft/staging restore survival.minecli.toml
cargo run -- --path /srv/minecraft/staging sync /srv/minecraft/survivalLocal file and folder installs are copied during sync when the source server folder is available. Plain manifest restore skips non-portable local packages.
MineCLI can inspect and install the required server-side files from Modrinth .mrpack files:
cargo run -- --server survival modpack inspect ./pack.mrpack
cargo run -- --server survival --dry-run modpack install ./pack.mrpack
cargo run -- --server survival modpack install ./pack.mrpackClient-only packs are rejected. Optional server files are listed but skipped for now, and overrides/ plus server-overrides/ files are copied during install.
MineCLI can inspect and toggle datapacks without editing level.dat:
cargo run -- --server survival datapacks list
cargo run -- --server survival datapacks disable example-pack
cargo run -- --server survival datapacks enable example-packDisabled datapacks are moved to .minecli/datapacks-disabled/. If a datapack is tracked in lock.toml, MineCLI updates the tracked path when it is enabled or disabled.
Registry-backed installs can be checked and updated against the latest compatible release for the server's Minecraft version and loader:
cargo run -- --server survival outdated
cargo run -- --server survival outdated --changelog
cargo run -- --server survival --dry-run update --all
cargo run -- --server survival update fabric-apiLocal file and folder installs are tracked in the lockfile but intentionally skipped by update commands.
Update and remove operations create file backups before replacing or deleting tracked files:
cargo run -- --server survival backups list
cargo run -- --server survival rollback <operation-id>Backups are stored under .minecli/backups/ with metadata that lets rollback restore both files and lockfile entries.
cargo run -- --server survival edit
cargo run -- --server survival doctor
cargo run -- --server survival doctor --fixedit opens .minecli/server.toml in $VISUAL or $EDITOR and validates the result. doctor --fix applies safe local fixes such as creating missing content directories and removing stale lockfile entries.
Required tooling:
- Rust 1.85 or newer
- Cargo
Common commands:
make fmt
make lint
make testEquivalent Cargo commands:
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo testProduction-oriented commands:
make release
make checksums
make completionsLive integration tests are ignored by default because they download real Fabric, Purpur, Forge, and NeoForge server artifacts and install packages from external sources:
cargo test --test live_server_flows -- --ignored --nocaptureUse --nocapture to see each downloaded artifact, detected server type, install target, lockfile listing, and cleanup check.
MineCLI is distributed under the MIT license. See LICENSE.