dosctl 1.4.0

A command-line tool to manage and play DOS games via DOSBox.

DOSCtl

A command-line tool to manage and play DOS games via DOSBox.

Installation

Requirements: Python 3.8+, DOSBox

# Install DOSBox
brew install dosbox          # macOS
sudo apt install dosbox      # Ubuntu/Debian

# Install DOSCtl
pip install dosctl

Other install methods

# From GitHub
pip install git+ssh://[e-mail]/xesco/dosctl.git

# Development (editable)
git clone [e-mail]:xesco/dosctl.git
cd dosctl
pip install -e ".[dev]"

Getting Started

1. List games — the game catalog downloads automatically on first run:

   dosctl list
   

2. Search for a game:

   dosctl search "Dune" --sort-by year
   

3. Play a game by its ID. On first run, dosctl downloads, installs, and asks you to pick the executable:

   dosctl play <game-id>
   

Commands

Every game has a unique 8-character ID (shown in list/search output). Use it for all operations.

dosctl list

Lists all available games.

Flag	Description
-s, --sort-by [name|year]	Sort by name or year
-i, --installed	Only show installed games

dosctl search <query>

Searches for games. Query is optional if --year is used.

Flag	Description
-y, --year <year>	Filter by year
-c, --case-sensitive	Case-sensitive search
-s, --sort-by [name|year]	Sort by name or year

dosctl play <game-id> [command-parts...]

Runs a game. Downloads and installs it if needed. On first run, prompts for the main executable; the choice is saved for future runs.

You can override the saved executable by passing command parts directly, or use --configure to re-pick interactively:

dosctl play 62ef2769                    # Use saved default
dosctl play 62ef2769 --configure        # Re-pick executable interactively
dosctl play 62ef2769 setup.exe          # Run a specific executable
dosctl play 62ef2769 game.exe -level 5  # Pass arguments to the executable

Some games include floppy-based installers that expect source files on A: and install to C:. Use -a to mount the game directory as both drives:

dosctl play 62ef2769 install.bat C: -a  # Run installer with floppy mode
dosctl play 62ef2769 STARCON2/GAME.EXE  # Then run the installed game normally

dosctl inspect <game-id>

Shows installed files for a game. Use -e, --executables to show only .exe/.com/.bat files.

dosctl delete <game-id>

Deletes an installed game and its downloaded archive.

dosctl refresh --force

Re-downloads the master game list from the Internet Archive.

dosctl net host <game-id>

Hosts a multiplayer game over your local network using DOSBox IPX networking. Displays your local IP so the other player knows where to connect.

Flag	Description
-p, --port <port>	UDP port for the IPX server (default: 19900)
-c, --configure	Force re-selection of the default executable

dosctl net join <game-id> <host-ip>

Joins a multiplayer game hosted by another player on your local network.

Flag	Description
-p, --port <port>	UDP port of the IPX server (default: 19900)
-c, --configure	Force re-selection of the default executable

Example — two players on the same network:

# Player 1 (host):
dosctl net host 62ef2769
# Output: "Your local IP appears to be: 192.168.1.42"

# Player 2 (join):
dosctl net join 62ef2769 192.168.1.42

Both DOSBox instances start with IPX networking enabled. Configure multiplayer in the game's own network/modem menu (select IPX). DOSBox stays open after the game exits so you can play again without reconnecting.

Configuration

Data is stored in platform-appropriate directories:

Platform	Base directory
Linux/macOS	~/.local/share/dosctl/
Windows	%USERPROFILE%\AppData\Local\dosctl\

<base-dir>/
  downloads/       # Downloaded .zip archives
  installed/       # Extracted games
  collections/     # Game list cache

Collection Backend

Games are sourced from the Total DOS Collection Release 14 on the Internet Archive. The catalog is downloaded on first use; individual games are downloaded on demand when you run them.

Disclaimer

This tool does not host or distribute any games — it manages content from external sources. You are responsible for ensuring you have legal rights to any content you use. Windows support is experimental; Linux and macOS are the primary platforms.

See LICENSE for the full MIT license.