6. Interfaccia a riga di comando (CLI)

6.1. Introduzione

blunderDB include un’interfaccia a riga di comando (CLI) completa nello stesso eseguibile dell’interfaccia grafica. La CLI è particolarmente utile per:

l’import in massa di match: importare un’intera cartella di file di match (XG, SGF, MAT, BGF…) con un solo comando,
l’automazione: integrare blunderDB in script shell per backup periodici, export pianificati o catene di elaborazione,
l’uso su server: gestire database su macchine prive di ambiente grafico,
l’ispezione rapida: verificare il contenuto o l’integrità di un database senza avviare l’interfaccia grafica.

La CLI condivide esattamente lo stesso formato di database dell’interfaccia grafica. Qualsiasi operazione eseguita tramite la CLI è immediatamente visibile nell’interfaccia grafica e viceversa.

6.2. Sintassi generale

La modalità viene rilevata automaticamente: se il primo argomento è un comando CLI, blunderDB si avvia in modalità headless, altrimenti avvia l’interfaccia grafica.

# Mode graphique (aucun argument)
./blunderdb

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

6.3. Comandi disponibili

Comando	Descrizione
create	Crea un nuovo database.
import	Importa dati (match, posizione, lotto).
export	Esporta dati.
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	Cerca posizioni con filtri.
list	Mostra il contenuto del database.
match	Mostra le posizioni e le analisi di un match.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Mostra i metadati del database.
edit	Modifica i metadati del database.
verify	Verifica l’integrità del database.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Elimina dati.
help	Mostra la guida.
version	Mostra la versione.

Ogni comando accetta l’opzione --help per mostrare la propria guida dettagliata.

6.4. create — Creare un database

Crea un nuovo file di database con metadati opzionali.

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

Opzioni:

--db — Percorso del file di database da creare (obbligatorio).
--user — Nome del proprietario del database.
--description — Descrizione del database.
--force — Sovrascrivere il file se esiste già.

L’estensione .db viene aggiunta automaticamente se assente. Le cartelle superiori vengono create se necessario.

Esempio:

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

6.5. import — Importare dati

Importa file di match o di posizioni nel database.

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

Opzioni:

--db — Percorso del database (obbligatorio).
--type — Tipo di import: match, position o batch (obbligatorio).
--file — File da importare (per match e position).
--dir — Cartella da importare (per batch).
--recursive — Scansionare ricorsivamente le sottocartelle (predefinito: sì).

6.5.1. Import di un match

Formati supportati: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) e BGBlitz (.bgf).

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

6.5.2. Import di posizioni

Importa posizioni da un file di testo (una posizione JSON per riga):

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

6.5.3. Import in lotto

Importa tutti i file di match di una cartella in una sola operazione. È il metodo più efficiente per importare un gran numero di match.

# 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

Una tabella riepilogativa indica per ogni file se l’import è riuscito (✓), fallito (✗) o se si tratta di un duplicato (⊘).

6.6. export — Esportare dati

Esporta il contenuto del database in file.

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

Opzioni:

--db — Database di origine (obbligatorio).
--type — Tipo di export: database, positions, matches o mat (export di uno o più match in trascrizione Jellyfish .mat) (obbligatorio).
--file — File di output (obbligatorio, tranne che per --type mat usato con --dir).
--dir — Directory di output per l’export .mat in blocco (più match, un file per match; senza --match-ids, vengono esportati tutti i match).
--analysis — Includere le analisi (predefinito: sì).
--comments — Includere i commenti (predefinito: sì).
--filters — Includere la libreria di filtri (predefinito: sì).
--played-moves — Includere le mosse giocate (predefinito: sì).
--matches — Includere i match (predefinito: sì).
--collections — Includere le collezioni (predefinito: no).
--collection-ids — ID delle collezioni da esportare (separati da virgole).
--match-ids — ID dei match da esportare (separati da virgole, vuoto = tutti).
--tournament-ids — ID dei tornei da esportare (separati da virgole).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Distribuire un database: origine e password).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Esempi:

# 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

Opzioni:

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

Opzioni:

--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 — Cercare posizioni

Cerca posizioni nel database secondo criteri combinabili.

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

Opzioni principali:

--db — Database (obbligatorio).
--format — Formato di output: table, json o xgid (predefinito: table).
--limit — Numero massimo di risultati (0 = illimitato).
--export — Esportare i risultati in un nuovo database.

Filtri disponibili:

--decision — Tipo di decisione: checker o cube.
--dice — Lancio dei dadi. 5,3 cerca le posizioni in cui entrambi i dadi corrispondono (in qualsiasi ordine). 5 cerca le posizioni in cui un 5 compare su uno dei due dadi (il valore del secondo dado viene ignorato). Implica --decision checker se non viene fornito alcun valore di --decision.
--pip-min / --pip-max — Intervallo di differenza del pip count.
--winrate-min / --winrate-max — Intervallo della percentuale di vittoria (%).
--cube — Valore del cubo.
--score1 / --score2 — Punteggi dei giocatori.
--match-length — Lunghezza del match.
--error-min — Errore di equity minimo.
--move-error-min / --move-error-max — Errore della mossa giocata (millipunti).
--has-analysis — Solo le posizioni con analisi.
--off1-min / --off2-min — Pedine uscite minime (giocatore 1/2).
--match-ids — Filtrare per ID dei match (separati da virgole).
--tournament-ids — Filtrare per ID dei tornei (separati da virgole).
--position-ids — Filtrare per ID di posizioni: intervallo 2,7 (posizioni da 2 a 7) o elenco esplicito separato da punti e virgola 5;10;15.
--individual — Solo le posizioni importate singolarmente, cioè quelle che hai aggiunto tu e non quelle portate da un import di partita.
--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.

Esempi:

# 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 — Elencare il contenuto

Mostra il contenuto del database.

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

Tipi:

matches — Elenco dei match importati.
tournaments — Elenco dei tornei.
positions — Elenco delle posizioni (limitato a 10 per impostazione predefinita).
stats — Rapporto di statistiche di prestazione: PR / Snowie ER / MWC (globale, pedine, cubo), PR mobile sulle ultime N decisioni, top blunder, ripartizione per azione di cubo e istogramma delle magnitudini di errore.

Opzioni (solo tipo ``stats``):

--metric — Metrica visualizzata: pr o mwc (predefinito: pr).
--player — Limitare al giocatore indicato.
--tournament — Limitare a uno o più ID di tornei (separati da virgole).
--from — Data di inizio (AAAA-MM-GG).
--to — Data di fine (AAAA-MM-GG).
--decision-type — Tipo di decisione: all, checker o cube (predefinito: all).
--top-blunders — Numero di errori peggiori elencati (predefinito: 10).
--format — Formato di output: text o json (predefinito: text).

Esempi:

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

Mostra le posizioni e le analisi di un match importato.

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

Opzioni:

--db — Database (obbligatorio).
--id — ID del match da visualizzare (obbligatorio).
--format — Formato di output: json, text o summary (predefinito: json).
--output — File di output (predefinito: output standard).

Esempi:

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

Opzioni:

--format — Formato di output: text o json (predefinito: 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).

Esempi:

# 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 — Metadati del database

Mostra i metadati e le statistiche di un database.

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

Opzioni:

--db — Database (obbligatorio).
--format — Formato di output: text o json (predefinito: text).

Esempi:

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

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

6.14. edit — Modificare i metadati

Modifica il nome utente o la descrizione di un database.

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

Opzioni:

--db — Database (obbligatorio).
--user — Nuovo nome utente.
--description — Nuova descrizione.
--clear-user — Cancellare il nome utente.
--clear-description — Cancellare la descrizione.

È richiesta almeno un’opzione di modifica.

Esempi:

# 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 — Verificare l’integrità

Verifica l’integrità del database e, facoltativamente, confronta un match con il suo file di origine.

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

Opzioni:

--db — Database (obbligatorio).
--match — ID del match da verificare.
--mat — File MAT da confrontare (usato con --match).

Senza l’opzione --match, il comando mostra le statistiche generali del database. Con --match, verifica i dati del match e può confrontarli con il file di origine originale.

Esempi:

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

Opzioni:

--db — Database (obbligatorio).

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.

Esempio:

./blunderdb vacuum --db base.db

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

6.17. delete — Eliminare dati

Elimina un match e tutti i dati associati (partite, mosse, analisi).

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

Opzioni:

--db — Database (obbligatorio).
--type — Tipo di eliminazione: match (obbligatorio).
--id — ID dell’elemento da eliminare (obbligatorio).
--confirm — Eliminare senza chiedere conferma.

Esempi:

# 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. Esempi di flusso di lavoro

6.18.1. Import di una cartella di torneo

# 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. Backup periodico

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

6.18.3. Analisi degli errori

# 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. Codici di uscita

0 — Successo.
1 — Errore.

Questo permette di utilizzare la CLI in script con gestione degli errori:

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