forked from Mirrors/RGSX
45f5d8bf7b
- add new instructions on menus to describe each function - upgrade controller_debug.pygame file to create a controller support - update command-line interface to be more effiscient and readable
255 lines
9.2 KiB
Markdown
255 lines
9.2 KiB
Markdown
# RGSX CLI — Usage Guide
|
||
|
||
This guide covers all available CLI commands with copy-ready Windows PowerShell examples.
|
||
|
||
## Prerequisites
|
||
- Python installed and on PATH (the app runs in headless mode; no window will open).
|
||
- Run commands from the folder that contains `rgsx_cli.py`.
|
||
|
||
## Quick interactive mode (new)
|
||
You can now start an interactive shell once and issue multiple commands without retyping `python rgsx_cli.py` each time:
|
||
|
||
```powershell
|
||
python rgsx_cli.py
|
||
```
|
||
You will see a prompt like:
|
||
```
|
||
RGSX CLI interactive mode. Type 'help' for commands, 'exit' to quit.
|
||
rgsx>
|
||
```
|
||
Inside this shell type subcommands exactly as you would after `python rgsx_cli.py`:
|
||
```
|
||
rgsx> platforms
|
||
rgsx> games --platform snes --search mario
|
||
rgsx> download --platform snes --game "Super Mario World (USA).zip"
|
||
rgsx> history --tail 10
|
||
rgsx> exit
|
||
```
|
||
Extras:
|
||
- `help` or `?` prints the global help.
|
||
- `exit` or `quit` leaves the shell.
|
||
- `--verbose` once sets persistent verbose logging for the rest of the session.
|
||
|
||
## Formatted table output (platforms)
|
||
The `platforms` command now renders a fixed-width ASCII table (unless `--json` is used):
|
||
```
|
||
+--------------------------------+-----------------+
|
||
| Platform Name | Folder |
|
||
+--------------------------------+-----------------+
|
||
| Nintendo Entertainment System | nes |
|
||
| Super Nintendo Entertainment.. | snes |
|
||
| Sega Mega Drive | megadrive |
|
||
+--------------------------------+-----------------+
|
||
```
|
||
Columns: 30 chars for name, 15 for folder (values longer are truncated with `...`).
|
||
|
||
## Aliases & option synonyms (updated)
|
||
Subcommand aliases:
|
||
- `platforms` → `p`
|
||
- `games` → `g`
|
||
- `download` → `dl`
|
||
- `clear-history` → `clear`
|
||
|
||
Option aliases (all shown forms are accepted; they are equivalent):
|
||
- Platform: `--platform`, `--p`, `-p`
|
||
- Game: `--game`, `--g`, `-g`
|
||
- Search: `--search`, `--s`, `-s`
|
||
- Force (download): `--force`, `-f`
|
||
- Interactive (download): `--interactive`, `-i`
|
||
|
||
Examples with aliases:
|
||
```powershell
|
||
python rgsx_cli.py dl -p snes -g "Super Mario World (USA).zip"
|
||
python rgsx_cli.py g --p snes --s mario
|
||
python rgsx_cli.py p --json
|
||
python rgsx_cli.py clear
|
||
```
|
||
|
||
## Ambiguous download selection (new table)
|
||
When you attempt a download with a non-exact title and interactive mode is active (TTY or `--interactive`), matches are displayed in a table:
|
||
```
|
||
No exact result found for this game: mario super yoshi
|
||
Select a match to download:
|
||
+------+--------------------------------------------------------------+------------+
|
||
| # | Title | Size |
|
||
+------+--------------------------------------------------------------+------------+
|
||
| 1 | Super Mario - Yoshi Island (Japan).zip | 3.2M |
|
||
| 2 | Super Mario - Yoshi Island (Japan) (Rev 1).zip | 3.2M |
|
||
| 3 | Super Mario - Yoshi Island (Japan) (Rev 2).zip | 3.2M |
|
||
| 4 | Super Mario World 2 - Yoshi's Island (USA).zip | 3.3M |
|
||
| 5 | Super Mario - Yoshi Island (Japan) (Beta) (1995-07-10).zip | 3.1M |
|
||
+------+--------------------------------------------------------------+------------+
|
||
Enter number (or press Enter to cancel):
|
||
```
|
||
If you cancel or are not in interactive mode, a similar table is still shown (without the prompt) followed by a tip.
|
||
|
||
## Improved fuzzy search for games (multi-token)
|
||
The `--search` / `--s` / `-s` option now uses the same multi-strategy ranking as the download suggestion logic:
|
||
1. Substring match (position-based) — highest priority
|
||
2. Ordered non-contiguous token sequence (smallest gap wins)
|
||
3. All tokens present in any order (smaller token set size wins)
|
||
|
||
Duplicate titles are deduplicated by keeping the best scoring strategy. This means queries like:
|
||
```powershell
|
||
python rgsx_cli.py games --p snes --s "super mario yoshi"
|
||
```
|
||
will surface all relevant "Super Mario World 2 - Yoshi's Island" variants even if the word order differs.
|
||
|
||
Example output:
|
||
```
|
||
+--------------------------------------------------------------+------------+
|
||
| Game Title | Size |
|
||
+--------------------------------------------------------------+------------+
|
||
| Super Mario World 2 - Yoshi's Island (USA).zip | 3.3M |
|
||
| Super Mario World 2 - Yoshi's Island (Europe) (En,Fr,De).zip | 3.3M |
|
||
| Super Mario - Yoshi Island (Japan).zip | 3.2M |
|
||
| Super Mario - Yoshi Island (Japan) (Rev 1).zip | 3.2M |
|
||
| Super Mario - Yoshi Island (Japan) (Rev 2).zip | 3.2M |
|
||
+--------------------------------------------------------------+------------+
|
||
```
|
||
If no results are found the table displays only headers followed by a message.
|
||
|
||
## General syntax (non-interactive)
|
||
Global options can be placed before or after the subcommand.
|
||
|
||
- Form 1:
|
||
```powershell
|
||
python rgsx_cli.py [--verbose] [--force-update|-force-update] <command> [options]
|
||
```
|
||
- Form 2:
|
||
```powershell
|
||
python rgsx_cli.py <command> [options] [--verbose] [--force-update|-force-update]
|
||
```
|
||
|
||
- `--verbose` enables detailed logs (DEBUG) on stderr.
|
||
- `--force-update` (or `-force-update`) purges local data and re-downloads the data pack (systems_list, games/*.json, images).
|
||
|
||
When source data is missing, the CLI will automatically download and extract the data pack (with progress).
|
||
|
||
## Commands
|
||
|
||
### 1) platforms (`platforms` / `p`) — list platforms
|
||
- Options:
|
||
- `--json`: JSON output (objects `{ name, folder }`).
|
||
|
||
Examples:
|
||
```powershell
|
||
python rgsx_cli.py platforms
|
||
python rgsx_cli.py p --json
|
||
python rgsx_cli.py --verbose p
|
||
python rgsx_cli.py p --verbose
|
||
```
|
||
|
||
Text output: one line per platform, formatted as `Name<TAB>Folder`.
|
||
|
||
### 2) games (`games` / `g`) — list games for a platform
|
||
- Options:
|
||
- `--platform | --p | -p <name_or_folder>` (e.g., `n64` or "Nintendo 64").
|
||
- `--search | --s | -s <text>`: filter by substring in game title.
|
||
|
||
Examples:
|
||
```powershell
|
||
python rgsx_cli.py games --platform n64
|
||
python rgsx_cli.py g --p "Nintendo 64" --s zelda
|
||
python rgsx_cli.py g -p n64 --verbose
|
||
```
|
||
|
||
Notes:
|
||
- The platform is resolved by display name (platform_name) or folder, case-insensitively.
|
||
|
||
### 3) download (`download` / `dl`) — download a game
|
||
- Options:
|
||
- `--platform | --p | -p <name_or_folder>`
|
||
- `--game | --g | -g "<exact or partial title>"`
|
||
- `--force | -f`: ignore unsupported-extension warning for the platform.
|
||
- `--interactive | -i`: prompt to choose from matches when no exact title is found.
|
||
|
||
Examples:
|
||
```powershell
|
||
# Exact title
|
||
python rgsx_cli.py dl --p n64 --g "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip"
|
||
|
||
# Partial match (interactive numbered selection if no exact match)
|
||
python rgsx_cli.py dl -p n64 -g "Ocarina of Time (Beta)"
|
||
|
||
# Forced despite extension
|
||
python rgsx_cli.py dl -p snes -g "pack_roms.rar" -f
|
||
|
||
# Verbose after subcommand
|
||
python rgsx_cli.py dl -p n64 -g "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip" --verbose
|
||
```
|
||
|
||
During download, progress %, size (MB) and speed (MB/s) are shown. The final result is also written to history.
|
||
|
||
Notes:
|
||
- ROMs are saved into the corresponding platform directory (e.g., `R:\roms\n64`).
|
||
- If the file is an archive (zip/rar) and the platform doesn’t support that extension, a warning is shown (you can use `--force`).
|
||
|
||
### 4) history — show history
|
||
- Options:
|
||
- `--tail <N>`: last N entries (default: 50)
|
||
- `--json`: JSON output
|
||
|
||
Examples:
|
||
```powershell
|
||
python rgsx_cli.py history
|
||
python rgsx_cli.py history --tail 20
|
||
python rgsx_cli.py history --json
|
||
```
|
||
|
||
### 5) clear-history (`clear-history` / `clear`) — clear history
|
||
Example:
|
||
```powershell
|
||
python rgsx_cli.py clear
|
||
```
|
||
|
||
### Global option: --force-update — purge + re-download data
|
||
- Removes `systems_list.json`, the `games/` and `images/` folders, then downloads/extracts the data pack again.
|
||
|
||
Examples:
|
||
```powershell
|
||
# Without subcommand: purge + re-download then exit
|
||
python rgsx_cli.py --force-update
|
||
|
||
# Placed after a subcommand (also accepted)
|
||
python rgsx_cli.py p --force-update
|
||
```
|
||
|
||
## Behavior and tips
|
||
- Platform resolution: by display name or folder, case-insensitive. For `games` and `download`, if no exact match is found a search-like suggestion list is shown.
|
||
- `--verbose` logs: most useful during downloads/extraction; printed at DEBUG level.
|
||
- Missing data download: automatic, with consistent progress (download then extraction).
|
||
- Exit codes (indicative):
|
||
- `0`: success
|
||
- `1`: download failure/generic error
|
||
- `2`: platform not found
|
||
- `3`: game not found
|
||
- `4`: unsupported extension (without `--force`)
|
||
|
||
## Quick examples (copy/paste)
|
||
```powershell
|
||
# Start interactive shell
|
||
python rgsx_cli.py
|
||
|
||
# List platforms (text)
|
||
python rgsx_cli.py p
|
||
|
||
# List platforms (JSON)
|
||
python rgsx_cli.py p --json
|
||
|
||
# List N64 games with filter (using alias synonyms)
|
||
python rgsx_cli.py g --p n64 --s zelda
|
||
|
||
# Download an N64 game (exact title) using aliases
|
||
python rgsx_cli.py dl --p n64 --g "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip"
|
||
|
||
# Download with approximate title (suggestions + interactive pick)
|
||
python rgsx_cli.py dl -p n64 -g "Ocarina of Time"
|
||
|
||
# View last 20 history entries
|
||
python rgsx_cli.py history --tail 20
|
||
|
||
# Purge and refresh data pack
|
||
python rgsx_cli.py --force-update
|
||
```
|