6. Διεπαφή γραμμής εντολών (CLI)

6.1. Εισαγωγή

Το blunderDB περιλαμβάνει μια πλήρη διεπαφή γραμμής εντολών (CLI) στο ίδιο εκτελέσιμο με τη γραφική διεπαφή. Η CLI είναι ιδιαίτερα χρήσιμη για:

τη μαζική εισαγωγή αγώνων: εισαγωγή ενός ολόκληρου καταλόγου αρχείων αγώνων (XG, SGF, MAT, BGF…) με μία μόνο εντολή,
την αυτοματοποίηση: ενσωμάτωση του blunderDB σε σενάρια κελύφους για τακτικά αντίγραφα ασφαλείας, προγραμματισμένες εξαγωγές ή αλυσίδες επεξεργασίας,
τη χρήση σε διακομιστή: διαχείριση βάσεων δεδομένων σε μηχανήματα χωρίς γραφικό περιβάλλον,
τη γρήγορη επιθεώρηση: έλεγχος του περιεχομένου ή της ακεραιότητας μιας βάσης δεδομένων χωρίς εκκίνηση της γραφικής διεπαφής.

Η CLI χρησιμοποιεί ακριβώς την ίδια μορφή βάσης δεδομένων με τη γραφική διεπαφή. Κάθε ενέργεια που εκτελείται μέσω της CLI είναι αμέσως ορατή στη γραφική διεπαφή και αντιστρόφως.

6.2. Γενική σύνταξη

Η λειτουργία ανιχνεύεται αυτόματα: αν το πρώτο όρισμα είναι μια εντολή CLI, το blunderDB εκκινεί σε λειτουργία χωρίς γραφικό περιβάλλον (headless), διαφορετικά εκκινεί τη γραφική διεπαφή.

# Mode graphique (aucun argument)
./blunderdb

# Mode CLI
./blunderdb <commande> [options]

6.3. Διαθέσιμες εντολές

Εντολή	Περιγραφή
create	Δημιουργεί μια νέα βάση δεδομένων.
import	Εισάγει δεδομένα (αγώνας, θέση, παρτίδα).
export	Εξάγει δεδομένα.
identity	Affiche ou déplace l’identité d’émetteur (clé de signature des filigranes).
open	Transforme un fichier protégé par mot de passe (.dbx) en base ordinaire.
search	Αναζητά θέσεις με φίλτρα.
list	Εμφανίζει το περιεχόμενο της βάσης.
match	Εμφανίζει τις θέσεις και τις αναλύσεις ενός αγώνα.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Εμφανίζει τα μεταδεδομένα της βάσης.
edit	Τροποποιεί τα μεταδεδομένα της βάσης.
verify	Ελέγχει την ακεραιότητα της βάσης.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Διαγράφει δεδομένα.
help	Εμφανίζει τη βοήθεια.
version	Εμφανίζει την έκδοση.

Κάθε εντολή δέχεται την επιλογή --help για την εμφάνιση της λεπτομερούς βοήθειάς της.

6.4. create — Δημιουργία βάσης δεδομένων

Δημιουργεί ένα νέο αρχείο βάσης δεδομένων με προαιρετικά μεταδεδομένα.

./blunderdb create --db <chemin> [--user <nom>] [--description <texte>] [--force]

Επιλογές:

--db — Διαδρομή του αρχείου βάσης δεδομένων προς δημιουργία (υποχρεωτικό).
--user — Όνομα του κατόχου της βάσης.
--description — Περιγραφή της βάσης.
--force — Αντικατάσταση του αρχείου αν υπάρχει ήδη.

Η επέκταση .db προστίθεται αυτόματα αν λείπει. Οι γονικοί κατάλογοι δημιουργούνται όταν χρειάζεται.

Παράδειγμα:

./blunderdb create --db mes_matchs.db --user "Jean" --description "Matchs de tournoi 2025"

6.5. import — Εισαγωγή δεδομένων

Εισάγει αρχεία αγώνων ή θέσεων στη βάση δεδομένων.

./blunderdb import --db <chemin> --type <type> [options]

Επιλογές:

--db — Διαδρομή της βάσης δεδομένων (υποχρεωτικό).
--type — Τύπος εισαγωγής: match, position ή batch (υποχρεωτικό).
--file — Αρχείο προς εισαγωγή (για match και position).
--dir — Κατάλογος προς εισαγωγή (για batch).
--recursive — Αναδρομική σάρωση των υποκαταλόγων (προεπιλογή: ναι).

6.5.1. Εισαγωγή αγώνα

Υποστηριζόμενες μορφές: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) και BGBlitz (.bgf).

./blunderdb import --db base.db --type match --file match.xg

6.5.2. Εισαγωγή θέσεων

Εισάγει θέσεις από ένα αρχείο κειμένου (μία θέση JSON ανά γραμμή):

./blunderdb import --db base.db --type position --file positions.txt

6.5.3. Μαζική εισαγωγή

Εισάγει όλα τα αρχεία αγώνων ενός καταλόγου σε μία μόνο ενέργεια. Είναι η πιο αποδοτική μέθοδος για την εισαγωγή μεγάλου αριθμού αγώνων.

# Import récursif (par défaut)
./blunderdb import --db base.db --type batch --dir ./matchs/

# Import non récursif
./blunderdb import --db base.db --type batch --dir ./matchs/ --recursive=false

Ένας συνοπτικός πίνακας δείχνει για κάθε αρχείο αν η εισαγωγή πέτυχε (✓), απέτυχε (✗) ή επρόκειτο για διπλότυπο (⊘).

6.6. export — Εξαγωγή δεδομένων

Εξάγει το περιεχόμενο της βάσης σε αρχεία.

./blunderdb export --db <chemin> --type <type> --file <sortie> [options]

Επιλογές:

--db — Βάση προέλευσης (υποχρεωτικό).
--type — Τύπος εξαγωγής: database, positions, matches ή mat (εξαγωγή ενός ή περισσότερων αγώνων σε μεταγραφή Jellyfish .mat) (υποχρεωτικό).
--file — Αρχείο εξόδου (υποχρεωτικό, εκτός από το --type mat που χρησιμοποιείται με το --dir).
--dir — Κατάλογος εξόδου για την ομαδική εξαγωγή .mat (πολλοί αγώνες, ένα αρχείο ανά αγώνα· χωρίς --match-ids, εξάγονται όλοι οι αγώνες).
--analysis — Συμπερίληψη των αναλύσεων (προεπιλογή: ναι).
--comments — Συμπερίληψη των σχολίων (προεπιλογή: ναι).
--filters — Συμπερίληψη της βιβλιοθήκης φίλτρων (προεπιλογή: ναι).
--played-moves — Συμπερίληψη των παιγμένων κινήσεων (προεπιλογή: ναι).
--matches — Συμπερίληψη των αγώνων (προεπιλογή: ναι).
--collections — Συμπερίληψη των συλλογών (προεπιλογή: όχι).
--collection-ids — IDs συλλογών προς εξαγωγή (χωρισμένα με κόμματα).
--match-ids — IDs αγώνων προς εξαγωγή (χωρισμένα με κόμματα, κενό = όλα).
--tournament-ids — IDs τουρνουά προς εξαγωγή (χωρισμένα με κόμματα).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Διανομή μιας βάσης: προέλευση και κωδικός πρόσβασης).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Παραδείγματα:

# Export complet de la base
./blunderdb export --db base.db --type database --file sauvegarde.db

# Export des positions en JSON
./blunderdb export --db base.db --type positions --file positions.txt

# Export de matchs spécifiques
./blunderdb export --db base.db --type matches --file selection.db --match-ids 1,3,5

# Export d'un match en transcription .mat (Jellyfish)
./blunderdb export --db base.db --type mat --match-ids 5 --file match5.mat

# Export de plusieurs matchs (ou de tous) en .mat dans un répertoire
./blunderdb export --db base.db --type mat --match-ids 5,9,12 --dir sorties/
./blunderdb export --db base.db --type mat --dir sorties/

# Export filigrané et protégé par mot de passe (fichier .dbx)
./blunderdb export --db cours.db --type database --file cours-diffusion.dbx \
    --watermark "Cours de Jean Dupont — 12 mars 2026" \
    --watermark-note "Merci de ne pas rediffuser." \
    --password secret

Un filigrane est signé avec l’identité d’émetteur locale (voir la commande identity ci-dessous) : il est infalsifiable, mais pas inamovible — le fichier reste une base SQLite ordinaire. Il ne protège rien, il indique seulement d’où vient le fichier. Un mot de passe protège le transport du fichier (la copie égarée, la pièce jointe envoyée par erreur), pas la base elle-même : quiconque a reçu le mot de passe peut l’ouvrir. blunderDB n’enregistre jamais rien côté destinataire (aucun registre, aucun journal) — voir docs/adr/0007-watermarks-mark-origin-and-nothing-else.md.

6.7. identity — Identité d’émetteur

Affiche ou déplace votre identité d’émetteur : la clé Ed25519 qui signe chaque filigrane. Elle est créée d’elle-même au premier filigrane apposé ; il n’y a rien à configurer. Elle appartient à une personne, pas à une base de données : tout ce que vous marquez porte une seule empreinte publique.

./blunderdb identity                                       # nom et empreinte
./blunderdb identity --name "Jean Dupont"                  # renommer
./blunderdb identity --export jean.bdbid --passphrase pw   # exporter vers une autre machine
./blunderdb identity --import jean.bdbid --passphrase pw

Επιλογές:

--name — Change le nom affiché de l’identité.
--export — Exporte l’identité vers un fichier .bdbid.
--import — Importe une identité depuis un fichier .bdbid.
--passphrase — Phrase de passe optionnelle protégeant le fichier exporté/importé (l’identité locale, elle, est volontairement non protégée).

Le fichier exporté permet à quiconque le détient de signer en votre nom — ne le partagez pas. Renommer ne change qu’un libellé : les fichiers déjà marqués conservent le nom sous lequel ils ont été scellés, et continuent de se vérifier.

6.8. open — Ouvrir un fichier protégé

Transforme un fichier protégé par mot de passe (.dbx) en base ordinaire. Le mot de passe est demandé une seule fois ; ensuite, c’est un fichier normal.

./blunderdb open --db cours.dbx --password secret
./blunderdb open --db cours.dbx --password secret --file ./mon-cours.db

Επιλογές:

--db — Fichier .dbx à ouvrir (obligatoire).
--password — Mot de passe du conteneur (obligatoire).
--file — Chemin de sortie pour la base ordinaire (défaut: même nom, extension .db).

Ce que le mot de passe protège : le transport du fichier — la copie égarée dans un dossier de téléchargements, la pièce jointe envoyée par erreur. Pas la base : quiconque a reçu le mot de passe peut l’ouvrir. L’en-tête du conteneur est en clair, si bien que blunderdb info lit l’origine d’un fichier protégé sans son mot de passe.

6.9. search — Αναζήτηση θέσεων

Αναζητά θέσεις στη βάση σύμφωνα με συνδυάσιμα κριτήρια.

./blunderdb search --db <chemin> [options]

Κύριες επιλογές:

--db — Βάση δεδομένων (υποχρεωτικό).
--format — Μορφή εξόδου: table, json ή xgid (προεπιλογή: table).
--limit — Μέγιστος αριθμός αποτελεσμάτων (0 = απεριόριστα).
--export — Εξαγωγή των αποτελεσμάτων σε μια νέα βάση.

Διαθέσιμα φίλτρα:

--decision — Τύπος απόφασης: checker ή cube.
--dice — Ζαριά. Το 5,3 αναζητά τις θέσεις όπου ταιριάζουν και τα δύο ζάρια (ανεξαρτήτως σειράς). Το 5 αναζητά τις θέσεις όπου ένα 5 εμφανίζεται σε ένα από τα δύο ζάρια (η τιμή του δεύτερου ζαριού αγνοείται). Συνεπάγεται --decision checker αν δεν δοθεί καμία τιμή για το --decision.
--pip-min / --pip-max — Εύρος διαφοράς του μετρητή πόντων (pip count).
--winrate-min / --winrate-max — Εύρος ποσοστού νίκης (%).
--cube — Τιμή του κύβου.
--score1 / --score2 — Σκορ των παικτών.
--match-length — Μήκος του αγώνα.
--error-min — Ελάχιστο σφάλμα equity.
--move-error-min / --move-error-max — Σφάλμα της παιγμένης κίνησης (millipoints).
--has-analysis — Μόνο οι θέσεις με ανάλυση.
--off1-min / --off2-min — Ελάχιστος αριθμός πουλιών εκτός (παίκτης 1/2).
--match-ids — Φιλτράρισμα κατά IDs αγώνων (χωρισμένα με κόμματα).
--tournament-ids — Φιλτράρισμα κατά IDs τουρνουά (χωρισμένα με κόμματα).
--position-ids — Φιλτράρισμα κατά IDs θέσεων: εύρος 2,7 (θέσεις 2 έως 7) ή ρητή λίστα χωρισμένη με ερωτηματικά 5;10;15.
--individual — Μόνο οι θέσεις που εισήχθησαν μεμονωμένα, δηλαδή αυτές που προσθέσατε εσείς και όχι όσες έφερε μια εισαγωγή αγώνα.
--flagged — Uniquement les positions marquées (flag) pour étude dans le logiciel d’origine (marques eXtreme Gammon). Non rétroactif : les matchs déjà importés doivent l’être à nouveau pour livrer leurs marques.
--has-comment — Uniquement les positions portant un commentaire. L’origine n’est pas distinguée : une note tapée à la main et un commentaire apporté par l’import d’un match comptent tous les deux. Les commentaires de match ou de tournoi ne sont pas consultés.
--no-comment — Uniquement les positions sans commentaire. Mutuellement exclusif avec --has-comment.

Παραδείγματα:

# Rechercher les décisions de videau
./blunderdb search --db base.db --decision cube

# Retrouver les positions que vous avez ajoutées vous-même
./blunderdb search --db base.db --individual

# Rechercher les positions avec erreur >= 0.1
./blunderdb search --db base.db --error-min 0.1

# Rechercher dans un tournoi et exporter
./blunderdb search --db base.db --tournament-ids 1 --export cubes.db

# Rechercher les positions avec un lancer de dés 6-5 (peu importe l'ordre)
./blunderdb search --db base.db --dice 6,5

# Rechercher les positions où un 6 a été obtenu sur l'un des deux dés
./blunderdb search --db base.db --dice 6

# Sortie JSON limitée à 10 résultats
./blunderdb search --db base.db --format json --limit 10

6.10. list — Εμφάνιση περιεχομένου

Εμφανίζει το περιεχόμενο της βάσης δεδομένων.

./blunderdb list --db <chemin> --type <type> [--limit <n>]

Τύποι:

matches — Λίστα των εισαγμένων αγώνων.
tournaments — Λίστα των τουρνουά.
positions — Λίστα των θέσεων (περιορισμένη στις 10 από προεπιλογή).
stats — Αναφορά στατιστικών επιδόσεων: PR / Snowie ER / MWC (συνολικό, πούλια, κύβος), κυλιόμενο PR στις τελευταίες N αποφάσεις, top blunders, κατανομή ανά ενέργεια κύβου και ιστόγραμμα των μεγεθών σφάλματος.

Επιλογές (μόνο τύπος ``stats``):

--metric — Εμφανιζόμενη μετρική: pr ή mwc (προεπιλογή: pr).
--player — Περιορισμός στον υποδεικνυόμενο παίκτη.
--tournament — Περιορισμός σε ένα ή περισσότερα IDs τουρνουά (χωρισμένα με κόμματα).
--from — Ημερομηνία έναρξης (ΕΕΕΕ-ΜΜ-ΗΗ).
--to — Ημερομηνία λήξης (ΕΕΕΕ-ΜΜ-ΗΗ).
--decision-type — Τύπος απόφασης: all, checker ή cube (προεπιλογή: all).
--top-blunders — Αριθμός των χειρότερων λαθών που εμφανίζονται (προεπιλογή: 10).
--format — Μορφή εξόδου: text ή json (προεπιλογή: text).

Παραδείγματα:

# Statistiques de la base
./blunderdb list --db base.db --type stats

# Statistiques en MWC pour un joueur donné
./blunderdb list --db base.db --type stats --metric mwc --player "Alice"

# Coups de pions uniquement, depuis une date
./blunderdb list --db base.db --type stats --decision-type checker --from 2026-01-01

# Sortie JSON (pour un script)
./blunderdb list --db base.db --type stats --format json

# Liste des matchs
./blunderdb list --db base.db --type matches

# Premières 20 positions
./blunderdb list --db base.db --type positions --limit 20

6.11. match — Εμφάνιση αγώνα

Εμφανίζει τις θέσεις και τις αναλύσεις ενός εισαγμένου αγώνα.

./blunderdb match --db <chemin> --id <id_match> [--format <format>] [--output <fichier>]

Επιλογές:

--db — Βάση δεδομένων (υποχρεωτικό).
--id — ID του αγώνα προς εμφάνιση (υποχρεωτικό).
--format — Μορφή εξόδου: json, text ή summary (προεπιλογή: json).
--output — Αρχείο εξόδου (προεπιλογή: τυπική έξοδος).

Παραδείγματα:

# Résumé d'un match
./blunderdb match --db base.db --id 1 --format summary

# Détails de chaque position
./blunderdb match --db base.db --id 1 --format text

# Export JSON vers un fichier
./blunderdb match --db base.db --id 1 --output match1.json

6.12. epc — Calculatrice EPC

Calcule l’Effective Pip Count, la probabilité de gain et le verdict de videau money d’une position de sortie donnée par XGID. Calcul pur : aucun fichier de base de données n’est impliqué.

./blunderdb epc [options] '<XGID>'

Επιλογές:

--format — Μορφή εξόδου: text ή json (προεπιλογή: text).
--bearoff-ts — Base bearoff two-sided optionnelle (.bd) élargissant la base intégrée TS-06-06 (également lue depuis la variable d’environnement BLUNDERDB_TS_PATH). La base valide la plus large l’emporte ; un fichier invalide est ignoré avec un avertissement.

Régimes. Dans le domaine couvert par la base two-sided, la probabilité de gain et l’analyse money du videau (cubeless, ND, D/T, D/P, verdict) sont exactes. En dehors, la probabilité de gain est estimée (convolution des distributions de lancers one-sided plus une correction calibrée) et affichée avec sa marge d’erreur mesurée ; le verdict de videau n’est volontairement jamais estimé (voir ADR-0009).

Παραδείγματα:

# Régime exact (les deux joueurs ont 6 pions ou moins)
./blunderdb epc 'XGID=-BBB------------------bbb-:0:0:1:00:0:0:0:0:10'

# Avec la base TS-06-11 téléchargée (exact jusqu'à 11 pions par joueur)
./blunderdb epc --bearoff-ts ~/.local/share/blunderdb/gnubg_ts6x11.bd 'XGID=…'

6.13. info — Μεταδεδομένα της βάσης

Εμφανίζει τα μεταδεδομένα και τα στατιστικά μιας βάσης δεδομένων.

./blunderdb info --db <chemin> [--format <format>]

Επιλογές:

--db — Βάση δεδομένων (υποχρεωτικό).
--format — Μορφή εξόδου: text ή json (προεπιλογή: text).

Παραδείγματα:

# Afficher les informations
./blunderdb info --db base.db

# Sortie JSON (pour un script)
./blunderdb info --db base.db --format json

6.14. edit — Τροποποίηση μεταδεδομένων

Τροποποιεί το όνομα χρήστη ή την περιγραφή μιας βάσης δεδομένων.

./blunderdb edit --db <chemin> [options]

Επιλογές:

--db — Βάση δεδομένων (υποχρεωτικό).
--user — Νέο όνομα χρήστη.
--description — Νέα περιγραφή.
--clear-user — Διαγραφή του ονόματος χρήστη.
--clear-description — Διαγραφή της περιγραφής.

Απαιτείται τουλάχιστον μία επιλογή τροποποίησης.

Παραδείγματα:

# Modifier l'utilisateur et la description
./blunderdb edit --db base.db --user "Marie" --description "Ma collection"

# Effacer la description
./blunderdb edit --db base.db --clear-description

6.15. verify — Έλεγχος ακεραιότητας

Ελέγχει την ακεραιότητα της βάσης δεδομένων και, προαιρετικά, συγκρίνει έναν αγώνα με το αρχείο προέλευσής του.

./blunderdb verify --db <chemin> [--match <id>] [--mat <fichier.mat>]

Επιλογές:

--db — Βάση δεδομένων (υποχρεωτικό).
--match — ID του αγώνα προς έλεγχο.
--mat — Αρχείο MAT προς σύγκριση (χρησιμοποιείται με --match).

Χωρίς την επιλογή --match, η εντολή εμφανίζει τα γενικά στατιστικά της βάσης. Με το --match, ελέγχει τα δεδομένα του αγώνα και μπορεί να τα συγκρίνει με το αρχικό αρχείο προέλευσης.

Παραδείγματα:

# Vérification globale
./blunderdb verify --db base.db

# Vérifier un match spécifique
./blunderdb verify --db base.db --match 1

# Comparer avec le fichier source
./blunderdb verify --db base.db --match 1 --mat original.mat

6.16. vacuum — Compacter la base de données

Récupère l’espace disque laissé par des suppressions (matchs, tournois, purges): SQLite ne réduit jamais le fichier tout seul lorsqu’on supprime des données, il faut le lui demander explicitement. C’est la seule façon de déclencher un compactage — il ne se produit jamais automatiquement à l’ouverture d’une base, car son coût est imprévisible sur une grosse base.

./blunderdb vacuum --db <chemin>

Επιλογές:

--db — Βάση δεδομένων (υποχρεωτικό).

La commande commence par un wal_checkpoint(TRUNCATE) pour que la taille affichée avant compactage soit honnête, vérifie qu’il reste sur le disque environ deux fois la taille actuelle du fichier (SQLite reconstruit entièrement la base avant de basculer dessus), effectue le VACUUM puis un ANALYZE pour rafraîchir les statistiques utilisées par le planificateur de requêtes. Si l’espace disque manque, la commande refuse de démarrer avec un message explicite plutôt que de risquer un compactage interrompu.

Παράδειγμα:

./blunderdb vacuum --db base.db

# Compacting database...
#   Before: 128.4 MiB
#   After:  41.2 MiB
#   Reclaimed: 87.2 MiB

6.17. delete — Διαγραφή δεδομένων

Διαγράφει έναν αγώνα και όλα τα σχετικά δεδομένα (παρτίδες, κινήσεις, αναλύσεις).

./blunderdb delete --db <chemin> --type match --id <id> [--confirm]

Επιλογές:

--db — Βάση δεδομένων (υποχρεωτικό).
--type — Τύπος διαγραφής: match (υποχρεωτικό).
--id — ID του στοιχείου προς διαγραφή (υποχρεωτικό).
--confirm — Διαγραφή χωρίς αίτημα επιβεβαίωσης.

Παραδείγματα:

# Supprimer avec confirmation interactive
./blunderdb delete --db base.db --type match --id 1

# Supprimer sans confirmation (pour scripts)
./blunderdb delete --db base.db --type match --id 1 --confirm

6.18. Παραδείγματα ροών εργασίας

6.18.1. Εισαγωγή ενός καταλόγου τουρνουά

# Créer une base dédiée au tournoi
./blunderdb create --db tournoi_paris.db --user "Jean" --description "Open de Paris 2025"

# Importer tous les matchs du répertoire
./blunderdb import --db tournoi_paris.db --type batch --dir ./matchs_open_paris/

# Vérifier le résultat
./blunderdb list --db tournoi_paris.db --type stats

6.18.2. Τακτικό αντίγραφο ασφαλείας

# Export complet pour sauvegarde
./blunderdb export --db production.db --type database --file sauvegarde-$(date +%Y%m%d).db

6.18.3. Ανάλυση σφαλμάτων

# Extraire les blunders dans une base séparée
./blunderdb search --db production.db --error-min 0.1 --export blunders.db

# Extraire les erreurs de videau
./blunderdb search --db production.db --decision cube --error-min 0.05 --export cube_errors.db

6.19. Κωδικοί εξόδου

0 — Επιτυχία.
1 — Σφάλμα.

Αυτό επιτρέπει τη χρήση της CLI σε σενάρια με διαχείριση σφαλμάτων:

if ./blunderdb import --db base.db --type match --file match.xg; then
    echo "Import réussi"
else
    echo "Échec de l'import"
    exit 1
fi