Manage your Paper or Spigot Minecraft server from the terminal.
CreeperCLI is a remote administration tool in two parts:
| Component | Location | What it does |
|---|---|---|
| Plugin (Java 21, Paper 1.21+) | plugin/ |
Runs inside the server. Owns authentication, the file sandbox, allowlisted console commands, monitoring, and live log streaming over a small TCP protocol. |
| CLI (Node.js 18+, no dependencies) | cli/ |
Installs from npm. Gives you an interactive shell, local-editor workflow, verified file transfers, live console stream, and monitoring dashboards. |
Both parts are required. The plugin does nothing without a client; the CLI is a client for this plugin.
- Sandboxed filesystem. Every path resolves inside the server root.
..escapes, symlink swaps, and absolute paths that leave the jail are rejected withE_PATH_ESCAPE. - Password plus TOTP 2FA. Bcrypt (cost 12) hashes, RFC 6238 one-time codes with QR setup, 15-minute session tokens bound to your IP.
- Brute-force defense. Per-IP login limiter (3 failures / 5 min) and fail2ban (3 failures, 10-minute ban).
- Console control without full access. Only allowlisted commands run:
list,say *,whitelist *,restartby default. Add your own patterns. - Full file toolset.
ls,cat,editin your local$EDITOR,grep,find,tree,cp,mv,rm,head,tail,wc. - Verified transfers.
cpush,cpull, andcsyncstream in 64 KB chunks and check SHA-256 on both ends. - Live monitoring.
statsfor CPU/RAM/disk,tps, atopdashboard, and a live console stream withlog --grep. - Accountability. Every action appends to an audit log with timestamp, source IP, user, and parameters.
- Drop
CreeperCLI-1.0.0.jarinto the server'splugins/folder and restart. First boot createsplugins/CreeperCLI/config.yml. - Create a user from the server console:
/creepercli user add steve <strong-password>. - Install the CLI on your computer:
npm install -g creepercli. - Connect:
creepercli login --host <server-ip> --port 45678. The CLI drops you into the interactive shell.
Full walkthrough: Getting started.
The plugin binds 0.0.0.0:45678 by default so hosted panels and containers work out of the box. That means the port is reachable from anywhere that can reach the machine.
- On a machine you control, set
network.host: "127.0.0.1"inplugins/CreeperCLI/config.ymland reach it through an SSH tunnel:ssh -N -L 45678:127.0.0.1:45678 user@server. - Run the server as a non-root OS user. CreeperCLI is a full admin channel.
- Enable 2FA with
creepercli totp setup. The limiter and fail2ban only slow attackers; 2FA stops credential theft.
The full threat model and hardening checklist is in Security.
The docs at demonz-development.github.io/creepercli are the single source of truth.
| Page | Covers |
|---|---|
| Getting started | Install, first user, first login, SSH tunnel |
| CLI commands | Every command, flag, and example |
| Console commands | /creepercli administration |
| Configuration | Every config.yml key, auto-migration |
| Security | Threat model, 2FA, sandbox, rate limits |
| Protocol | Wire format, actions, events, error codes |
| Plugin API | Extension API for Paper/Spigot developers |
| Architecture | Threading model, sandbox design, extensions |
| Advanced | Editing, sync, monitoring, scripting |
| Troubleshooting | Common errors, FAQ, tests |
Ready-to-post listings for Modrinth, SpigotMC, Hangar, CurseForge, npm, and GitHub Releases live in marketplace/.
- Plugin: JDK 21 and Maven.
mvn -B packageto build inplugin/;mvn testfor the PathSanitizer suite. - CLI: Node.js 18+.
npm installincli/;npm testfor tests.
SemVer with v* tags. The plugin builds and the CLI publishes to npm on tag. v1.0.0 is out on npm as creepercli. See CHANGELOG.md and CONTRIBUTING.md.
Apache License 2.0. See LICENSE.