Skip to main content

​
Quick reference

​
serv start

Starts the server inside a persistent background tmux session.
Behavior:
  1. Checks whether a Java server process is already running. If one is found, it prints a warning and exits.
  2. Checks whether a tmux session named minecraft exists without an attached Java process (a zombie session). If found, the zombie is cleaned up before proceeding.
  3. Launches start.sh inside a new detached tmux session.
  4. Waits 3 seconds, then checks whether the process is alive.
Example output (success):
Example output (already running):
Example output (failed to start):

​
serv stop

Sends a graceful stop command to the server console and waits up to 30 seconds for the process to exit cleanly.
Behavior:
  1. Creates a stop_signal file in the server directory. This tells start.sh not to restart the server after it exits.
  2. Sends the stop command to the tmux session.
  3. Polls once per second for up to 30 seconds waiting for the Java process to exit.
  4. If the process is still alive after 30 seconds, force-kills it with pkill and destroys the tmux session.
Example output (graceful stop):
Example output (force kill):

​
serv restart

Stops the server if running and immediately relaunches it in a new tmux session.
Behavior:
  1. Sends stop to the server console if a process is detected, waits 10 seconds, then kills the tmux session.
  2. Creates a new detached tmux session running start.sh.
Unlike serv stop, restart does not create a stop_signal file — the startup loop inside start.sh is free to restart on crash as normal.

​
serv console

Attaches your terminal to the live tmux session so you can read logs and type commands directly into the server console.
To detach without stopping the server: press Ctrl+B, then D. The session name is minecraft and uses the socket at /tmp/minecraft-tmux. You can also attach manually:

​
serv status

Prints a summary of the server’s current state.
When online, displays:
  • Online/offline status
  • Server version (Paper MC_VERSION-BUILD or Vanilla MC_VERSION, detected from the jar)
  • Process uptime
  • Memory usage (% of system RAM)
  • Player count (requires mcstatus — see below)
Example output:
Player count dependency: Player count requires the mcstatus Python package. If it is not installed:
Install it with:
When offline:

​
serv backup

Takes a full backup of the entire server directory as a .tar.gz archive.
Behavior:
  1. If the server is running, stops it first (using serv stop).
  2. Creates backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz containing the full server directory, excluding backups/, cache, and build artifacts.
  3. If the server was running before the backup, restarts it automatically.
  4. If the server was offline when the backup started, it is left offline after the backup completes.
Example output:

​
serv restore

Opens an interactive numbered menu listing every available archive in backups/. Selecting an entry will restore the server to that point in time.
Archive types shown in the menu: Restore procedure:
  1. Stop the server if it is running.
  2. Create an undo backup (restore_undo.tar.gz) of whatever files are about to be replaced.
  3. Wipe the target directories to ensure no stale chunk or player files survive.
  4. Extract the selected archive into the server directory.
  5. Remove any stale session.lock files from restored world directories.
  6. Restart the server if it was running before the restore.
To undo a restore: run serv restore again and select Restore Undo. Example menu output:

​
serv update

Checks the PaperMC or Mojang API for a newer version of the server jar and, after confirmation, downloads and installs it.
Behavior:
  1. Detects whether the current jar is PaperMC or Vanilla by inspecting server.jar.
  2. Queries the appropriate API for the latest available version.
  3. Displays the current version and the latest available version.
  4. If already up to date, exits immediately.
  5. If an update is available, shows a summary of the planned actions and prompts for confirmation ([y/N]).
  6. Stops the server if running.
  7. Backs up the current server.jar to backups/jars/.
  8. Downloads the new jar, replacing server.jar.
  9. If the download fails, restores the backed-up jar automatically.
  10. Restarts the server.
Example output (PaperMC):

​
serv chk

Checks for an available update and prints the result without making any changes. Useful for monitoring or scripting.
Example output (update available):
Example output (up to date):
With -s, no output is produced when the server is up to date, making it suitable for use in cron jobs where you only want output when action is needed.