> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poplock.scyne.com/llms.txt
> Use this file to discover all available pages before exploring further.

# serv commands

> Full reference for every subcommand of the serv CLI, the primary tool for managing the PopLock server.

## Quick reference

| Command          | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| `serv start`     | Start the server in a background tmux session                            |
| `serv stop`      | Gracefully stop the server                                               |
| `serv restart`   | Stop and restart the server                                              |
| `serv console`   | Attach to the live server console                                        |
| `serv status`    | Show online/offline status, version, uptime, memory, and player count    |
| `serv backup`    | Take a full manual backup (stops and restarts the server)                |
| `serv backup -s` | Silent backup — no output, useful for scripting                          |
| `serv restore`   | Interactive restore menu listing all snapshots, backups, and undo points |
| `serv update`    | Check for and apply the latest PaperMC or Vanilla update                 |
| `serv chk`       | Check for available updates without applying them                        |
| `serv chk -s`    | Silent update check — no output if already up to date                    |

***

## serv start

Starts the server inside a persistent background tmux session.

```bash theme={null}
serv start
```

**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):**

```text theme={null}
Minecraft server started in background
Use 'serv console' to view the server console
```

**Example output (already running):**

```text theme={null}
A Minecraft server is already running.
Use 'serv console' to attach or 'serv restart' to restart.
```

**Example output (failed to start):**

```text theme={null}
Failed to start server! Check permissions:
1. Run: sudo chown -R <user>:<user> /usr/local/games/minecraft_server/java
2. Verify: ls -l /usr/local/games/minecraft_server/java/start.sh
3. Check error log: cat /tmp/minecraft_error.log
```

***

## serv stop

Sends a graceful `stop` command to the server console and waits up to 30 seconds for the process to exit cleanly.

```bash theme={null}
serv stop
```

**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):**

```text theme={null}
Stopping Minecraft server...
Minecraft server stopped successfully
```

**Example output (force kill):**

```text theme={null}
Stopping Minecraft server...
Server didn't stop gracefully. Force killing...
```

***

## serv restart

Stops the server if running and immediately relaunches it in a new tmux session.

```bash theme={null}
serv restart
```

**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.

```bash theme={null}
serv 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:

```bash theme={null}
tmux -S /tmp/minecraft-tmux attach -t minecraft
```

***

## serv status

Prints a summary of the server's current state.

```bash theme={null}
serv status
```

**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:**

```text theme={null}
PopLock is Online
Ver: Paper 1.21.4-225
Running for: 02:14:33
Memory usage: 18.3%
Players: 3/20
```

**Player count dependency:**

Player count requires the `mcstatus` Python package. If it is not installed:

```text theme={null}
Player count unavailable - install mcstatus: 'pip install mcstatus'
```

Install it with:

```bash theme={null}
pip install mcstatus
```

**When offline:**

```text theme={null}
PopLock is OFFLINE!!!
```

***

## serv backup

Takes a full backup of the entire server directory as a `.tar.gz` archive.

```bash theme={null}
serv backup          # Interactive — prints progress
serv backup -s       # Silent — no output (suitable for cron or scripting)
```

**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:**

```text theme={null}
Server is running. Stopping for backup...
Stopping Minecraft server...
Minecraft server stopped successfully
Creating backup archive...
Backup successfully saved to: /usr/local/games/minecraft_server/java/backups/minecraft_backup_20250403_230001.tar.gz
Restarting server...
Minecraft server started in background
Use 'serv console' to view the server console
```

***

## 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.

```bash theme={null}
serv restore
```

**Archive types shown in the menu:**

| Type           | Filename pattern                          | Created by           | Contains                                                   |
| -------------- | ----------------------------------------- | -------------------- | ---------------------------------------------------------- |
| Daily Snapshot | `snapshot_YYYYMMDD_HHMMSS.tar.gz`         | `snapshot.sh` (cron) | World directories + `whitelist.json` + `server.properties` |
| Full Backup    | `minecraft_backup_YYYYMMDD_HHMMSS.tar.gz` | `serv backup`        | Entire server directory                                    |
| Restore Undo   | `restore_undo.tar.gz`                     | `serv restore`       | Whatever was replaced in the last restore                  |

**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:**

```text theme={null}
Available Backups:
  [0] Daily Snapshot: 2025-04-03 23:00:01 (1.2G)
  [1] Daily Snapshot: 2025-04-02 23:00:03 (1.1G)
  [2] Full Backup: 20250401_120000 (2.4G)
  [3] Restore Undo (980M)

Select a backup to restore (or press Enter to cancel):
```

***

## serv update

Checks the PaperMC or Mojang API for a newer version of the server jar and, after confirmation, downloads and installs it.

```bash theme={null}
serv update
```

**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):**

```text theme={null}
Checking latest Paper release...
Current version : 1.21.4-220
Latest version  : 1.21.4-225

This will:
  1. Stop the server (if running)
  2. Back up paper.jar  →  /usr/local/games/minecraft_server/java/backups/jars/paper_1.21.4-220.jar
  3. Download paper-1.21.4-225.jar
  4. Restart the server

Proceed with update? [y/N]
```

***

## serv chk

Checks for an available update and prints the result without making any changes. Useful for monitoring or scripting.

```bash theme={null}
serv chk         # Print update status
serv chk -s      # Silent — print nothing if already up to date
```

**Example output (update available):**

```text theme={null}
Checking for updates...
Update available: Paper 1.21.4-225  (current: 1.21.4-220)
Run 'serv update' to upgrade.
```

**Example output (up to date):**

```text theme={null}
Checking for updates...
Server is up to date — Paper 1.21.4-225
```

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.