6. Command Line Interface (CLI)

6.1. Introduction

blunderDB ships a full command line interface (CLI) in the same executable as the graphical interface. The CLI is especially useful for:

bulk import of matches: import an entire directory of match files (XG, SGF, MAT, BGF…) in a single command,
automation: integrate blunderDB into shell scripts for regular backups, scheduled exports, or processing pipelines,
server usage: manage databases on machines without a graphical environment,
quick inspection: check the contents or integrity of a database without launching the graphical interface.

The CLI shares exactly the same database format as the graphical interface. Any operation performed via the CLI is immediately visible in the GUI and vice versa.

6.2. General syntax

The mode is detected automatically: if the first argument is a CLI command, blunderDB launches in headless mode, otherwise it launches the graphical interface.

# Mode graphique (aucun argument)
./blunderdb

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

6.3. Available commands

Command	Description
create	Create a new database.
import	Import data (match, position, batch).
export	Export data.
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	Search positions with filters.
list	Display database contents.
match	Display match positions and analysis.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Display database metadata.
edit	Edit database metadata.
verify	Verify database integrity.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Delete data.
help	Show help.
version	Show version.

Each command accepts the --help option to display its detailed help.

6.4. create — Create a database

Create a new database file with optional metadata.

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

Options:

--db — Path to the database file to create (required).
--user — Database owner name.
--description — Database description.
--force — Overwrite the file if it already exists.

The .db extension is added automatically if missing. Parent directories are created as needed.

Example:

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

6.5. import — Import data

Import match or position files into the database.

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

Options:

--db — Path to the database (required).
--type — Import type: match, position or batch (required).
--file — File to import (for match and position).
--dir — Directory to import (for batch).
--recursive — Recursively scan subdirectories (default: yes).

6.5.1. Import a match

Supported formats: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) and BGBlitz (.bgf).

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

6.5.2. Import positions

Import positions from a text file (one JSON position per line):

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

6.5.3. Batch import

Import all match files from a directory in a single operation. This is the most efficient method for importing a large number of matches.

# 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

A summary table shows for each file whether the import succeeded (✓), failed (✗) or was a duplicate (⊘).

6.6. export — Export data

Export database contents to files.

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

Options:

--db — Source database (required).
--type — Export type: database, positions, matches or mat (export of one or more matches as a Jellyfish .mat transcript) (required).
--file — Output file (required, except for --type mat used with --dir).
--dir — Output directory for batch .mat export (several matches, one file per match; without --match-ids, all matches are exported).
--analysis — Include analysis (default: yes).
--comments — Include comments (default: yes).
--filters — Include filter library (default: yes).
--played-moves — Include played moves (default: yes).
--matches — Include matches (default: yes).
--collections — Include collections (default: no).
--collection-ids — Collection IDs to export (comma-separated).
--match-ids — Match IDs to export (comma-separated, empty = all).
--tournament-ids — Tournament IDs to export (comma-separated).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Handing out a database: origin and password).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Examples:

# 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 — Search positions

Search positions in the database using combinable criteria.

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

Main options:

--db — Database (required).
--format — Output format: table, json or xgid (default: table).
--limit — Maximum number of results (0 = unlimited).
--export — Export results to a new database.

Available filters:

--decision — Decision type: checker or cube.
--dice — Dice roll. 5,3 matches positions where both dice match (any order). 5 matches positions where a 5 appears on either die (the second die value is ignored). Implies --decision checker when no --decision value is given.
--pip-min / --pip-max — Pip count difference range.
--winrate-min / --winrate-max — Win rate range (%).
--cube — Cube value.
--score1 / --score2 — Player scores.
--match-length — Match length.
--error-min — Minimum equity error.
--move-error-min / --move-error-max — Played move error (millipoints).
--has-analysis — Only positions with analysis.
--off1-min / --off2-min — Minimum checkers off (player 1/2).
--match-ids — Filter by match IDs (comma-separated).
--tournament-ids — Filter by tournament IDs (comma-separated).
--position-ids — Filter by position IDs: range 2,7 (positions 2 to 7) or explicit semicolon-separated list 5;10;15.
--individual — Only positions imported on their own, that is, the ones you added yourself and not the ones a match import brought in.
--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.

Examples:

# 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 — List contents

Display database contents.

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

Types:

matches — List of imported matches.
tournaments — List of tournaments.
positions — List of positions (limited to 10 by default).
stats — Performance statistics report: PR / Snowie ER / MWC (overall, checker, cube), rolling PR over the last N decisions, top blunders, breakdown by cube action and error magnitude histogram.

Options (``stats`` type only):

--metric — Displayed metric: pr or mwc (default: pr).
--player — Restrict to the given player.
--tournament — Restrict to one or more tournament IDs (comma-separated).
--from — Start date (YYYY-MM-DD).
--to — End date (YYYY-MM-DD).
--decision-type — Decision type: all, checker or cube (default: all).
--top-blunders — Number of worst errors listed (default: 10).
--format — Output format: text or json (default: text).

Examples:

# 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 — Display a match

Display positions and analysis of an imported match.

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

Options:

--db — Database (required).
--id — Match ID to display (required).
--format — Output format: json, text or summary (default: json).
--output — Output file (default: stdout).

Examples:

# 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 — Output format: text or json (default: 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).

Examples:

# 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 — Database metadata

Display metadata and statistics of a database.

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

Options:

--db — Database (required).
--format — Output format: text or json (default: text).

Examples:

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

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

6.14. edit — Edit metadata

Edit the user name or description of a database.

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

Options:

--db — Database (required).
--user — New user name.
--description — New description.
--clear-user — Clear user name.
--clear-description — Clear description.

At least one edit option is required.

Examples:

# 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 — Verify integrity

Verify database integrity and optionally compare a match against its source file.

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

Options:

--db — Database (required).
--match — Match ID to verify.
--mat — MAT file to compare against (used with --match).

Without --match, the command displays general database statistics. With --match, it verifies the match data and can compare it against the original source file.

Examples:

# 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 — Database (required).

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.

Example:

./blunderdb vacuum --db base.db

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

6.17. delete — Delete data

Delete a match and all associated data (games, moves, analyses).

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

Options:

--db — Database (required).
--type — Delete type: match (required).
--id — ID of the item to delete (required).
--confirm — Delete without asking for confirmation.

Examples:

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

6.18.1. Import a tournament directory

# 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. Regular backup

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

6.18.3. Error analysis

# 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. Exit codes

0 — Success.
1 — Error.

This makes the CLI suitable for use in scripts with error handling:

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