⠀

A CLI featuring all MCPanel features, but as a CLI. Runs on Windows, macOS, and Linux with no native dependencies beyond Python and Java.

Note: MCPanel-CLI and all MCPanel related repositorys will be at MCPanel-Studios soon!

Three faces to the same engine:

Surface	How to use	Output
Human commands	mcpanel create server -t "test" -sw paper -v 1.21.1	pretty, colourised
API commands	mcpanel api fetch server -id srv_123	raw JSON on stdout
Interactive TUI	mcpanel cli	full REPL with tab completion + guided wizards

---

Install

Dependencies: Python 3.8+ · prompt_toolkit (auto-installed) · Java (to run Minecraft servers)

Linux / macOS

./install.sh           # symlink bin/mcpanel into ~/.local/bin (no build needed)
./install.sh --pip     # pip install --user .  (proper console-script entry)
./install.sh --uninstall

Windows (PowerShell)

.\install.ps1          # pip install --user (recommended)
.\install.ps1 -Uninstall

No install required - run straight from the checkout:

# Linux / macOS
./bin/mcpanel --help
python3 -m mcpanel --help

# Windows
python bin\mcpanel --help
python -m mcpanel --help

Data directory (same location the desktop app uses):

Platform	Path
Windows	%APPDATA%\mcpanel\
macOS	~/Library/Application Support/mcpanel/
Linux	~/.config/mcpanel/

Override with the MCPANEL_HOME environment variable.

---

Interactive TUI (mcpanel cli)

mcpanel › /create server

• Commands start with / - /create server, /list servers, /start server, …
• Tab completion - completes command names, nouns, flag names, server IDs, software names, and plugin platforms, with a usage hint shown inline for each match
• Live usage tooltip - the bottom toolbar updates as you type, showing the full syntax for the current command
• Guided wizards - enter a command without arguments and you get prompted for each one interactively (name, software picker, version picker, RAM, port, EULA)
• Arrow-key pickers - selecting a server, software, version, platform, or backup shows a scrollable inline list; ↑↓ to navigate, Enter to confirm, Esc to cancel
• Command history - ↑↓ recalls previous commands
• /exit - leave the TUI and return to the terminal (servers keep running in the background)
• /shutdown - kill all running servers then exit
• /search plugins|mods, /install plugin|mod, /info plugin - browse Modrinth / Hangar / SpigotMC and install without leaving the TUI; omit the platform or the target server and you get a picker. The plugins/mods word is optional, so /search modrinth luckperms works too
• /proxy info|link - inspect or extend a Velocity proxy; the proxy list is filtered to Velocity servers and the link list to Paper-based ones
• /backup create|list|delete|restore and /buildtools version|update - same features as the command-line, with guided pickers for server/backup selection
• /discover - re-scan servers/ for folders dropped in since the TUI started (the one-shot CLI already does this on every startup)

Every command in the reference below is available inside the TUI except the scripting-oriented ones (fetch, api, completion, debug).

mcpanel › /create server
  Select software:
  ❯ paper
    purpur
    velocity
    ...
  ↑↓ navigate   Enter select   Esc cancel

mcpanel › /search plugins modrinth luckperms
NAME                         AUTHOR             DOWNLOADS   UPDATED      VERSION
LuckPerms                    lucko              2.3M        2026-06-18   MBSY8toc
  A permissions plugin/mod for Minecraft servers.

Install: /install plugin <platform> <slug> -id <serverid>

mcpanel › /install plugin modrinth luckperms
  Select server to install the plugin into:
  ❯ srv_1700000000000  survival

Type /help inside the TUI for the full command list.

---

Quick start (command-line)

# Create a Paper 1.21.1 server with 20 GB RAM and accept the EULA
mcpanel create server -t "my server" -ram 20480 -sw paper -v 1.21.1 --accept-eula

# List servers, then start one
mcpanel list servers
mcpanel start server -id srv_1700000000000

# Watch the live console (Ctrl-C to detach)
mcpanel console server -id srv_1700000000000

# Send a console command
mcpanel cmd server -id srv_1700000000000 -c "say hello"

# Check who's online via server-list-ping
mcpanel ping server -id srv_1700000000000

# Stop gracefully
mcpanel stop server -id srv_1700000000000

-ram takes plain megabytes (20480) or a suffixed value (20G).

---

Command reference

Servers

Command	What it does
create server -t <name> -sw <software> -v <version> [-ram <MB|nG>] [-port <n>] [-profile <id>] [-java <path>] [-jargs "<args>"] [-storage <limit>] [--unstable] [-dest <folder>] [--accept-eula]	Create + download a server. -dest puts it in <folder>/<name> (any drive or mount) instead of MCPanel's servers folder
list servers	List all servers + online status
info server -id <id>	Full server details
update server -id <id> [-t -ram -port -sw -v -java -jargs -storage]	Change settings (port rewrites server.properties)
delete server -id <id> [--keep-files]	Delete the server and its files (a linked server's original folder too). --keep-files only removes it from MCPanel's list and leaves the folder alone - the panels' Remove button
duplicate server -id <id> -t <newName> [-v <version>] [-dest <folder>] [--unstable] (alias clone)	Copy a server. -v switches the copy to another version of the same software (new jar, files copied as-is); -dest as for create server
import server -path <folder> [-t <name>] [--link] [-port -ram -sw -v -java -jargs]	Adopt any existing server folder - no MCPanel config needed; software, version, port and RAM are detected. --link uses the folder in place instead of copying it
start | stop | restart | kill server -id <id>	Lifecycle (start/restart accept --accept-eula)
cmd server -id <id> -c "<command>"	Send a console command
logs server -id <id> [-f] [-n <N>] / console server -id <id>	View / follow console output
sessions server -id <id>	List archived log sessions
fetch logfiles -id <id>	List the server's own log files (logs/: latest.log + archives)
fetch logfile -id <id> [-file <name>]	Read one of them (default latest.log; .gz archives too; last 10k lines)
upload-log -id <id> [-file <name>]	Upload a log file to mclo.gs and print the link. Over 10k lines / 25 MB, the oldest lines are cut off
ping server -id <id> (or -host <h> -port <p>)	Server-list-ping
files server -id <id>	File tree
stats server -id <id>	Disk usage, plus the running server's CPU % and RAM
accept-eula server -id <id>	Write eula=true
scan server -path <folder>	Detect port/software before importing
open server -id <id>	Open folder in file manager

Proxy (Velocity)

Command	What it does
proxy info --velocity-id <id>	List servers registered in a Velocity proxy config
proxy link -id <id> --velocity-id <id> [--server-name <name>] [--priority <pos>] [--custom-ip <ip:port>]	Link a Paper-based server (Paper, Purpur, Folia, Leaf) into a Velocity proxy (writes paper-global.yml + velocity.toml; rolled back on failure)

Profiles (server presets)

Command	What it does
create profile -t <name> [-desc <text>] [-sw <a,b>] [-versions <a,b>]	Create a blank profile
create profile-from-server -id <id> -t <name> -paths <rel,paths> [-desc <text>] [-sw <sw>] [-versions <ver>]	Snapshot files from a running server into a new profile
list profiles	List all profiles
info profile -id <id>	Show profile details
delete profile -id <id>	Delete a profile
import profile -path <folder> -t <name> [-desc <text>] [-sw <sw>] [-versions <ver>]	Import an existing profile folder
scan profile -path <folder>	Read metadata from a profile folder
open profile -id <id>	Open profile folder in file manager

mcpanel create profile -t "Survival" -desc "essentials" -sw paper,purpur
# then drop plugins/, config/, server.properties into the printed folder

mcpanel create profile-from-server -id srv_1700000000000 -t "my preset" -paths "plugins,config"

Versions

mcpanel versions -sw paper            # paper|purpur|velocity|fabric|vanilla|leaf|folia|spigot
mcpanel versions -sw vanilla --prerelease
mcpanel versions -sw paper --unstable

Sources: PaperMC API (paper/folia/velocity), Purpur API, Mojang manifest (vanilla), FabricMC meta, GitHub releases (leaf). Spigot's version list is fetched live from hub.spigotmc.org/versions/ (the same metadata directory BuildTools itself reads).

Plugins & mods

Command	What it does
search plugins | mods <modrinth|hangar|spigotmc> [query] [-id <serverid>] [-v <MC version>] [-sw <software>] [-n <limit>] [-o <offset>]	Search a platform for plugins/mods
install plugin | mod <modrinth|hangar|spigotmc> <slug> -id <serverid> [-v <MC version>] [--owner <owner>] [--version <version>]	Download + drop a plugin/mod into a server's plugins//mods/ folder (or --profile-id <id> to install into a profile instead)
info plugin <modrinth|hangar|spigotmc> <slug> [--owner <owner>]	Version history + website link for a plugin/mod

mcpanel search plugins modrinth luckperms -id srv_1700000000000
mcpanel install plugin modrinth luckperms -id srv_1700000000000
mcpanel install mod hangar someproject --owner someowner -id srv_1700000000000

-id/-v auto-detect the target Minecraft version from the server so results are pre-filtered to what's actually compatible. Hangar projects need --owner whenever the slug alone is ambiguous. Fabric servers install into mods/; everything else installs into plugins/.

Backups

Command	What it does
backup create -id <id>	Zip the server folder (logs excluded) into <data dir>/backups/<id>/backup_<timestamp>.zip
backup list -id <id>	List backups for a server
backup restore -id <id> -name <filename>	Restore a server from a backup zip (overwrites current files)
backup delete -id <id> -name <filename>	Delete a specific backup

BuildTools (Spigot)

Spigot ships no prebuilt jars - creating a Spigot server compiles one locally with SpigotMC's BuildTools. The CLI keeps its own copy of BuildTools.jar (downloaded once, in the CLI's own install directory, never overwritten after that) and runs it automatically the first time it's needed.

Command	What it does
buildtools version	Show whether BuildTools is installed (downloads it if missing)
buildtools update	Force BuildTools.jar to re-download now
fetch jdk-compat -sw <software> -v <version>	Which detected JDKs can actually build/run a given software + version - BuildTools enforces an exact compile-time Java range, so this tells you upfront instead of failing after minutes of building

Server discovery

Every server folder carries a mcpanel.json manifest (a copy of its config entry, minus the machine-specific path). Drop a server folder - or a folder restored from a backup - straight into the servers/ data directory and it self-registers automatically:

mcpanel discover          # re-scan servers/ for folders not yet registered; also runs on every CLI startup

Shell completion

eval "$(mcpanel completion bash)"     # add to ~/.bashrc
eval "$(mcpanel completion zsh)"      # add to ~/.zshrc

Completes command names, nouns, -sw/platform values, and live server IDs (via mcpanel api list servers).

System

detect-jdk (now flags JRE-only installs via hasCompiler), fetch jdk-compat, system, version, check-update, config show, config path.

Updating

mcpanel updateapp                       # update everything installed here (MCPanel, WebUI, CLI)
mcpanel updateapp -p mcpanel            # just the desktop app (AppImage / rpm / deb / NSIS / dmg)
mcpanel updateapp -p cli                # just the CLI (alias of mcpanel-cli; reinstalls via pip)
mcpanel updateapp -path ~/MCPanel-WebUI # the WebUI in that folder (git pull / source zip + npm install)

Fetches the newest GitHub release and installs it. Every GitHub fetch tries the MCPanel-Studios organisation first and falls back to the old DippyCoder repositories.

Shutdown

mcpanel shutdown          # kill all running servers and stop MCPanel

Also available as /shutdown inside mcpanel cli (servers keep running if you use /exit instead).

---

API mode (terminal as backend)

Prefix any command with api to get raw JSON - ideal for scripting or wiring a UI on top:

mcpanel api fetch server  -id srv_123      # one server (+ running flag)
mcpanel api list servers                    # { "servers": [...] }
mcpanel api fetch config                    # the whole config.json
mcpanel api fetch versions -sw paper        # { "versions": [...] }
mcpanel api fetch log     -id srv_123       # [{time,text,type}, ...]
mcpanel api fetch logfiles -id srv_123      # {files:[{name,size,modified}]}
mcpanel api upload-log    -id srv_123       # {success,url,id,raw,file,lines,totalLines,truncated}
mcpanel api fetch status  -id srv_123       # true / false
mcpanel api ping server   -id srv_123       # { online, players, ... }
mcpanel api fetch stats   -id srv_123       # { size, ramBytes, cpuPct }
mcpanel api create server -t x -sw paper -v 1.21.1   # { success, server }
mcpanel api system                          # { totalRam, availableStorage }
mcpanel api search plugins modrinth luckperms -id srv_123   # { results, hasMore }
mcpanel api backup list -id srv_123         # { backups: [...] }
mcpanel api fetch jdk-compat -sw spigot -v 1.21.1   # { range, jdks, recommended }

Every error comes back as {"error": "<message>", "code": "<code>"} with a non-zero exit code - argument errors and crashes included. error is always a complete, ready-to-show sentence; code is a stable identifier for logic only. Clients should display error as-is and never keep their own code→text table: that way an error added in a newer CLI still reads correctly in an older MCPanel or WebUI. Unknown codes should be treated like the generic error.

mcpanel api errors lists every code (the CLI's plus any addon's) with its default message.

proxy link is all-or-nothing: if writing velocity.toml, server.properties, paper-global.yml or config.json fails, every file already written is restored and the reply looks like:

{"error": "Proxy link failed while writing paper-global.yml: ...", "code": "proxy_link_failed",
 "failedStep": "paper-global.yml", "rolledBack": true, "rollbackErrors": []}

rolledBack: false means the restore itself failed for the files in rollbackErrors.

---

Addons

Addons add new command groups to the CLI. Because the CLI is MCPanel's backend, an addon that adds mcpanel api foo bar is immediately callable from the desktop app and the WebUI too - there's no second integration to write.

Command	What it does
addons list	List discovered addons with their source and status
addons info <name>	One addon's metadata (and its traceback, if it failed to load)
addons enable <name> / addons disable <name>	Toggle an addon; disabling never deletes anything
addons install <path|url>	Install from a .py file, an addon folder (or a project folder containing one), a .zip, or an https:// URL - e.g. a GitHub "Download ZIP" link. Reinstalling upgrades in place
addons remove <name>	Remove a user-installed addon (bundled and pip-installed ones are refused)

Addons are discovered from three places, in this order - first wins on a name clash:

Source	Location
bundled	ships inside the CLI (mcpanel/bundled_addons/, currently empty) - enabled by default
pip	any installed distribution exposing the mcpanel.addons entry-point group
user	<data dir>/addons/<name>.py or <data dir>/addons/<name>/__init__.py

A broken addon is skipped and reported by addons list - it never stops the CLI from starting. MCPANEL_NO_ADDONS=1 disables addon loading entirely, as an escape hatch.

Addons are not sandboxed: an addon can do anything the user running mcpanel can. Install addons you trust.

Writing one is documented in ADDONS.md.

---

Addon libraries (mcpanel mclib / mclib)

Install addons from an addon library - MCLib by default - or straight from a GitHub/Codeberg repository. Versions come from the repository's releases; no other platform is accepted.

mcpanel mclib <library|repo-url> <list|install|update|downgrade|remove> [name] [version]
mclib         <library|repo-url> <list|install|update|downgrade|remove> [name] [version]

mclib mclib list                          # browse MCLib
mclib mclib list accounts                 # an addon's releases
mclib mclib install accounts [v1.1.0]     # newest stable, or a pinned release tag
mclib mclib update [accounts] [version]   # one addon, or everything from that library
mclib mclib downgrade accounts [version]  # to the previous (or a given) release
mclib mclib remove accounts
mclib https://github.com/o/r install v2   # a repo URL replaces <library> <name>

mclib is a shorthand for mcpanel mclib (installed next to mcpanel); in the TUI use /mclib or just mclib. Before anything is downloaded from an addon's repository you must accept the third-party disclaimer (prompt, or -y/--yes). In JSON mode an unaccepted install returns code disclaimer_required with the disclaimer text and the library's terms, so an app can show them and retry with --yes.

All addons - whether they're for the CLI, the desktop app or the WebUI - install into the CLI's addons/ folder and run inside the CLI. Two files there belong to this command:

File	What it's for
addons/libraries.json	The libraries mclib <name> can use. Created with mclib → MCLib; add your own {"name": {"url": ".../index.json"}} entries for other libraries.
addons/mclib-installed.json	Which addon came from which library and release (managed automatically).

The desktop app and the WebUI have the same browser built in (the Addons page), and addons can extend those interfaces too - see ADDONS.md.

---

Accounts & permissions

User accounts, roles and permissions (what MCPanel-WebUI signs people in with) live in a separate addon, MCPanel-Accounts - the CLI itself doesn't ship them. The desktop app doesn't need it; the WebUI does:

mclib mclib install accounts                              # from MCLib (GitHub releases)
mcpanel accounts passwd -u admin -p "a real password"     # the seeded login is admin / admin

Existing account data (<data dir>/addon-data/accounts/accounts.db) is picked up as-is - it never lived inside the CLI. See that repository's README for the full command reference.

---

How running servers work

A CLI invocation is short-lived, so each running server is owned by a detached supervisor process (python -m mcpanel.supervisor <id>). It launches Java, streams stdout/stderr to a structured log, and exposes a control socket (Unix domain socket on Linux/macOS, TCP loopback on Windows) so cmd / stop / kill from any later invocation reach the live process. Runtime state lives in the run/ subfolder of the data directory.

---

Layout

mcpanel/
├── cli.py          ← argparse tree (human + api) and dispatch
├── tui.py          ← interactive REPL (mcpanel cli)
├── servers.py      ← server controllers (create/start/stop/…)
├── profiles.py     ← profile controllers
├── plugins.py      ← plugin/mod search + install (Modrinth, Hangar, Spiget)
├── backup.py       ← server backup create/list/restore/delete (zip)
├── buildtools.py   ← SpigotMC BuildTools download + compile-on-create for Spigot
├── versions.py     ← version listing + download-URL resolution
├── supervisor.py   ← detached daemon that owns one running server
├── runstate.py     ← client helpers for talking to supervisors
├── ping.py         ← Minecraft server-list-ping
├── system.py       ← JDK detection (+ compatibility ranges), system info, update check
├── render.py       ← human-readable output + ANSI helpers
├── addons.py       ← addon discovery, loading and the `addons` command group
├── errors.py       ← the API error contract + catalogue (`mcpanel api errors`)
├── mclib.py        ← `mcpanel mclib` / `mclib`: addon libraries, GitHub/Codeberg releases
├── bundled_addons/ ← first-party addons that ship with the CLI (none at the moment)
└── http.py · util.py · config.py · paths.py

config.py also owns each server's mcpanel.json manifest (see Server discovery) - written on every create/update/duplicate/import so a server folder can be moved between installs or restored from backup and re-register itself.

---

Notes

• Spigot is compiled locally via BuildTools, which the CLI downloads and runs automatically on first use - this requires a full JDK (not a JRE-only install) in the version BuildTools expects for that Minecraft version; run mcpanel fetch jdk-compat -sw spigot -v <version> to check first.
• Fabric downloads the server-side loader JAR from FabricMC.
• Match your Java version to the Minecraft version (1.20.5+ needs Java 21) - detect-jdk and fetch jdk-compat both report this per-JDK now.
• stats reads CPU straight from the OS (/proc/<pid>/stat, GetProcessTimes on Windows) and reports it as a share of the whole machine. A CLI invocation is one-shot, so the figure is the delta since the previous stats call for that server (cached in run/<id>.cpu) - the first call after a start therefore reports 0%.
• The JSON shapes from api mirror the original Electron IPC return values 1:1.
• The interactive TUI requires prompt_toolkit (installed automatically via pip). On terminals without ANSI support the TUI degrades gracefully to plain text.