{"id":34026305,"url":"https://github.com/xesco/dosctl","last_synced_at":"2026-04-02T00:03:38.838Z","repository":{"id":308130748,"uuid":"1031552485","full_name":"xesco/dosctl","owner":"xesco","description":"A command-line tool to manage and play DOS games via DOSBox","archived":false,"fork":false,"pushed_at":"2026-03-22T22:10:08.000Z","size":2467,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T14:36:17.179Z","etag":null,"topics":["archive-org","cli","dos","dosbox","emulator","games","python","retro-gaming","total-dos-collection"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xesco.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T01:21:31.000Z","updated_at":"2026-03-22T22:10:11.000Z","dependencies_parsed_at":"2025-08-04T12:25:21.232Z","dependency_job_id":null,"html_url":"https://github.com/xesco/dosctl","commit_stats":null,"previous_names":["xesco/dosctl"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/xesco/dosctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xesco%2Fdosctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xesco%2Fdosctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xesco%2Fdosctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xesco%2Fdosctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xesco","download_url":"https://codeload.github.com/xesco/dosctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xesco%2Fdosctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293161,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["archive-org","cli","dos","dosbox","emulator","games","python","retro-gaming","total-dos-collection"],"created_at":"2025-12-13T17:00:30.422Z","updated_at":"2026-04-02T00:03:38.823Z","avatar_url":"https://github.com/xesco.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DOSCtl\n\nA command-line tool to manage and play DOS games via DOSBox.\n\n![DOSCtl Screenshot](dosctl-screenshot.png)\n\n## Installation\n\n**Requirements:** Python 3.8+, [DOSBox](https://www.dosbox.com/)\n\n```bash\n# Install DOSBox\nbrew install dosbox          # macOS\nsudo apt install dosbox      # Ubuntu/Debian\n\n# Install DOSCtl\npip install dosctl\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eOther install methods\u003c/summary\u003e\n\n```bash\n# From GitHub\npip install git+ssh://git@github.com/xesco/dosctl.git\n\n# Development (editable)\ngit clone git@github.com:xesco/dosctl.git\ncd dosctl\npip install -e \".[dev]\"\n```\n\u003c/details\u003e\n\n## Getting Started\n\n1. **List games** — the game catalog downloads automatically on first run:\n    ```bash\n    dosctl list\n    ```\n2. **Search** for a game:\n    ```bash\n    dosctl search \"Dune\" --sort-by year\n    ```\n3. **Play** a game by its ID. On first run, `dosctl` downloads, installs, and asks you to pick the executable:\n    ```bash\n    dosctl play \u003cgame-id\u003e\n    ```\n\n## Commands\n\nEvery game has a unique 8-character ID (shown in `list`/`search` output). Use it for all operations.\n\n### `dosctl list`\n\nLists all available games.\n\n| Flag | Description |\n|------|-------------|\n| `-s, --sort-by [name\\|year]` | Sort by name or year |\n| `-i, --installed` | Only show installed games |\n\n### `dosctl search \u003cquery\u003e`\n\nSearches for games. Query is optional if `--year` is used.\n\n| Flag | Description |\n|------|-------------|\n| `-y, --year \u003cyear\u003e` | Filter by year |\n| `-c, --case-sensitive` | Case-sensitive search |\n| `-s, --sort-by [name\\|year]` | Sort by name or year |\n\n### `dosctl play \u003cgame-id\u003e [command-parts...]`\n\nRuns a game. Downloads and installs it if needed. On first run, prompts for the main executable; the choice is saved for future runs.\n\n| Flag | Description |\n|------|-------------|\n| `-c, --configure` | Force re-selection of the default executable |\n| `-a, --floppy` | Also mount game directory as A: drive (for floppy-based installers) |\n| `-n, --no-exec` | Open DOSBox with the game directory mounted but don't run anything (for debugging) |\n\nYou can override the saved executable by passing command parts directly, or use `--configure` to re-pick interactively:\n\n```bash\ndosctl play 62ef2769                    # Use saved default\ndosctl play 62ef2769 --configure        # Re-pick executable interactively\ndosctl play 62ef2769 setup.exe          # Run a specific executable\ndosctl play 62ef2769 game.exe -level 5  # Pass arguments to the executable\n```\n\nSome 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:\n\n```bash\ndosctl play 62ef2769 install.bat C: -a  # Run installer with floppy mode\ndosctl play 62ef2769 STARCON2/GAME.EXE  # Then run the installed game normally\n```\n\nTo troubleshoot a game, open DOSBox at the game directory without running anything:\n\n```bash\ndosctl play 62ef2769 --no-exec          # Drop to C:\\\u003e prompt\ndosctl play 62ef2769 --no-exec -a       # Drop to A:\\\u003e prompt (floppy mode)\n```\n\n**Per-game DOSBox config:** if a `dosbox.conf` file exists in the game's install directory, it is automatically loaded by DOSBox (via `-conf`). Use it to override cycles, memory, sound settings, or any other DOSBox option for that specific game. The `net host` and `net join` commands honour the same file.\n\n### `dosctl inspect \u003cgame-id|alias\u003e`\n\nShows installed files for a game. Use `-e, --executables` to show only `.exe`/`.com`/`.bat` files.\n\n### `dosctl info \u003cgame-id|alias\u003e`\n\nShows catalog metadata and local status for a game: name, ID, release year, alias (if set), download/install status, install path, and the saved default executable.\n\n### `dosctl delete \u003cgame-id|alias\u003e`\n\nDeletes an installed game and its downloaded archive.\n\n### `dosctl refresh --force`\n\nRe-downloads the master game list from the Internet Archive.\n\n### `dosctl alias`\n\nManage short, memorable names (aliases) for game IDs. Aliases can be used in place of the 8-character ID in any command that accepts one (`play`, `inspect`, `info`, `delete`, `net host`, `net join`).\n\nAlias names must start with a letter or digit and contain only lowercase letters, digits, and hyphens.\n\n#### `dosctl alias set \u003calias\u003e \u003cgame-id\u003e`\n\nCreate or update an alias:\n\n```bash\ndosctl alias set doom 62ef2769\ndosctl play doom        # same as: dosctl play 62ef2769\n```\n\n#### `dosctl alias remove \u003calias\u003e`\n\nRemove an alias.\n\n#### `dosctl alias list`\n\nList all defined aliases.\n\n### `dosctl net host \u003cgame-id|alias\u003e`\n\nHosts a multiplayer game using DOSBox IPX networking. By default, hosts on your local network. Use `--internet` to enable internet play with automatic UPnP port mapping and a discovery code.\n\n| Flag | Description |\n|------|-------------|\n| `-p, --port \u003cport\u003e` | UDP port for the IPX server (default: 19900) |\n| `-c, --configure` | Force re-selection of the default executable |\n| `-i, --internet` | Enable internet play (UPnP port mapping + discovery code) |\n| `-I, --public-ip \u003cip\u003e` | Specify your public IP (skips automatic detection; requires `--internet`) |\n| `-U, --no-upnp` | Skip UPnP port mapping (requires `--internet`) |\n| `-n, --no-exec` | Open DOSBox with IPX server running but don't run anything (for debugging) |\n\n### `dosctl net join \u003cgame-id|alias\u003e \u003chost\u003e`\n\nJoins a multiplayer game hosted by another player. The host argument can be a raw IP address (for LAN) or a discovery code (for internet play).\n\n| Flag | Description |\n|------|-------------|\n| `-p, --port \u003cport\u003e` | UDP port of the IPX server (default: 19900) |\n| `-c, --configure` | Force re-selection of the default executable |\n\n**Example — LAN play:**\n\n```bash\n# Player 1 (host):\ndosctl net host 62ef2769\n# Output: \"Your local IP appears to be: 192.168.1.42\"\n\n# Player 2 (join with IP):\ndosctl net join 62ef2769 192.168.1.42\n```\n\n**Example — internet play:**\n\n```bash\n# Player 1 (host with internet mode):\ndosctl net host 62ef2769 --internet\n# Output: \"Your discovery code: DOOM-3KF8A\"\n\n# Player 2 (join with discovery code):\ndosctl net join 62ef2769 DOOM-3KF8A\n```\n\nIf UPnP fails or you've already forwarded the port manually:\n\n```bash\ndosctl net host 62ef2769 --internet --no-upnp --public-ip 203.0.113.5\n```\n\nBoth 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.\n\n## Configuration\n\nData is stored in platform-appropriate directories:\n\n| Platform | Config directory | Data directory |\n|----------|-----------------|----------------|\n| Linux | `~/.config/dosctl/` | `~/.local/share/dosctl/` |\n| macOS | `~/.local/share/dosctl/` | `~/.local/share/dosctl/` |\n| Windows | `%USERPROFILE%\\AppData\\Local\\dosctl\\` | `%USERPROFILE%\\AppData\\Local\\dosctl\\` |\n\n**Config directory** (settings and aliases):\n```\n\u003cconfig-dir\u003e/\n  aliases.json     # Saved game aliases\n  ipx.conf         # DOSBox IPX networking config (auto-generated)\n```\n\n**Data directory** (game files):\n```\n\u003cdata-dir\u003e/\n  downloads/       # Downloaded .zip archives\n  installed/       # Extracted games\n    \u003cgame-id\u003e/     # Game install directory\n      dosbox.conf  # Optional per-game DOSBox config\n  collections/     # Game list cache\n```\n\n## Collection Backend\n\nGames are sourced from the [Total DOS Collection Release 14](https://archive.org/details/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.\n\n## Disclaimer\n\nThis 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.\n\nSee [LICENSE](LICENSE) for the full MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxesco%2Fdosctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxesco%2Fdosctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxesco%2Fdosctl/lists"}