RGSX/README_CLI.md

RGSX CLI — Guide d’utilisation

Ce guide couvre toutes les commandes disponibles du CLI et fournit des exemples prêts à copier (Windows PowerShell).

Nouveau: mode interactif

Vous pouvez maintenant lancer une session interactive et enchaîner les commandes sans retaper python rgsx_cli.py à chaque fois :

python rgsx_cli.py

Vous verrez :

RGSX CLI interactive mode. Type 'help' for commands, 'exit' to quit.
rgsx>

Dans cette session tapez directement les sous-commandes :

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 ou ? affiche l’aide globale.
• exit ou quit quitte la session.
• --verbose une fois active les logs détaillés pour toute la session.

Tableau formaté (platforms)

La commande platforms affiche maintenant un tableau ASCII à largeur fixe (sauf avec --json) :

+--------------------------------+-----------------+
| Nom de plateforme              | Dossier         |
+--------------------------------+-----------------+
| Nintendo Entertainment System  | nes             |
| Super Nintendo Entertainment.. | snes            |
| Sega Mega Drive                | megadrive       |
+--------------------------------+-----------------+

Colonnes : 30 caractères pour le nom, 15 pour le dossier (troncature par ...).

Aliases & synonymes d’options (mis à jour)

Aliases des sous-commandes :

• platforms → p
• games → g
• download → dl
• clear-history → clear

Options équivalentes (toutes les formes listées sont acceptées) :

• Plateforme : --platform, --p, -p
• Jeu : --game, --g, -g
• Recherche : --search, --s, -s
• Forcer (download) : --force, -f
• Mode interactif (download) : --interactive, -i

Exemples avec alias :

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

Sélection ambiguë lors d’un download (nouveau tableau)

Quand vous tentez un téléchargement avec un titre non exact et que le mode interactif est actif (TTY ou --interactive), les correspondances s’affichent en tableau :

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):

Si vous annulez ou que le mode interactif n’est pas actif, un tableau similaire est affiché (sans le prompt) suivi d’un conseil.

Recherche améliorée (multi‑tokens) pour games

L’option --search / --s / -s utilise maintenant la même logique de classement que les suggestions du download :

1. Correspondance sous-chaîne (position la plus tôt) — priorité 0
2. Séquence de tokens dans l’ordre (non contiguë) — priorité 1 (écart le plus faible)
3. Tous les tokens présents dans n’importe quel ordre — priorité 2 (ensemble de tokens plus petit privilégié)

Les doublons sont dédupliqués en gardant le meilleur score. Ainsi une requête :

python rgsx_cli.py games --p snes --s "super mario yoshi"

affiche toutes les variantes pertinentes de "Super Mario World 2 - Yoshi's Island" même si l’ordre des mots diffère.

Exemple de sortie :

+--------------------------------------------------------------+------------+
| 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       |
+--------------------------------------------------------------+------------+

Si aucun résultat n’est trouvé, seul l’en-tête est affiché puis un message.

Prérequis

• Python installé et accessible (le projet utilise un mode headless; aucune fenêtre ne s’ouvrira).
• Exécuter depuis le dossier contenant rgsx_cli.py.

Syntaxe générale (mode classique)

Les options globales peuvent être placées avant ou après la sous-commande.

• Forme 1:

  python rgsx_cli.py [--verbose] [--force-update|-force-update] <commande> [options]
  

• Forme 2:

  python rgsx_cli.py <commande> [options] [--verbose] [--force-update|-force-update]
  

• --verbose active les logs détaillés (DEBUG) sur stderr.

• --force-update (ou -force-update) purge les données locales et force le re-téléchargement du pack de données (systems_list, games/*.json, images).

Quand les données sources sont manquantes, le CLI télécharge et extrait automatiquement le pack (avec progression).

Commandes

1) platforms (platforms / p) — lister les plateformes

• Options:
  • --json: sortie JSON (objets { name, folder }).

Exemples:

python rgsx_cli.py platforms
python rgsx_cli.py p --json
python rgsx_cli.py --verbose p
python rgsx_cli.py p --verbose

Sortie texte: une ligne par plateforme, au format Nom<TAB>Dossier.

2) games (games / g) — lister les jeux d’une plateforme

• Options:
  • --platform | --p | -p <nom_ou_dossier> (ex: n64 ou "Nintendo 64").
  • --search | --s | -s <texte>: filtre par sous-chaîne.

Exemples:

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

Remarques:

• La plateforme est résolue par nom affiché (platform_name) ou dossier, insensible à la casse.

3) download (download / dl) — télécharger un jeu

• Options:
  • --platform | --p | -p <nom_ou_dossier>
  • --game | --g | -g "<titre exact ou partiel>"
  • --force | -f: ignorer l’avertissement d’extension non supportée.
  • --interactive | -i: choisir un titre parmi des correspondances quand aucun exact n’est trouvé.

Exemples:

# Titre exact
python rgsx_cli.py dl --p n64 --g "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip"

# Titre partiel (sélection numérotée si aucun exact)
python rgsx_cli.py dl -p n64 -g "Ocarina of Time (Beta)"

# Forcer malgré extension
python rgsx_cli.py dl -p snes -g "pack_roms.rar" -f

# Verbose après sous-commande
python rgsx_cli.py dl -p n64 -g "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip" --verbose

Pendant le téléchargement: progression %, taille (MB), vitesse (MB/s). Résultat final aussi dans l’historique.

Notes:

• Les ROMs sont enregistrées dans le dossier plateforme correspondant (ex: R:\roms\n64).
• Si le fichier est une archive (zip/rar) et que la plateforme ne supporte pas l’extension, un avertissement apparaît (utiliser --force).

4) history — afficher l’historique

• Options:
  • --tail <N>: n dernières entrées (défaut: 50)
  • --json: sortie JSON

Exemples:

python rgsx_cli.py history
python rgsx_cli.py history --tail 20
python rgsx_cli.py history --json

5) clear-history (clear-history / clear) — vider l’historique

Exemple:

python rgsx_cli.py clear

Option globale: --force-update — purge + re-téléchargement des données

• Supprime systems_list.json, games/, images/ puis retélécharge/extrait le pack.

Exemples:

python rgsx_cli.py --force-update
python rgsx_cli.py p --force-update

Comportements et conseils

• Résolution plateforme: par nom affiché ou dossier, insensible à la casse.
• --verbose: utile surtout pour téléchargements/extractions.
• Données manquantes: téléchargement + extraction automatiques.
• Codes de sortie (indicatif):
  • 0: succès
  • 1: échec téléchargement/erreur générique
  • 2: plateforme introuvable
  • 3: jeu introuvable
  • 4: extension non supportée (sans --force)

Exemples rapides (copier-coller)

# Démarrer le shell interactif
python rgsx_cli.py

# Lister plateformes (alias)
python rgsx_cli.py p

# Lister plateformes (JSON)
python rgsx_cli.py p --json

# Lister jeux N64 avec filtre (synonymes)
python rgsx_cli.py g --p n64 --s zelda

# Télécharger un jeu N64 (titre exact) avec alias
python rgsx_cli.py dl --p n64 --g "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip"

# Télécharger (titre partiel) + sélection
python rgsx_cli.py dl -p n64 -g "Ocarina of Time"

# Historique (20 dernières entrées)
python rgsx_cli.py history --tail 20

# Purger et recharger le pack
python rgsx_cli.py --force-update