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

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

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 la sortie standard d’erreur.

• --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).

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

Commandes

1) platforms — lister les plateformes

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

Exemples:

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

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

2) games — lister les jeux d’une plateforme

• Options:
  • --platform <nom_ou_dossier> (ex: n64 ou "Nintendo 64").
  • --search <texte>: filtre par sous-chaîne dans le nom du jeu.

Exemples:

python rgsx_cli.py games --platform n64
python rgsx_cli.py games --platform "Nintendo 64" --search zelda
python rgsx_cli.py games --platform n64 --verbose

Remarques:

• La plateforme est résolue par nom affiché (platform_name) ou par dossier (folder), sans tenir compte de la casse.

3) download — télécharger un jeu

• Options:
  • --platform <nom_ou_dossier>
  • --game "<titre exact ou partiel>"
  • --force: ignorer l’avertissement si l’extension du fichier n’est pas répertoriée comme supportée pour la plateforme.

Exemples:

# Titre exact
python rgsx_cli.py download --platform n64 --game "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip"

# Correspondance partielle
# Si aucun titre exact n’est trouvé, le CLI n’autosélectionne plus. Il affiche des correspondances possibles.
python rgsx_cli.py download --platform n64 --game "Ocarina of Time (Beta)"
# ➜ Le CLI proposera une liste de titres potentiels (à relancer ensuite avec le titre exact).

Mode interactif par défaut:
- Si aucun titre exact n’est trouvé et que vous êtes dans un terminal interactif (TTY), une liste numérotée s’affiche automatiquement pour choisir un match et lancer le téléchargement.

# Forcer si l’extension semble non supportée (ex: .rar)
python rgsx_cli.py download --platform snes --game "pack_roms.rar" --force

# Verbose positionné après la sous-commande
python rgsx_cli.py download --platform n64 --game "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip" --verbose

Pendant le téléchargement, une progression en pourcentage, taille (MB) et vitesse (MB/s) s’affiche. Le résultat final est également écrit dans l’historique.

Notes:

• Les ROMs sont enregistrées dans le dossier de la plateforme correspondante (ex: R:\roms\n64).
• Si le fichier est une archive (zip/rar) et que la plateforme ne supporte pas l’extension, un avertissement est affiché (vous pouvez 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 — vider l’historique

Exemple:

python rgsx_cli.py clear-history

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

• Supprime systems_list.json, le dossier games/ et images/, puis télécharge/extrait à nouveau le pack de données.

Exemples:

# Sans sous-commande: purge + re-téléchargement puis sortie
python rgsx_cli.py --force-update

# Placé après une sous-commande (accepté aussi)
python rgsx_cli.py platforms --force-update

Comportements et conseils

• Résolution de plateforme: par nom affiché ou dossier, insensible à la casse. Pour la commande games et download, une recherche par sous-chaîne est utilisée si la correspondance exacte n’est pas trouvée.
• Logs --verbose: principalement utiles lors des téléchargements/extractions; émis en DEBUG.
• Téléchargement de données manquantes: automatique avec progression harmonisée (téléchargement puis extraction).
• Codes de sortie (indicatif):
  • 0: succès
  • 1: échec du téléchargement/erreur générique
  • 2: plateforme introuvable
  • 3: jeu introuvable
  • 4: extension non supportée (sans --force)

Exemples rapides (copier-coller)

# Lister plateformes (texte)
python rgsx_cli.py platforms

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

# Lister jeux N64 avec filtre
python rgsx_cli.py games --platform n64 --search zelda

# Télécharger un jeu N64 (titre exact)
python rgsx_cli.py download --platform n64 --game "Legend of Zelda, The - Ocarina of Time (USA) (Beta).zip"

# Télécharger un jeu N64 (titre aproximatif)
python rgsx_cli.py download --platform n64 --game "Ocarina of Time"
Resultat (exemple) : 
No exact result found for this game: Ocarina of Time
Select a match to download:
  1. Legend of Zelda, The - Ocarina of Time (Europe) (Beta) (2003-02-13) (GameCube).zip
  2. Legend of Zelda, The - Ocarina of Time (Europe) (Beta) (2003-02-21) (GameCube) (Debug).zip
  ...
  15. F-Zero X (USA) (Beta) (The Legend of Zelda - Ocarina of Time leftover data).zip

# Voir l’historique (20 dernières entrées)
python rgsx_cli.py history --tail 20

# Purger et recharger les données de listes des systèmes et des jeux
python rgsx_cli.py --force-update