ProgressQuest-cli

Faithful port of the game logic
Saves (with backups) to $XDG_CONFIG_HOME/pqcli/save.dat
Terminal interface that comes in 2 flavors:
- Rich and colorful (--curses, default)
- Minimal, suitable for raw grind (--basic)
Ideal to run on your server

How it looks like

Curses interface:

Basic interface:

How to install

If you have Python 3.10 or newer, just run pip install --user pqcli and you're good to go! Then type pqcli to run the game.

In case if you want to use the git version, the process is just a bit more complex:

$ git clone https://github.com/rr-/pq-cli.git
$ cd pq-cli
$ pip install --user .

Docker / Docker Compose

The repository includes a Dockerfile and docker-compose.yml that run the game with --basic and keep save data in a persistent named volume.

There is no registry pipeline required for this setup: build locally, then run with Compose.

# Build image locally from the Dockerfile
docker compose build

# First run (interactive): create your character in the shared save volume
docker compose run --rm pqcli-init

# Later runs on a server (detached, default save slot 1):
docker compose up -d pqcli

# List existing saves in the same volume:
docker compose run --rm pqcli-init pqcli --basic --list-saves

# Change detached slot if needed (example: slot 2):
PQCLI_SAVE_SLOT=2 docker compose up -d pqcli

# Follow logs / stop detached container:
docker compose logs -f pqcli
docker compose stop pqcli

On first run, if no save data exists in the mounted volume, pqcli will automatically launch an interactive character-creation bootstrap in CLI mode before starting the normal interface.

For server usage, run first-time setup without a forced slot (pqcli-init), then run the long-lived detached service (pqcli) that loads slot 1 by default.

Customizing the adventure

All word lists (monsters, spells, equipment, races, classes, titles and so on) live in JSON files. To change them, copy the built-in files somewhere and edit them:

$ pqcli --dump-data ~/.config/pqcli/data

On startup, pqcli reads $XDG_CONFIG_HOME/pqcli/data/ (or the directory given with --data-dir DIR). Each NAME.json there replaces the built-in list of the same name. Files you leave out fall back to the built-in lists, so you can delete the copies you don't change. If a file is malformed, pqcli prints what is wrong and refuses to start.

The available files are spells, offense_attrib, defense_attrib, offense_bad, defense_bad, shields, armors, weapons, specials, item_attrib, item_ofs, boring_items, monsters, races, classes, titles, impressive_titles and combat_verbs.

For example, to vary the combat descriptions, create combat_verbs.json. {target} is replaced with the enemy:

[
  "Executing {target}",
  "In a fierce battle to thwart {target}",
  "Fighting bravely against {target}",
  "Kicking the butt of {target}"
]

A few things to keep in mind:

Order matters in spells.json: spells are learned roughly from the top down, so keep weaker spells first.
Titles near the top of titles.json show up more often.
Stats in races.json and classes.json are written as STR, CON, DEX, INT, WIS, CHA, HP Max or MP Max.
Existing characters keep their race and class even if you remove them from the lists.

Contributing

# Clone the repository:
git clone https://github.com/rr-/pq-cli.git
cd pq-cli

# Install to a local venv:
uv sync

# Install pre-commit hooks:
uv run pre-commit install

# Run the game and the tests:
just run
just test

This project uses uv for packaging. Install instructions are available at uv#installation. The justfile needs just; without it, use uv run pqcli and uv run pytest.

Troubleshooting

`_curses.error: init_pair() returned ERR`

If running on Linux and you get the error _curses.error: init_pair() returned ERR, try making sure that your $TERM variable is set to a value which supports 256 colors, such as via the following:

TERM=xterm-256color pqcli