Overview

Date: 2026-05-11

Time: 15:53

Overview

This is the CLI entry point for ftl2-servercraft, a Minecraft server lifecycle manager built on FTL2. It provides subcommands to provision, start, stop, back up, verify, and monitor game servers on Linode infrastructure. Each command loads server definitions from a YAML config file, sets up FTL2 automation with secret bindings and state management, then delegates to per-server-type scripts for the actual work.

Usage Patterns

The CLI is invoked as a single binary with subcommands:

# Show status of all configured servers
ftl2-servercraft status

# Provision and start a server, restoring from latest backup
ftl2-servercraft launch my-server

# Start fresh without restoring a backup
ftl2-servercraft launch my-server --fresh

# Re-provision a running server (e.g. after config change)
ftl2-servercraft reconfigure my-server

# Back up, then destroy a server
ftl2-servercraft stop my-server

# Check if the server's tmux session is alive
ftl2-servercraft verify my-server

# Back up without stopping
ftl2-servercraft backup my-server

# Run the auto-teardown watchdog (stops server when no players)
ftl2-servercraft watchdog my-server

# Launch the TUI dashboard (default when no subcommand given)
ftl2-servercraft tui
ftl2-servercraft  # also launches TUI

All commands accept --config path/to/servers.yml (defaults to servers.yml).

API and Configuration

Config file (servers.yml): Defines servers by name. Each config object exposes .name, .label, .script, .inventorypath, .statepath, .slackchannel, plus methods like .getip(), .isprovisioned(), .getbackups().

FTL2 automation context: Every command that touches infrastructure creates an automation() context with:

• secretbindings — maps module FQCNs to Vault secret names (LINODETOKEN, LINODEROOTPASS, SLACK_TOKEN)
• inventory — path from server config
• state_file — path from server config (crash recovery / idempotency)
• fail_fast=True — abort on first module failure
• gate_modules="auto" — pre-build modules for remote execution (launch/reconfigure only)
• gate_dependencies=["httpx"] — additional Python deps for gated modules
• autoinstalldeps=True — install missing module dependencies automatically

Logging: Each command creates a timestamped log file under logs/ (e.g. logs/provision-my-server-20260511-143022.log). Output goes to both file and stdout.

Key Behaviors

• Launch runs the full lifecycle: provision → optionally restore from backup → start → verify. Verification failure raises RuntimeError and exits with code 1.
• Stop performs save → backup → Slack notification → destroy. Backup and Slack failures are caught and logged but don't abort the destroy step.
• Reconfigure requires the server to already be provisioned; it re-runs provision and start without destroying.
• Verify exits with code 2 if the tmux session is not found (distinct from code 1 for errors).
• Watchdog runs until Ctrl-C, monitoring player count and auto-tearing down empty servers.
• Restore logic on launch: if --fresh is not passed, the latest backup is restored. If no backups exist, it logs a message and proceeds fresh anyway.
• All commands that require a provisioned server check config.is_provisioned() and exit early with a message if not.
• Server name must match a key in servers.yml; unknown names print available options and exit.

Relationships

• config.load_config() — loads and parses servers.yml into server config objects
• scripts.getscript() — returns a script module by name with provision(), startserver(), verifyserver(), saveandstop(), backupworld(), restore_world(), destroy() functions
• ftl2.automation — the FTL2 async context manager providing the ftl handle for running modules
• community.general.linodev4 — Linode provisioning module (bound to LINODETOKEN, LINODEROOTPASS)
• community.general.slack — Slack notification module (bound to SLACK_TOKEN)
• .watchdog.runwatchdog / .tui.runtui / .tui.ServerState — watchdog and TUI subsystems