6. Interface en ligne de commande (CLI)

6.1. Introduction

blunderDB embarque une interface en ligne de commande (CLI) complète dans le même exécutable que l’interface graphique. La CLI est particulièrement utile pour:

l’import en masse de matchs: importer un répertoire entier de fichiers de matchs (XG, SGF, MAT, BGF…) en une seule commande,
l’automatisation: intégrer blunderDB dans des scripts shell pour des sauvegardes régulières, des exports planifiés ou des chaînes de traitement,
l’utilisation sur serveur: manipuler des bases de données sur des machines sans environnement graphique,
l’inspection rapide: vérifier le contenu ou l’intégrité d’une base de données sans lancer l’interface graphique.

La CLI partage exactement le même format de base de données que l’interface graphique. Toute opération effectuée en CLI est immédiatement visible dans l’interface graphique et inversement.

6.2. Syntaxe générale

Le mode est détecté automatiquement: si le premier argument est une commande CLI, blunderDB se lance en mode headless, sinon il lance l’interface graphique.

# Mode graphique (aucun argument)
./blunderdb

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

6.3. Commandes disponibles

Commande	Description
create	Crée une nouvelle base de données.
import	Importe des données (match, position, lot).
export	Exporte des données.
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	Recherche des positions avec filtres.
list	Affiche le contenu de la base.
match	Affiche les positions et analyses d’un match.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Affiche les métadonnées de la base.
edit	Modifie les métadonnées de la base.
verify	Vérifie l’intégrité de la base.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Supprime des données.
help	Affiche l’aide.
version	Affiche la version.

Chaque commande accepte l’option --help pour afficher son aide détaillée.

6.4. create — Créer une base de données

Crée un nouveau fichier de base de données avec des métadonnées optionnelles.

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

Options:

--db — Chemin du fichier de base de données à créer (obligatoire).
--user — Nom du propriétaire de la base.
--description — Description de la base.
--force — Écraser le fichier s’il existe déjà.

L’extension .db est ajoutée automatiquement si elle est absente. Les répertoires parents sont créés si nécessaire.

Exemple:

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

6.5. import — Importer des données

Importe des fichiers de matchs ou de positions dans la base de données.

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

Options:

--db — Chemin de la base de données (obligatoire).
--type — Type d’import: match, position ou batch (obligatoire).
--file — Fichier à importer (pour match et position).
--dir — Répertoire à importer (pour batch).
--recursive — Scanner récursivement les sous-répertoires (défaut: oui).

6.5.1. Import d’un match

Formats supportés: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) et BGBlitz (.bgf).

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

6.5.2. Import de positions

Importe des positions depuis un fichier texte (une position JSON par ligne):

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

6.5.3. Import par lot

Importe tous les fichiers de matchs d’un répertoire en une seule opération. C’est la méthode la plus efficace pour importer un grand nombre de matchs.

# 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

Un tableau récapitulatif indique pour chaque fichier si l’import a réussi (✓), échoué (✗) ou s’il s’agit d’un doublon (⊘).

6.6. export — Exporter des données

Exporte le contenu de la base vers des fichiers.

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

Options:

--db — Base source (obligatoire).
--type — Type d’export: database, positions, matches ou mat (export d’un ou plusieurs matchs en transcription Jellyfish .mat) (obligatoire).
--file — Fichier de sortie (obligatoire, sauf pour --type mat utilisé avec --dir).
--dir — Répertoire de sortie pour l’export .mat par lot (plusieurs matchs, un fichier par match ; sans --match-ids, tous les matchs sont exportés).
--analysis — Inclure les analyses (défaut: oui).
--comments — Inclure les commentaires (défaut: oui).
--filters — Inclure la bibliothèque de filtres (défaut: oui).
--played-moves — Inclure les coups joués (défaut: oui).
--matches — Inclure les matchs (défaut: oui).
--collections — Inclure les collections (défaut: non).
--collection-ids — IDs de collections à exporter (séparés par des virgules).
--match-ids — IDs de matchs à exporter (séparés par des virgules, vide = tous).
--tournament-ids — IDs de tournois à exporter (séparés par des virgules).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Diffuser une base : origine et mot de passe).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Exemples:

# 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

Options:

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

Options:

--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 — Rechercher des positions

Recherche des positions dans la base selon des critères combinables.

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

Options principales:

--db — Base de données (obligatoire).
--format — Format de sortie: table, json ou xgid (défaut: table).
--limit — Nombre maximum de résultats (0 = illimité).
--export — Exporter les résultats vers une nouvelle base.

Filtres disponibles:

--decision — Type de décision: checker ou cube.
--dice — Lancer de dés. 5,3 cherche les positions où les deux dés correspondent (peu importe l’ordre). 5 cherche les positions où un 5 apparaît sur l’un des deux dés (la valeur du deuxième dé est ignorée). Implique --decision checker si aucune valeur de --decision n’est donnée.
--pip-min / --pip-max — Intervalle de différence de pip count.
--winrate-min / --winrate-max — Intervalle de taux de victoire (%).
--cube — Valeur du videau.
--score1 / --score2 — Scores des joueurs.
--match-length — Longueur du match.
--error-min — Erreur d’équité minimale.
--move-error-min / --move-error-max — Erreur du coup joué (millipoints).
--has-analysis — Uniquement les positions avec analyse.
--off1-min / --off2-min — Pions sortis minimum (joueur 1/2).
--match-ids — Filtrer par IDs de matchs (séparés par des virgules).
--tournament-ids — Filtrer par IDs de tournois (séparés par des virgules).
--position-ids — Filtrer par IDs de positions : intervalle 2,7 (positions 2 à 7) ou liste explicite séparée par des points-virgules 5;10;15.
--individual — Uniquement les positions importées seules, c’est-à-dire celles que vous avez ajoutées vous-même et non celles qu’un import de match a apportées.
--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.

Exemples:

# 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 — Lister le contenu

Affiche le contenu de la base de données.

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

Types:

matches — Liste des matchs importés.
tournaments — Liste des tournois.
positions — Liste des positions (limité à 10 par défaut).
stats — Rapport de statistiques de performance : PR / Snowie ER / MWC (global, pions, videau), PR glissant sur les N dernières décisions, top blunders, répartition par action de videau et histogramme des magnitudes d’erreur.

Options (type ``stats`` uniquement):

--metric — Métrique affichée: pr ou mwc (défaut: pr).
--player — Restreindre au joueur indiqué.
--tournament — Restreindre à un ou plusieurs IDs de tournois (séparés par des virgules).
--from — Date de début (AAAA-MM-JJ).
--to — Date de fin (AAAA-MM-JJ).
--decision-type — Type de décision: all, checker ou cube (défaut: all).
--top-blunders — Nombre de pires erreurs listées (défaut: 10).
--format — Format de sortie: text ou json (défaut: text).

Exemples:

# 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 — Afficher un match

Affiche les positions et analyses d’un match importé.

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

Options:

--db — Base de données (obligatoire).
--id — ID du match à afficher (obligatoire).
--format — Format de sortie: json, text ou summary (défaut: json).
--output — Fichier de sortie (défaut: sortie standard).

Exemples:

# 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>'

Options:

--format — Format de sortie: text ou json (défaut: 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).

Exemples:

# 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 — Métadonnées de la base

Affiche les métadonnées et les statistiques d’une base de données.

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

Options:

--db — Base de données (obligatoire).
--format — Format de sortie: text ou json (défaut: text).

Exemples:

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

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

6.14. edit — Modifier les métadonnées

Modifie le nom d’utilisateur ou la description d’une base de données.

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

Options:

--db — Base de données (obligatoire).
--user — Nouveau nom d’utilisateur.
--description — Nouvelle description.
--clear-user — Effacer le nom d’utilisateur.
--clear-description — Effacer la description.

Au moins une option de modification est requise.

Exemples:

# 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 — Vérifier l’intégrité

Vérifie l’intégrité de la base de données et, optionnellement, compare un match avec son fichier source.

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

Options:

--db — Base de données (obligatoire).
--match — ID du match à vérifier.
--mat — Fichier MAT à comparer (utilisé avec --match).

Sans l’option --match, la commande affiche les statistiques générales de la base. Avec --match, elle vérifie les données du match et peut les comparer avec le fichier source original.

Exemples:

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

Options:

--db — Base de données (obligatoire).

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.

Exemple:

./blunderdb vacuum --db base.db

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

6.17. delete — Supprimer des données

Supprime un match et toutes les données associées (parties, coups, analyses).

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

Options:

--db — Base de données (obligatoire).
--type — Type de suppression: match (obligatoire).
--id — ID de l’élément à supprimer (obligatoire).
--confirm — Supprimer sans demander de confirmation.

Exemples:

# 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. Exemples de flux de travail

6.18.1. Import d’un répertoire de tournoi

# 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. Sauvegarde régulière

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

6.18.3. Analyse des erreurs

# 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. Codes de retour

0 — Succès.
1 — Erreur.

Cela permet d’utiliser la CLI dans des scripts avec gestion d’erreurs:

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