6. Interfaz de línea de comandos (CLI)

6.1. Introducción

blunderDB incluye una interfaz de línea de comandos (CLI) completa en el mismo ejecutable que la interfaz gráfica. La CLI resulta especialmente útil para:

la importación masiva de partidas: importar un directorio entero de archivos de partidas (XG, SGF, MAT, BGF…) con un solo comando,
la automatización: integrar blunderDB en scripts de shell para copias de seguridad periódicas, exportaciones programadas o cadenas de procesamiento,
el uso en servidor: manipular bases de datos en máquinas sin entorno gráfico,
la inspección rápida: comprobar el contenido o la integridad de una base de datos sin abrir la interfaz gráfica.

La CLI utiliza exactamente el mismo formato de base de datos que la interfaz gráfica. Cualquier operación realizada desde la CLI es inmediatamente visible en la interfaz gráfica y viceversa.

6.2. Sintaxis general

El modo se detecta automáticamente: si el primer argumento es un comando de la CLI, blunderDB se ejecuta en modo headless; de lo contrario, abre la interfaz gráfica.

# Mode graphique (aucun argument)
./blunderdb

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

6.3. Comandos disponibles

Comando	Descripción
create	Crea una nueva base de datos.
import	Importa datos (partida, posición, lote).
export	Exporta datos.
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	Busca posiciones con filtros.
list	Muestra el contenido de la base de datos.
match	Muestra las posiciones y los análisis de una partida.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Muestra los metadatos de la base de datos.
edit	Modifica los metadatos de la base de datos.
verify	Verifica la integridad de la base de datos.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Elimina datos.
help	Muestra la ayuda.
version	Muestra la versión.

Cada comando acepta la opción --help para mostrar su ayuda detallada.

6.4. create — Crear una base de datos

Crea un nuevo archivo de base de datos con metadatos opcionales.

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

Opciones:

--db — Ruta del archivo de base de datos a crear (obligatorio).
--user — Nombre del propietario de la base de datos.
--description — Descripción de la base de datos.
--force — Sobrescribir el archivo si ya existe.

La extensión .db se añade automáticamente si falta. Los directorios superiores se crean si es necesario.

Ejemplo:

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

6.5. import — Importar datos

Importa archivos de partidas o de posiciones en la base de datos.

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

Opciones:

--db — Ruta de la base de datos (obligatorio).
--type — Tipo de importación: match, position o batch (obligatorio).
--file — Archivo a importar (para match y position).
--dir — Directorio a importar (para batch).
--recursive — Explorar recursivamente los subdirectorios (por defecto: sí).

6.5.1. Importar una partida

Formatos compatibles: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) y BGBlitz (.bgf).

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

6.5.2. Importar posiciones

Importa posiciones desde un archivo de texto (una posición JSON por línea):

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

6.5.3. Importación por lotes

Importa todos los archivos de partidas de un directorio en una sola operación. Es el método más eficiente para importar un gran número de partidas.

# 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 tabla resumen indica para cada archivo si la importación tuvo éxito (✓), falló (✗) o se trata de un duplicado (⊘).

6.6. export — Exportar datos

Exporta el contenido de la base de datos a archivos.

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

Opciones:

--db — Base de datos de origen (obligatorio).
--type — Tipo de exportación: database, positions, matches o mat (exportación de una o varias partidas en transcripción Jellyfish .mat) (obligatorio).
--file — Archivo de salida (obligatorio, salvo para --type mat utilizado con --dir).
--dir — Directorio de salida para la exportación .mat por lotes (varias partidas, un archivo por partida; sin --match-ids, se exportan todas las partidas).
--analysis — Incluir los análisis (por defecto: sí).
--comments — Incluir los comentarios (por defecto: sí).
--filters — Incluir la biblioteca de filtros (por defecto: sí).
--played-moves — Incluir las jugadas realizadas (por defecto: sí).
--matches — Incluir las partidas (por defecto: sí).
--collections — Incluir las colecciones (por defecto: no).
--collection-ids — IDs de las colecciones a exportar (separados por comas).
--match-ids — IDs de las partidas a exportar (separados por comas, vacío = todas).
--tournament-ids — IDs de los torneos a exportar (separados por comas).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Distribuir una base de datos: origen y contraseña).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Ejemplos:

# 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

Opciones:

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

Opciones:

--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 — Buscar posiciones

Busca posiciones en la base de datos según criterios combinables.

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

Opciones principales:

--db — Base de datos (obligatorio).
--format — Formato de salida: table, json o xgid (por defecto: table).
--limit — Número máximo de resultados (0 = ilimitado).
--export — Exportar los resultados a una nueva base de datos.

Filtros disponibles:

--decision — Tipo de decisión: checker o cube.
--dice — Tirada de dados. 5,3 busca las posiciones en las que coinciden ambos dados (sin importar el orden). 5 busca las posiciones en las que aparece un 5 en cualquiera de los dos dados (se ignora el valor del segundo dado). Implica --decision checker si no se especifica ningún valor de --decision.
--pip-min / --pip-max — Intervalo de diferencia de pip count.
--winrate-min / --winrate-max — Intervalo de porcentaje de victoria (%).
--cube — Valor del cubo.
--score1 / --score2 — Marcadores de los jugadores.
--match-length — Duración del match.
--error-min — Error de equidad mínimo.
--move-error-min / --move-error-max — Error de la jugada realizada (milipuntos).
--has-analysis — Solo las posiciones con análisis.
--off1-min / --off2-min — Fichas retiradas mínimas (jugador 1/2).
--match-ids — Filtrar por IDs de partidas (separados por comas).
--tournament-ids — Filtrar por IDs de torneos (separados por comas).
--position-ids — Filtrar por IDs de posiciones: intervalo 2,7 (posiciones 2 a 7) o lista explícita separada por puntos y comas 5;10;15.
--individual — Solo las posiciones importadas por separado, es decir, las que usted añadió y no las que trajo la importación de una partida.
--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.

Ejemplos:

# 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 — Listar el contenido

Muestra el contenido de la base de datos.

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

Tipos:

matches — Lista de las partidas importadas.
tournaments — Lista de los torneos.
positions — Lista de posiciones (limitada a 10 por defecto).
stats — Informe de estadísticas de rendimiento: PR / Snowie ER / MWC (global, fichas, cubo), PR deslizante sobre las N últimas decisiones, peores errores, reparto por acción de cubo e histograma de las magnitudes de error.

Opciones (solo para el tipo ``stats``):

--metric — Métrica mostrada: pr o mwc (por defecto: pr).
--player — Restringir al jugador indicado.
--tournament — Restringir a uno o varios IDs de torneos (separados por comas).
--from — Fecha de inicio (AAAA-MM-DD).
--to — Fecha de fin (AAAA-MM-DD).
--decision-type — Tipo de decisión: all, checker o cube (por defecto: all).
--top-blunders — Número de peores errores listados (por defecto: 10).
--format — Formato de salida: text o json (por defecto: text).

Ejemplos:

# 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 — Mostrar una partida

Muestra las posiciones y los análisis de una partida importada.

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

Opciones:

--db — Base de datos (obligatorio).
--id — ID de la partida a mostrar (obligatorio).
--format — Formato de salida: json, text o summary (por defecto: json).
--output — Archivo de salida (por defecto: salida estándar).

Ejemplos:

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

Opciones:

--format — Formato de salida: text o json (por defecto: 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).

Ejemplos:

# 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 — Metadatos de la base de datos

Muestra los metadatos y las estadísticas de una base de datos.

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

Opciones:

--db — Base de datos (obligatorio).
--format — Formato de salida: text o json (por defecto: text).

Ejemplos:

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

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

6.14. edit — Modificar los metadatos

Modifica el nombre de usuario o la descripción de una base de datos.

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

Opciones:

--db — Base de datos (obligatorio).
--user — Nuevo nombre de usuario.
--description — Nueva descripción.
--clear-user — Borrar el nombre de usuario.
--clear-description — Borrar la descripción.

Se requiere al menos una opción de modificación.

Ejemplos:

# 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 — Verificar la integridad

Verifica la integridad de la base de datos y, opcionalmente, compara una partida con su archivo de origen.

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

Opciones:

--db — Base de datos (obligatorio).
--match — ID de la partida a verificar.
--mat — Archivo MAT a comparar (se usa con --match).

Sin la opción --match, el comando muestra las estadísticas generales de la base de datos. Con --match, verifica los datos de la partida y puede compararlos con el archivo de origen original.

Ejemplos:

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

Opciones:

--db — Base de datos (obligatorio).

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.

Ejemplo:

./blunderdb vacuum --db base.db

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

6.17. delete — Eliminar datos

Elimina una partida y todos los datos asociados (juegos, jugadas, análisis).

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

Opciones:

--db — Base de datos (obligatorio).
--type — Tipo de eliminación: match (obligatorio).
--id — ID del elemento a eliminar (obligatorio).
--confirm — Eliminar sin pedir confirmación.

Ejemplos:

# 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. Ejemplos de flujos de trabajo

6.18.1. Importar un directorio de 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. Copia de seguridad periódica

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

6.18.3. Análisis de errores

# 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. Códigos de salida

0 — Éxito.
1 — Error.

Esto permite usar la CLI en scripts con gestión de errores:

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