Launch and control an isolated Minecraft Java client from the command line.
| Directory | Purpose |
|---|---|
| cli | The @mizius/minecraft package installs and controls managed game instances. |
| mod | The Fabric client mod receives local commands and performs game actions. |
| skills | The agent skill explains the CLI workflow. The package bundles a copy. |
Install Node.js 22 or newer on Windows x64. Download minecraft.tgz from the latest GitHub release, then install it from the download directory.
npm install --global ./minecraft.tgz
minecraft launch --json
minecraft control state --jsonThe first launch downloads the required game files. The client uses an offline profile. Authenticated multiplayer servers and Realms require a signed-in account.
Run minecraft update to install the latest stable CLI release. The CLI also checks for updates before starting each new client and resumes the launch after an update.
Use the CLI commands to inspect and control the game.
minecraft control screenshot --output .\screen.png
minecraft control record start --json
minecraft control record stop --json
minecraft control key W --action hold
minecraft control key W --action release
minecraft control click 640 360 --button leftThe default window stays visible without taking foreground focus. Use --foreground to give it focus when it starts. The client listens for commands only on loopback.
The mod and CLI package use the shared version in project.properties. Update its version property to change both versions.
Build the mod from its directory.
cd mod
.\gradlew.bat assembleBuild the CLI from its directory.
cd cli
npm ci
npm run buildnpm pack builds the CLI and mod, bundles the compiled mod, compatibility metadata, and skill, then creates the package archive.
The release.yml workflow runs on pushes to main and can also run manually on main. It compares the stable version in project.properties with the latest GitHub release. If the version is newer, or no release exists, it builds and publishes a release tagged v<version> with the packaged minecraft.tgz attached. Otherwise it skips the build.
See the CLI release instructions for version updates and release permissions. Publishing and installing public releases do not require an npm account.