| Name | dosctl JSON |
| Version |
1.1.4
JSON |
| download |
| home_page | None |
| Summary | A command-line tool to manage and play DOS games via DOSBox. |
| upload_time | 2025-08-09 13:17:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
dos
games
retro
dosbox
cli
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# DOSCtl
A command-line tool to manage and play DOS games.
## Installation
### Requirements
- **Python:** 3.8 or higher
- **DOSBox:** Required for running games
### Install DOSBox
```bash
# macOS
brew install dosbox
# Ubuntu/Debian
sudo apt install dosbox
# Windows
# Download from https://www.dosbox.com/
```
### Install DOSCtl
#### From PyPI (Recommended)
```bash
pip install dosctl
```
#### From GitHub (Development Version)
Install the latest development version directly from GitHub:
```bash
pip install git+https://github.com/xesco/dosctl.git
```
Or install a specific version/tag:
```bash
pip install git+https://github.com/xesco/dosctl.git@v1.1.0
```
For development with editable install:
```bash
git clone https://github.com/xesco/dosctl.git
cd dosctl
pip install -e ".[dev]"
```
## Getting Started
1. **List Games:** Find a game you want to play. The tool will automatically download the game list from the [Total DOS Collection Release 14](https://archive.org/details/Total_DOS_Collection_Release_14) on the first run.
```bash
dosctl list
```
2. **Search for a Game:** Narrow down the list with a search.
```bash
dosctl search "Dune" --sort-by year
```
3. **Run a Game:** Run the game using its ID. The first time you run a game, `dosctl` will download and install it, then ask you to choose the correct executable.
```bash
dosctl run <game-id>
```
## Core Concepts
### Game IDs
Every game in the collection is assigned a unique 8-character ID (a hash of its path). You use this ID for all operations like running, inspecting, or deleting games.
### First-Time Run
The first time you run a game, `dosctl` will prompt you to select the main executable file from a list of possibilities (`.exe`, `.com`, `.bat`). Your choice is remembered, so subsequent runs will launch the game immediately. You can force this selection again by using the `--configure` flag.
### Command Parts
You can specify exactly what DOS command to run by providing **command parts** after the game ID. This gives you fine-grained control over game execution:
- **Without command parts:** `dosctl run <game-id>` uses the saved default executable
- **With command parts:** `dosctl run <game-id> setup.exe -silent` runs the exact command you specify
Command parts are joined with spaces to form the final DOS command. This is useful for:
- Running different executables (setup, configuration tools, etc.)
- Passing command-line arguments to games
- Running batch files with parameters
- Bypassing the saved default when needed
**Examples:**
```bash
dosctl run 62ef2769 setup.exe # Run setup instead of main game
dosctl run 62ef2769 game.exe -debug # Run with debug flag
dosctl run 62ef2769 install.bat /q # Run batch file quietly
dosctl run 62ef2769 editor.exe level1 # Run level editor with specific level
```
## Usage Examples
### List only your installed games
```bash
$ dosctl list -i
Available Games:
[53ad2f67] (1991) Lemmings (1991)(Psygnosis Limited) [Strategy, Action]
[fdcc9602] (1990) Secret of Monkey Island, The (VGA) (1990)(Lucasfilm Games LLC) [Adventure]
```
### Search for a game
```bash
$ dosctl search "metal mutant"
Found 5 game(s):
[dd228682] (1991) Metal Mutant (1991)(Silmarils) [Action, Adventure]
[55123659] (1991) Metal Mutant (1991)(Silmarils) [Codes]
[9a5aa0b6] (1991) Metal Mutant (Es) (1991)(Silmarils) [Action, Adventure]
```
### Run a game for the first time
```bash
$ dosctl run dd228682
Downloading 'Metal Mutant (1991)(Silmarils) [Action, Adventure].zip'...
✅ Successfully installed 'Metal Mutant (1991)(Silmarils) [Action, Adventure]'
No default executable set for game 'dd228682'. Searching...
Found a single executable: 'METAL.EXE'. Setting as default.
Starting 'METAL.EXE' with DOSBox...
```
### Run a specific executable directly
```bash
$ dosctl run dd228682 setup.exe
Starting 'SETUP.EXE' with DOSBox...
```
### Run with command-line arguments
```bash
$ dosctl run dd228682 game.exe -difficulty hard -level 3
Starting 'GAME.EXE -DIFFICULTY HARD -LEVEL 3' with DOSBox...
```
### Run main executable with required parameters
```bash
$ dosctl run dd228682 metal.exe soundblaster
Starting 'METAL.EXE SOUNDBLASTER' with DOSBox...
```
### Force reconfiguration of saved executable
```bash
$ dosctl run dd228682 --configure
Please choose one of the following to run:
1: METAL.EXE
2: SETUP.EXE
3: README.BAT
Select a file to execute: 2
Starting 'SETUP.EXE' with DOSBox...
```
### Inspect game files
```bash
$ dosctl inspect dd228682
Inspecting files for 'Metal Mutant (1991)(Silmarils) [Action, Adventure]' (ID: dd228682)
Location: <dosctl-data-dir>/installed/dd228682
----------------------------------------
METAL.EXE
SETUP.EXE
README.TXT
DATA/LEVELS.DAT
DATA/SOUNDS.DAT
```
### Show only executable files
```bash
$ dosctl inspect dd228682 --executables
Inspecting files for 'Metal Mutant (1991)(Silmarils) [Action, Adventure]' (ID: dd228682)
Location: <dosctl-data-dir>/installed/dd228682
----------------------------------------
Executable files:
METAL.EXE
SETUP.EXE
```
## Commands
* `dosctl list`
* Lists all available games.
* `-s, --sort-by [name|year]`: Sort the list by name or year.
* `-i, --installed`: Only show games that are currently installed.
* `dosctl search <query>`
* Searches for games. The query is optional if `--year` is used.
* `-y, --year <year>`: Filter by a specific year.
* `-c, --case-sensitive`: Make the search case-sensitive.
* `-s, --sort-by [name|year]`: Sort the results by name or year.
* `dosctl run <game-id> [command-parts...]`
* Runs a game. Downloads and installs it if necessary.
* Prompts for an executable on the first run.
* **Command Parts:** You can specify the exact DOS command to run instead of using the saved default.
* `-c, --configure`: Force the interactive executable selection menu to appear.
**Examples:**
```bash
dosctl run 62ef2769 # Use saved/default executable
dosctl run 62ef2769 --configure # Choose executable interactively
dosctl run 62ef2769 setup.exe # Run specific executable
dosctl run 62ef2769 game.exe -level 5 # Run with command-line arguments
dosctl run 62ef2769 install.bat quiet # Run batch file with parameters
```
* `dosctl inspect <game-id>`
* Shows the list of installed files for a game.
* `-e, --executables`: Show only executable files (.exe, .com, .bat).
* `dosctl delete <game-id>`
* Deletes an installed game and its files.
* `dosctl refresh --force`
* Forces a re-download of the master game list from the Internet Archive.
## Configuration
`dosctl` stores its data in platform-appropriate directories following OS conventions.
### File Locations
**Linux & macOS:**
```
~/.local/share/dosctl/
├── downloads/ # Downloaded game archives (.zip files)
├── installed/ # Extracted and installed games
├── collections/ # Game collection metadata cache
├── current_session.json
└── installations.json
```
**Windows:**
```
%USERPROFILE%\AppData\Local\dosctl\
├── downloads\ # Downloaded game archives (.zip files)
├── installed\ # Extracted and installed games
├── collections\ # Game collection metadata cache
├── current_session.json
└── installations.json
```
**Examples:**
- Linux: `/home/username/.local/share/dosctl/`
- macOS: `/Users/username/.local/share/dosctl/`
- Windows: `C:\Users\username\AppData\Local\dosctl\`
### Storage Requirements
- **downloads/**: Game archives (typically 1-50 MB each)
- **installed/**: Extracted games (typically 2-100 MB each)
- **collections/**: Metadata cache (~5 MB)
Plan for several GB of storage if you install many games.
## Collection Backend
By default, `dosctl` uses the [**Total DOS Collection Release 14**](https://archive.org/details/Total_DOS_Collection_Release_14) from the Internet Archive as its game collection source. This comprehensive collection contains thousands of DOS games from the 1980s and 1990s, all ready to download and play.
The collection includes:
- Classic DOS games from various genres (adventure, action, strategy, RPG, etc.)
- Games from major publishers like LucasArts, Sierra, id Software, and many others
- Both well-known titles and obscure gems
- Games in their original format, preserved for historical accuracy
When you first run `dosctl list` or `dosctl search`, the tool will automatically download the complete game catalog from this collection. The games themselves are downloaded individually only when you choose to run them.
## ⚠️ Important Legal Disclaimer
**Use at Your Own Risk**: This software is provided "as is" without any warranty. You are solely responsible for your actions when using this tool.
**Content Responsibility**: This tool does not host or distribute any games. It only helps manage content you legally obtain elsewhere. You are responsible for:
- Ensuring you have legal rights to any games you manage
- Respecting copyright laws and software licenses
- Any legal consequences of your usage
**No Liability**: The author is not responsible for copyright infringement or any damages arising from use of this software.
**Legal Compliance**: Ensure you have proper legal rights to any games or software you manage with this tool. Respect copyright laws and software licenses.
## ⚠️ Windows Support Notice
Windows support is currently **experimental**. While the core functionality should work, it has not been extensively tested on Windows systems. Linux and macOS are the primary supported platforms.
If you encounter issues on Windows, please report them on GitHub. Contributions to improve Windows compatibility are welcome!
Raw data
{
"_id": null,
"home_page": null,
"name": "dosctl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "dos, games, retro, dosbox, cli",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b4/3b/3e0bc7ec2dd19bcd2b7227b50d035a5e6891d1414a4f4a6f72b4adc130e9/dosctl-1.1.4.tar.gz",
"platform": null,
"description": "# DOSCtl\n\nA command-line tool to manage and play DOS games.\n\n\n\n## Installation\n\n### Requirements\n- **Python:** 3.8 or higher\n- **DOSBox:** Required for running games\n\n### Install DOSBox\n```bash\n# macOS\nbrew install dosbox\n\n# Ubuntu/Debian\nsudo apt install dosbox\n\n# Windows\n# Download from https://www.dosbox.com/\n```\n\n### Install DOSCtl\n\n#### From PyPI (Recommended)\n```bash\npip install dosctl\n```\n\n#### From GitHub (Development Version)\nInstall the latest development version directly from GitHub:\n```bash\npip install git+https://github.com/xesco/dosctl.git\n```\n\nOr install a specific version/tag:\n```bash\npip install git+https://github.com/xesco/dosctl.git@v1.1.0\n```\n\nFor development with editable install:\n```bash\ngit clone https://github.com/xesco/dosctl.git\ncd dosctl\npip install -e \".[dev]\"\n```\n\n## Getting Started\n\n1. **List Games:** Find a game you want to play. The tool will automatically download the game list from the [Total DOS Collection Release 14](https://archive.org/details/Total_DOS_Collection_Release_14) on the first run.\n ```bash\n dosctl list\n ```\n2. **Search for a Game:** Narrow down the list with a search.\n ```bash\n dosctl search \"Dune\" --sort-by year\n ```\n3. **Run a Game:** Run the game using its ID. The first time you run a game, `dosctl` will download and install it, then ask you to choose the correct executable.\n ```bash\n dosctl run <game-id>\n ```\n\n## Core Concepts\n\n### Game IDs\nEvery game in the collection is assigned a unique 8-character ID (a hash of its path). You use this ID for all operations like running, inspecting, or deleting games.\n\n### First-Time Run\nThe first time you run a game, `dosctl` will prompt you to select the main executable file from a list of possibilities (`.exe`, `.com`, `.bat`). Your choice is remembered, so subsequent runs will launch the game immediately. You can force this selection again by using the `--configure` flag.\n\n### Command Parts\nYou can specify exactly what DOS command to run by providing **command parts** after the game ID. This gives you fine-grained control over game execution:\n\n- **Without command parts:** `dosctl run <game-id>` uses the saved default executable\n- **With command parts:** `dosctl run <game-id> setup.exe -silent` runs the exact command you specify\n\nCommand parts are joined with spaces to form the final DOS command. This is useful for:\n- Running different executables (setup, configuration tools, etc.)\n- Passing command-line arguments to games\n- Running batch files with parameters\n- Bypassing the saved default when needed\n\n**Examples:**\n```bash\ndosctl run 62ef2769 setup.exe # Run setup instead of main game\ndosctl run 62ef2769 game.exe -debug # Run with debug flag\ndosctl run 62ef2769 install.bat /q # Run batch file quietly\ndosctl run 62ef2769 editor.exe level1 # Run level editor with specific level\n```\n\n## Usage Examples\n\n### List only your installed games\n```bash\n$ dosctl list -i\nAvailable Games:\n [53ad2f67] (1991) Lemmings (1991)(Psygnosis Limited) [Strategy, Action]\n [fdcc9602] (1990) Secret of Monkey Island, The (VGA) (1990)(Lucasfilm Games LLC) [Adventure]\n```\n\n### Search for a game\n```bash\n$ dosctl search \"metal mutant\"\nFound 5 game(s):\n [dd228682] (1991) Metal Mutant (1991)(Silmarils) [Action, Adventure]\n [55123659] (1991) Metal Mutant (1991)(Silmarils) [Codes]\n [9a5aa0b6] (1991) Metal Mutant (Es) (1991)(Silmarils) [Action, Adventure]\n```\n\n### Run a game for the first time\n```bash\n$ dosctl run dd228682\nDownloading 'Metal Mutant (1991)(Silmarils) [Action, Adventure].zip'...\n\u2705 Successfully installed 'Metal Mutant (1991)(Silmarils) [Action, Adventure]'\nNo default executable set for game 'dd228682'. Searching...\nFound a single executable: 'METAL.EXE'. Setting as default.\nStarting 'METAL.EXE' with DOSBox...\n```\n\n### Run a specific executable directly\n```bash\n$ dosctl run dd228682 setup.exe\nStarting 'SETUP.EXE' with DOSBox...\n```\n\n### Run with command-line arguments\n```bash\n$ dosctl run dd228682 game.exe -difficulty hard -level 3\nStarting 'GAME.EXE -DIFFICULTY HARD -LEVEL 3' with DOSBox...\n```\n\n### Run main executable with required parameters\n```bash\n$ dosctl run dd228682 metal.exe soundblaster\nStarting 'METAL.EXE SOUNDBLASTER' with DOSBox...\n```\n\n### Force reconfiguration of saved executable\n```bash\n$ dosctl run dd228682 --configure\nPlease choose one of the following to run:\n 1: METAL.EXE\n 2: SETUP.EXE\n 3: README.BAT\nSelect a file to execute: 2\nStarting 'SETUP.EXE' with DOSBox...\n```\n\n### Inspect game files\n```bash\n$ dosctl inspect dd228682\nInspecting files for 'Metal Mutant (1991)(Silmarils) [Action, Adventure]' (ID: dd228682)\nLocation: <dosctl-data-dir>/installed/dd228682\n----------------------------------------\n METAL.EXE\n SETUP.EXE\n README.TXT\n DATA/LEVELS.DAT\n DATA/SOUNDS.DAT\n```\n\n### Show only executable files\n```bash\n$ dosctl inspect dd228682 --executables\nInspecting files for 'Metal Mutant (1991)(Silmarils) [Action, Adventure]' (ID: dd228682)\nLocation: <dosctl-data-dir>/installed/dd228682\n----------------------------------------\nExecutable files:\n METAL.EXE\n SETUP.EXE\n```\n\n## Commands\n\n* `dosctl list`\n * Lists all available games.\n * `-s, --sort-by [name|year]`: Sort the list by name or year.\n * `-i, --installed`: Only show games that are currently installed.\n\n* `dosctl search <query>`\n * Searches for games. The query is optional if `--year` is used.\n * `-y, --year <year>`: Filter by a specific year.\n * `-c, --case-sensitive`: Make the search case-sensitive.\n * `-s, --sort-by [name|year]`: Sort the results by name or year.\n\n* `dosctl run <game-id> [command-parts...]`\n * Runs a game. Downloads and installs it if necessary.\n * Prompts for an executable on the first run.\n * **Command Parts:** You can specify the exact DOS command to run instead of using the saved default.\n * `-c, --configure`: Force the interactive executable selection menu to appear.\n\n **Examples:**\n ```bash\n dosctl run 62ef2769 # Use saved/default executable\n dosctl run 62ef2769 --configure # Choose executable interactively\n dosctl run 62ef2769 setup.exe # Run specific executable\n dosctl run 62ef2769 game.exe -level 5 # Run with command-line arguments\n dosctl run 62ef2769 install.bat quiet # Run batch file with parameters\n ```\n\n* `dosctl inspect <game-id>`\n * Shows the list of installed files for a game.\n * `-e, --executables`: Show only executable files (.exe, .com, .bat).\n\n* `dosctl delete <game-id>`\n * Deletes an installed game and its files.\n\n* `dosctl refresh --force`\n * Forces a re-download of the master game list from the Internet Archive.\n\n## Configuration\n\n`dosctl` stores its data in platform-appropriate directories following OS conventions.\n\n### File Locations\n\n**Linux & macOS:**\n```\n~/.local/share/dosctl/\n\u251c\u2500\u2500 downloads/ # Downloaded game archives (.zip files)\n\u251c\u2500\u2500 installed/ # Extracted and installed games\n\u251c\u2500\u2500 collections/ # Game collection metadata cache\n\u251c\u2500\u2500 current_session.json\n\u2514\u2500\u2500 installations.json\n```\n\n**Windows:**\n```\n%USERPROFILE%\\AppData\\Local\\dosctl\\\n\u251c\u2500\u2500 downloads\\ # Downloaded game archives (.zip files)\n\u251c\u2500\u2500 installed\\ # Extracted and installed games\n\u251c\u2500\u2500 collections\\ # Game collection metadata cache\n\u251c\u2500\u2500 current_session.json\n\u2514\u2500\u2500 installations.json\n```\n\n**Examples:**\n- Linux: `/home/username/.local/share/dosctl/`\n- macOS: `/Users/username/.local/share/dosctl/`\n- Windows: `C:\\Users\\username\\AppData\\Local\\dosctl\\`\n\n### Storage Requirements\n\n- **downloads/**: Game archives (typically 1-50 MB each)\n- **installed/**: Extracted games (typically 2-100 MB each)\n- **collections/**: Metadata cache (~5 MB)\n\nPlan for several GB of storage if you install many games.\n\n## Collection Backend\n\nBy default, `dosctl` uses the [**Total DOS Collection Release 14**](https://archive.org/details/Total_DOS_Collection_Release_14) from the Internet Archive as its game collection source. This comprehensive collection contains thousands of DOS games from the 1980s and 1990s, all ready to download and play.\n\nThe collection includes:\n- Classic DOS games from various genres (adventure, action, strategy, RPG, etc.)\n- Games from major publishers like LucasArts, Sierra, id Software, and many others\n- Both well-known titles and obscure gems\n- Games in their original format, preserved for historical accuracy\n\nWhen you first run `dosctl list` or `dosctl search`, the tool will automatically download the complete game catalog from this collection. The games themselves are downloaded individually only when you choose to run them.\n\n## \u26a0\ufe0f Important Legal Disclaimer\n\n**Use at Your Own Risk**: This software is provided \"as is\" without any warranty. You are solely responsible for your actions when using this tool.\n\n**Content Responsibility**: This tool does not host or distribute any games. It only helps manage content you legally obtain elsewhere. You are responsible for:\n- Ensuring you have legal rights to any games you manage\n- Respecting copyright laws and software licenses\n- Any legal consequences of your usage\n\n**No Liability**: The author is not responsible for copyright infringement or any damages arising from use of this software.\n\n**Legal Compliance**: Ensure you have proper legal rights to any games or software you manage with this tool. Respect copyright laws and software licenses.\n\n## \u26a0\ufe0f Windows Support Notice\n\nWindows support is currently **experimental**. While the core functionality should work, it has not been extensively tested on Windows systems. Linux and macOS are the primary supported platforms.\n\nIf you encounter issues on Windows, please report them on GitHub. Contributions to improve Windows compatibility are welcome!\n",
"bugtrack_url": null,
"license": null,
"summary": "A command-line tool to manage and play DOS games via DOSBox.",
"version": "1.1.4",
"project_urls": {
"Homepage": "https://github.com/xesco/dosctl",
"Issues": "https://github.com/xesco/dosctl/issues",
"Source": "https://github.com/xesco/dosctl"
},
"split_keywords": [
"dos",
" games",
" retro",
" dosbox",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b3fe7e911027785d08b628ccee5ef525463fbd5029cca7d23f2df4efd5cd85a7",
"md5": "307b912beb6c60ea155d02c6c2e07416",
"sha256": "cbbd00e9811cdb47023f4610e540b429b1ca97f3fc78e951c36441c43bccad77"
},
"downloads": -1,
"filename": "dosctl-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "307b912beb6c60ea155d02c6c2e07416",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30226,
"upload_time": "2025-08-09T13:17:31",
"upload_time_iso_8601": "2025-08-09T13:17:31.861733Z",
"url": "https://files.pythonhosted.org/packages/b3/fe/7e911027785d08b628ccee5ef525463fbd5029cca7d23f2df4efd5cd85a7/dosctl-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b43b3e0bc7ec2dd19bcd2b7227b50d035a5e6891d1414a4f4a6f72b4adc130e9",
"md5": "1f65e76934f167c3d0d91ba638667338",
"sha256": "751715c7659deede9c2dbef78e0e8faf8ccad47b459b4cf3fff7effb4e1b297f"
},
"downloads": -1,
"filename": "dosctl-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "1f65e76934f167c3d0d91ba638667338",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31014,
"upload_time": "2025-08-09T13:17:33",
"upload_time_iso_8601": "2025-08-09T13:17:33.201804Z",
"url": "https://files.pythonhosted.org/packages/b4/3b/3e0bc7ec2dd19bcd2b7227b50d035a5e6891d1414a4f4a6f72b4adc130e9/dosctl-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 13:17:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xesco",
"github_project": "dosctl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dosctl"
}
