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.
search	Sucht Positionen mit Filtern.
list	Zeigt den Inhalt der Datenbank an.
match	Zeigt die Positionen und Analysen eines Matches an.
info	Zeigt die Metadaten der Datenbank an.
edit	Ändert die Metadaten der Datenbank.
verify	Prüft die Integrität der Datenbank.
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 oder matches (erforderlich).
--file — Ausgabedatei (erforderlich).
--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).

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

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

Beispiele:

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

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

Zeigt den Inhalt der Datenbank an.

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

Typen:

matches — Liste der importierten Matches.
positions — Liste der Positionen (standardmäßig auf 10 begrenzt).
stats — Globale Statistiken (Positionen, Analysen, Matches, Spiele, Züge).

Beispiele:

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

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

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

6.9. 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.10. 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.11. 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.12. 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.13. 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.14. Workflow-Beispiele

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

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

6.14.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.15. 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