6. Befehlszeilenschnittstelle (CLI)

6.1. Einführung

blunderDB enthält eine vollständige Befehlszeilenschnittstelle (CLI) in derselben ausführbaren Datei wie die grafische Oberfläche. Die CLI ist besonders nützlich für:

den Massenimport von Matches: ein ganzes Verzeichnis mit Match-Dateien (XG, SGF, MAT, BGF…) mit einem einzigen Befehl importieren,
die Automatisierung: blunderDB in Shell-Skripte einbinden für regelmäßige Sicherungen, geplante Exporte oder Verarbeitungsketten,
den Servereinsatz: Datenbanken auf Maschinen ohne grafische Umgebung verwalten,
die schnelle Inspektion: den Inhalt oder die Integrität einer Datenbank prüfen, ohne die grafische Oberfläche zu starten.

Die CLI verwendet genau dasselbe Datenbankformat wie die grafische Oberfläche. Jede über die CLI ausgeführte Operation ist sofort in der grafischen Oberfläche sichtbar und umgekehrt.

6.2. Allgemeine Syntax

Der Modus wird automatisch erkannt: Ist das erste Argument ein CLI-Befehl, startet blunderDB im Headless-Modus, andernfalls startet es die grafische Oberfläche.

# Mode graphique (aucun argument)
./blunderdb

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

6.3. Verfügbare Befehle

Befehl	Beschreibung
create	Erstellt eine neue Datenbank.
import	Importiert Daten (Match, Position, Stapel).
export	Exportiert Daten.
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	Sucht Positionen mit Filtern.
list	Zeigt den Inhalt der Datenbank an.
match	Zeigt die Positionen und Analysen eines Matches an.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Zeigt die Metadaten der Datenbank an.
edit	Ändert die Metadaten der Datenbank.
verify	Prüft die Integrität der Datenbank.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Löscht Daten.
help	Zeigt die Hilfe an.
version	Zeigt die Version an.

Jeder Befehl akzeptiert die Option --help, um seine ausführliche Hilfe anzuzeigen.

6.4. create — Eine Datenbank erstellen

Erstellt eine neue Datenbankdatei mit optionalen Metadaten.

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

Optionen:

--db — Pfad zur zu erstellenden Datenbankdatei (erforderlich).
--user — Name des Datenbankbesitzers.
--description — Beschreibung der Datenbank.
--force — Überschreibt die Datei, falls sie bereits existiert.

Die Erweiterung .db wird automatisch hinzugefügt, falls sie fehlt. Übergeordnete Verzeichnisse werden bei Bedarf erstellt.

Beispiel:

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

6.5. import — Daten importieren

Importiert Match- oder Positionsdateien in die Datenbank.

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

Optionen:

--db — Pfad zur Datenbank (erforderlich).
--type — Importtyp: match, position oder batch (erforderlich).
--file — Zu importierende Datei (für match und position).
--dir — Zu importierendes Verzeichnis (für batch).
--recursive — Unterverzeichnisse rekursiv durchsuchen (Standard: ja).

6.5.1. Ein Match importieren

Unterstützte Formate: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) und BGBlitz (.bgf).

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

6.5.2. Positionen importieren

Importiert Positionen aus einer Textdatei (eine JSON-Position pro Zeile):

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

6.5.3. Stapelimport

Importiert alle Match-Dateien eines Verzeichnisses in einem einzigen Vorgang. Dies ist die effizienteste Methode, um eine große Anzahl von Matches zu importieren.

# 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

Eine Übersichtstabelle zeigt für jede Datei an, ob der Import erfolgreich war (✓), fehlgeschlagen ist (✗) oder ein Duplikat war (⊘).

6.6. export — Daten exportieren

Exportiert den Inhalt der Datenbank in Dateien.

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

Optionen:

--db — Quelldatenbank (erforderlich).
--type — Exporttyp: database, positions, matches oder mat (Export eines oder mehrerer Matches als Jellyfish-Transkription .mat) (erforderlich).
--file — Ausgabedatei (erforderlich, außer bei --type mat in Verbindung mit --dir).
--dir — Ausgabeverzeichnis für den .mat-Stapelexport (mehrere Matches, eine Datei pro Match; ohne --match-ids werden alle Matches exportiert).
--analysis — Analysen einbeziehen (Standard: ja).
--comments — Kommentare einbeziehen (Standard: ja).
--filters — Filterbibliothek einbeziehen (Standard: ja).
--played-moves — Gespielte Züge einbeziehen (Standard: ja).
--matches — Matches einbeziehen (Standard: ja).
--collections — Sammlungen einbeziehen (Standard: nein).
--collection-ids — Zu exportierende Sammlungs-IDs (durch Kommas getrennt).
--match-ids — Zu exportierende Match-IDs (durch Kommas getrennt, leer = alle).
--tournament-ids — Zu exportierende Turnier-IDs (durch Kommas getrennt).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Eine Datenbank weitergeben: Herkunft und Passwort).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Beispiele:

# 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

Optionen:

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

Optionen:

--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 — Positionen suchen

Sucht Positionen in der Datenbank anhand kombinierbarer Kriterien.

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

Hauptoptionen:

--db — Datenbank (erforderlich).
--format — Ausgabeformat: table, json oder xgid (Standard: table).
--limit — Maximale Anzahl an Ergebnissen (0 = unbegrenzt).
--export — Ergebnisse in eine neue Datenbank exportieren.

Verfügbare Filter:

--decision — Entscheidungstyp: checker oder cube.
--dice — Würfelwurf. 5,3 sucht Positionen, bei denen beide Würfel übereinstimmen (unabhängig von der Reihenfolge). 5 sucht Positionen, bei denen eine 5 auf einem der beiden Würfel erscheint (der Wert des zweiten Würfels wird ignoriert). Impliziert --decision checker, wenn kein Wert für --decision angegeben ist.
--pip-min / --pip-max — Bereich der Pip-Count-Differenz.
--winrate-min / --winrate-max — Bereich der Gewinnrate (%).
--cube — Wert des Dopplerwürfels.
--score1 / --score2 — Spielstände der Spieler.
--match-length — Matchlänge.
--error-min — Minimaler Equity-Fehler.
--move-error-min / --move-error-max — Fehler des gespielten Zuges (Millipoints).
--has-analysis — Nur Positionen mit Analyse.
--off1-min / --off2-min — Mindestanzahl ausgewürfelter Steine (Spieler 1/2).
--match-ids — Nach Match-IDs filtern (durch Kommas getrennt).
--tournament-ids — Nach Turnier-IDs filtern (durch Kommas getrennt).
--position-ids — Nach Positions-IDs filtern: Intervall 2,7 (Positionen 2 bis 7) oder explizite, durch Semikolons getrennte Liste 5;10;15.
--individual — Nur einzeln importierte Stellungen, also die, die Sie selbst hinzugefügt haben, und nicht die aus einem Match-Import.
--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.

Beispiele:

# 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 — Inhalt auflisten

Zeigt den Inhalt der Datenbank an.

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

Typen:

matches — Liste der importierten Matches.
tournaments — Liste der Turniere.
positions — Liste der Positionen (standardmäßig auf 10 begrenzt).
stats — Bericht der Leistungsstatistiken: PR / Snowie ER / MWC (global, Steine, Cube), gleitender PR über die letzten N Entscheidungen, Top-Blunders, Aufschlüsselung nach Cube-Aktion und Histogramm der Fehlergrößen.

Optionen (nur Typ ``stats``):

--metric — Angezeigte Metrik: pr oder mwc (Standard: pr).
--player — Auf den angegebenen Spieler beschränken.
--tournament — Auf eine oder mehrere Turnier-IDs beschränken (durch Kommas getrennt).
--from — Startdatum (JJJJ-MM-TT).
--to — Enddatum (JJJJ-MM-TT).
--decision-type — Entscheidungstyp: all, checker oder cube (Standard: all).
--top-blunders — Anzahl der aufgelisteten schlimmsten Fehler (Standard: 10).
--format — Ausgabeformat: text oder json (Standard: text).

Beispiele:

# 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 — Ein Match anzeigen

Zeigt die Positionen und Analysen eines importierten Matches an.

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

Optionen:

--db — Datenbank (erforderlich).
--id — ID des anzuzeigenden Matches (erforderlich).
--format — Ausgabeformat: json, text oder summary (Standard: json).
--output — Ausgabedatei (Standard: Standardausgabe).

Beispiele:

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

Optionen:

--format — Ausgabeformat: text oder json (Standard: 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).

Beispiele:

# 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 — Datenbank-Metadaten

Zeigt die Metadaten und Statistiken einer Datenbank an.

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

Optionen:

--db — Datenbank (erforderlich).
--format — Ausgabeformat: text oder json (Standard: text).

Beispiele:

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

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

6.14. edit — Metadaten ändern

Ändert den Benutzernamen oder die Beschreibung einer Datenbank.

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

Optionen:

--db — Datenbank (erforderlich).
--user — Neuer Benutzername.
--description — Neue Beschreibung.
--clear-user — Benutzernamen löschen.
--clear-description — Beschreibung löschen.

Mindestens eine Änderungsoption ist erforderlich.

Beispiele:

# 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 — Integrität prüfen

Prüft die Integrität der Datenbank und vergleicht optional ein Match mit seiner Quelldatei.

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

Optionen:

--db — Datenbank (erforderlich).
--match — ID des zu prüfenden Matches.
--mat — Zum Vergleich heranzuziehende MAT-Datei (zusammen mit --match verwendet).

Ohne die Option --match zeigt der Befehl die allgemeinen Statistiken der Datenbank an. Mit --match prüft er die Match-Daten und kann sie mit der ursprünglichen Quelldatei vergleichen.

Beispiele:

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

Optionen:

--db — Datenbank (erforderlich).

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.

Beispiel:

./blunderdb vacuum --db base.db

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

6.17. delete — Daten löschen

Löscht ein Match und alle zugehörigen Daten (Spiele, Züge, Analysen).

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

Optionen:

--db — Datenbank (erforderlich).
--type — Löschtyp: match (erforderlich).
--id — ID des zu löschenden Elements (erforderlich).
--confirm — Ohne Bestätigungsabfrage löschen.

Beispiele:

# 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. Workflow-Beispiele

6.18.1. Ein Turnierverzeichnis importieren

# 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. Regelmäßige Sicherung

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

6.18.3. Fehleranalyse

# 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. Rückgabecodes

0 — Erfolg.
1 — Fehler.

Dadurch lässt sich die CLI in Skripten mit Fehlerbehandlung verwenden:

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