README
¶
pzmod
Project Zomboid dedicated-server mod manager · this is how you modded.
pzmod is a keyboard-driven terminal app (plus a scriptable CLI) for managing
the mods on a Project Zomboid dedicated server. It browses the Steam Workshop,
resolves dependencies, orders your mods, validates everything before you boot the
server, and keeps timestamped backups, all while preserving your
servertest.ini byte-for-byte.
Features
- Terminal app: browse and manage everything from a fast, keyboard-driven UI
- Workshop search & browse: find mods and add them without copying IDs
- Dependency auto-resolution: pull in required items (and their deps) for you
- Load-order management: reorder mods and get a framework-first suggestion
- Type-to-filter: press
/on any long list to filter instantly - Dry-run validation: catch missing deps, unknown mod IDs, delisted items, and bad map order before launch
- Backups & rollback: every save snapshots the config; restore in one step
- Multiple server profiles: manage several configs from one place
- Build 41 / Build 42 awareness: per-profile build with compatibility hints
- Byte-exact config edits: comments, ordering, and line endings are preserved
Demo
Each clip is captioned with what it does. Filter a long list, get a load-order suggestion, validate before you boot, and snapshot every save:
 |
 |
 |
 |
Install
Linux & macOS
curl -fsSL https://pzmod.dev/install.sh | bash
Installs the latest release to /usr/local/bin (Intel and Apple Silicon), with the
download checksum-verified. Pass a custom path with | bash -s -- ~/.local/bin/pzmod.
Prefer to read the script first?
curl -fsSL https://pzmod.dev/install.sh -o install.sh
less install.sh
bash install.sh # optional: bash install.sh ~/.local/bin/pzmod
Windows (PowerShell)
irm https://pzmod.dev/install.ps1 | iex
Installs to %LOCALAPPDATA%\pzmod and adds it to your user PATH.
Docker
A minimal multi-arch image (amd64/arm64) is published to the GitHub Container Registry:
docker run --rm -it \
-e PZMOD_STEAM_KEY=<key> \
-v "$PWD:/data" \
ghcr.io/kldzj/pzmod --file /data/servertest.ini validate
Pass your Steam key with PZMOD_STEAM_KEY and mount your config in. Add
-v pzmod:/config to persist profiles and backups across runs.
Manual
Download a binary from the releases page.
Usage
# Launch the interactive terminal app (profile picker)
pzmod
# Open a specific config directly
pzmod --file path/to/servertest.ini
# Scriptable subcommands (use --file or --profile, or the default profile)
pzmod profile add --name "My Server" --file path/to/servertest.ini --build b41
pzmod set name "My Server"
pzmod get list
pzmod search hydrocraft
pzmod mods add 2392709985 --resolve-deps
pzmod validate # exits non-zero on errors (CI-friendly)
pzmod backup list
Run pzmod --help for the full command list.
Requirements
- A Steam Web API key (get one here)
- A Project Zomboid server install (or at least a
servertest.ini)
Support
pzmod is free and open source. If it saves you time running your server, please consider sponsoring its development on GitHub. It directly funds new features and maintenance. ♥
Upgrading from v2
Config now lives in ~/.config/pzmod (%AppData%\pzmod on Windows). Your
existing ~/.pzmod API key is migrated automatically on first run. The old
--file flag and the get/set/copy/api-key/update commands still work
as before.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
bbcode
Package bbcode renders Steam Workshop BBCode into terminal-styled text.
|
Package bbcode renders Steam Workshop BBCode into terminal-styled text. |
|
cli
Package cli builds pzmod's cobra command tree.
|
Package cli builds pzmod's cobra command tree. |
|
openurl
Package openurl opens a URL in the user's default browser, best-effort.
|
Package openurl opens a URL in the user's default browser, best-effort. |
|
pathutil
Package pathutil holds small filesystem path helpers shared by the CLI and TUI.
|
Package pathutil holds small filesystem path helpers shared by the CLI and TUI. |
|
tui
Package tui is pzmod's Bubble Tea terminal application.
|
Package tui is pzmod's Bubble Tea terminal application. |
|
pkg
|
|
|
build
Package build models Project Zomboid build awareness (B41 vs B42).
|
Package build models Project Zomboid build awareness (B41 vs B42). |
|
domain
Package domain holds pure value types and transforms for Project Zomboid mod management.
|
Package domain holds pure value types and transforms for Project Zomboid mod management. |
|
ini
Package ini implements a byte-exact, round-trip-preserving INI document model.
|
Package ini implements a byte-exact, round-trip-preserving INI document model. |
|
modinfo
Package modinfo optionally enriches load-order analysis by reading mod.info files from a downloaded Workshop content directory.
|
Package modinfo optionally enriches load-order analysis by reading mod.info files from a downloaded Workshop content directory. |
|
serverconfig
Package serverconfig is the Project Zomboid-aware wrapper over a byte-exact ini.Document.
|
Package serverconfig is the Project Zomboid-aware wrapper over a byte-exact ini.Document. |
|
service
Package service orchestrates the domain logic over injected adapters (Steam API, on-disk store, optional mod.info provider).
|
Package service orchestrates the domain logic over injected adapters (Steam API, on-disk store, optional mod.info provider). |
|
steam
Package steam is an injectable client for the Steam Web API's Workshop endpoints.
|
Package steam is an injectable client for the Steam Web API's Workshop endpoints. |
|
steam/steamtest
Package steamtest provides an in-memory fake of steam.API for service tests.
|
Package steamtest provides an in-memory fake of steam.API for service tests. |
|
store
Package store persists pzmod's state under the user config directory (~/.config/pzmod on Linux, %AppData%/pzmod on Windows): server profiles, the Steam API key, and timestamped config backups.
|
Package store persists pzmod's state under the user config directory (~/.config/pzmod on Linux, %AppData%/pzmod on Windows): server profiles, the Steam API key, and timestamped config backups. |