Overview

pluggy is a single-binary toolchain for Minecraft plugin development. Scaffold a project, install dependencies from Modrinth, Maven, local jars, or sibling workspaces, build a real plugin jar, and boot a live Paper, Spigot, Velocity, or Sponge server that rebuilds when you save.

No global JVM toolchain, no Gradle wrapper, no pom.xml. One project.json per project.

Start here

If you have never used pluggy before, read these in order. The first page is enough to get a plugin running.

Getting started: install, scaffold, build, and run a dev server. Eight minutes from zero to a live server.
Glossary: plain-English definitions for every term in these docs. Bookmark it.
project.json reference: every field, every form, and the validation rules.
Dependency sources: the Modrinth, Maven, file, and workspace grammar.

Commands

Every subcommand, with its flags, JSON envelope, and sample output.

Command	Summary
`init`	Scaffold a new project in an empty directory.
`install`	Add a dependency or refresh the lockfile.
`remove`	Drop a dependency and (optionally) its cached jar.
`info`	Inspect a Modrinth, Maven, file, or workspace source.
`search`	Search Modrinth by keyword.
`list`	Print declared deps, resolved versions, and registries.
`why`	Trace which top-level dep pulled in a transitive.
`outdated`	List locked deps with a newer upstream version.
`audit`	Verify cached jars against the lockfile hashes.
`build`	Compile, copy resources, write the descriptor, jar.
`test`	Compile and run JUnit Platform tests under `test/`.
`docs`	Generate Javadoc HTML against the resolved classpath.
`dev`	Boot a live server with the plugin and its runtime deps.
`sdk`	Manage the JDKs pluggy provisions for builds.
`cache`	Inspect and prune the download cache.
`doctor`	Check the environment and every workspace.
`upgrade`	Replace the running binary with the latest release.
`completions`	Print a shell completion script.

Deeper topics

These pages explain how pluggy works once you’ve outgrown the tutorial. They assume you’ve shipped at least one plugin.

Build pipeline: what happens between pluggy build and the output jar. Maven dependency resolution, SNAPSHOT handling, classpath construction, descriptor generation.
Dev server: the dev/ staging directory, runtime vs compile-time plugin detection, EULA handling, --reload vs restart, shutdown semantics.
Workspaces: monorepo layout, inheritance rules, the workspace: source kind, topological build order.
IDE integration: what ide: "vscode" | "eclipse" | "intellij" writes and where.
Cross-platform notes: install paths, cache paths, line endings, signal handling.
Troubleshooting: common failures, the error messages the code actually prints, and what to do about them.

Recipes

Task-oriented walkthroughs for situations that come up often. Each recipe stands alone; pick the one that matches what you’re trying to do.

Reading these docs

Path examples use POSIX form (~/Library/Caches/pluggy/...). When the Windows path differs in a way that matters, the difference is called out inline.

pluggy reads one file (project.json) and writes one lockfile (pluggy.lock). Everything else, the cache, the build staging directory, the dev/ server directory, is derived from those two.

If a term feels unfamiliar, check the glossary first.