Skip to main content

CLI and Server Overview

When MineBackup needs to run on a Minecraft Dedicated Server, VPS, NAS, or SSH-only Linux host, minebackup-cli is the official entry point for configuring, backing up, verifying, and rehearsing a cold restore without starting the GUI. It is provided as a headless/server mode starting with MineBackup 1.16.2.

What is the CLI?​

minebackup-cli is a separately deployable command-line program. It can create a Manifest from an empty Profile, validate configuration, diagnose the environment, run one-shot backups, inspect History, verify an archive, and plan a Restore dry-run. It does not open dialogs or require a desktop session.

A one-shot command does not require the long-running service, for example:

minebackup-cli --data-dir "$PROFILE" --json backup \
  --config <ConfigId> --world world

How do CLI and GUI fit together?​

Both entry points share the same runtime/core and data contracts:

GUI                 CLI
 │                   │
 └──── shared runtime/core ────┘
              │
      Profile / History
      Backup / Restore

The GUI and CLI are therefore not incompatible products. They use the same Profile, History, archive, and restore core. A Profile still has single-instance ownership, so do not let a GUI and a CLI write to the same Profile at the same time.

When should you choose the CLI?​

The CLI is especially useful for:

  • Minecraft Dedicated Server;
  • SSH-only Linux, VPS, and NAS hosts;
  • systems without a DISPLAY or Wayland session;
  • long-running servers scheduled by systemd or Windows Task Scheduler;
  • unattended workflows that need one server account, a fixed Profile, and auditable JSON output.

Ordinary Windows, Linux, and macOS desktop users can continue using the GUI. The CLI is the server/headless path, not a forced migration for desktop users.

CLI is not the same as serve​

minebackup-cli backup

can perform a one-shot operation by itself. serve is an optional long-running Profile runtime for persistent Minecraft servers, KnotLink, hot restore, or frequent CLI calls. It forwards requests over local IPC and does not open a TCP/UDP management port. Basic CLI configuration, backup, and verification do not depend on serve.

  1. Five-minute quick start: complete the first server backup
  2. Use AI to generate a configuration (optional)
  3. Profiles and Manifests
  4. Backup, History, Verify, and Restore
  5. Job workflows and the long-running Serve runtime
  6. Read Linux and systemd or Windows Task Scheduler
  7. Finish with Commands, JSON, and exit codes and CLI troubleshooting

Every configuration tutorial follows the same safety chain:

generate/edit manifest
        ↓
profile validate → profile diff → profile apply --dry-run
        ↓
profile apply → doctor → backup → history → verify
        ↓
restore --dry-run