6. Komentoriviliittymä (CLI)

6.1. Johdanto

blunderDB sisältää täydellisen komentoriviliittymän (CLI) samassa suoritettavassa tiedostossa kuin graafinen käyttöliittymä. CLI on erityisen hyödyllinen seuraaviin tarkoituksiin:

ottelujen massatuonti: koko hakemistollinen ottelutiedostoja (XG, SGF, MAT, BGF…) tuodaan yhdellä komennolla,
automaatio: blunderDB:n integrointi shell-skripteihin säännöllisiä varmuuskopioita, ajastettuja vientejä tai käsittelyputkia varten,
palvelinkäyttö: tietokantojen hallinta koneilla, joilla ei ole graafista ympäristöä,
nopea tarkastus: tietokannan sisällön tai eheyden tarkistaminen käynnistämättä graafista käyttöliittymää.

CLI käyttää täsmälleen samaa tietokantamuotoa kuin graafinen käyttöliittymä. Mikä tahansa CLI:llä tehty toimenpide näkyy välittömästi graafisessa käyttöliittymässä ja päinvastoin.

6.2. Yleinen syntaksi

Tila tunnistetaan automaattisesti: jos ensimmäinen argumentti on CLI-komento, blunderDB käynnistyy headless-tilassa, muuten se käynnistää graafisen käyttöliittymän.

# Mode graphique (aucun argument)
./blunderdb

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

6.3. Käytettävissä olevat komennot

Komento	Kuvaus
create	Luo uusi tietokanta.
import	Tuo tietoja (ottelu, asema, erä).
export	Vie tietoja.
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	Hae asemia suodattimilla.
list	Näytä tietokannan sisältö.
match	Näytä ottelun asemat ja analyysit.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Näytä tietokannan metatiedot.
edit	Muokkaa tietokannan metatietoja.
verify	Tarkista tietokannan eheys.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Poista tietoja.
help	Näytä ohje.
version	Näytä versio.

Jokainen komento hyväksyy --help-valitsimen yksityiskohtaisen ohjeen näyttämiseksi.

6.4. create — Luo tietokanta

Luo uusi tietokantatiedosto valinnaisilla metatiedoilla.

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

Valitsimet:

--db — Luotavan tietokantatiedoston polku (pakollinen).
--user — Tietokannan omistajan nimi.
--description — Tietokannan kuvaus.
--force — Korvaa tiedosto, jos se on jo olemassa.

.db-pääte lisätään automaattisesti, jos se puuttuu. Ylähakemistot luodaan tarvittaessa.

Esimerkki:

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

6.5. import — Tuo tietoja

Tuo ottelu- tai asematiedostoja tietokantaan.

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

Valitsimet:

--db — Tietokannan polku (pakollinen).
--type — Tuontityyppi: match, position tai batch (pakollinen).
--file — Tuotava tiedosto (tyypeille match ja position).
--dir — Tuotava hakemisto (tyypille batch).
--recursive — Selaa alihakemistot rekursiivisesti (oletus: kyllä).

6.5.1. Ottelun tuonti

Tuetut muodot: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) ja BGBlitz (.bgf).

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

6.5.2. Asemien tuonti

Tuo asemia tekstitiedostosta (yksi JSON-asema riviä kohden):

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

6.5.3. Erätuonti

Tuo kaikki hakemiston ottelutiedostot yhdellä toimenpiteellä. Tämä on tehokkain tapa tuoda suuri määrä otteluita.

# 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

Yhteenvetotaulukko näyttää jokaisesta tiedostosta, onnistuiko tuonti (✓), epäonnistuiko se (✗) vai oliko kyseessä kaksoiskappale (⊘).

6.6. export — Vie tietoja

Vie tietokannan sisältö tiedostoihin.

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

Valitsimet:

--db — Lähdetietokanta (pakollinen).
--type — Vientityyppi: database, positions, matches tai mat (yhden tai useamman ottelun vienti Jellyfish .mat -transkriptioon) (pakollinen).
--file — Tulostiedosto (pakollinen, paitsi --type mat -vaihtoehdolle yhdessä --dir kanssa).
--dir — Erävientinä tehtävän .mat-viennin tulostushakemisto (useita otteluita, yksi tiedosto ottelua kohden; ilman --match-ids viedään kaikki ottelut).
--analysis — Sisällytä analyysit (oletus: kyllä).
--comments — Sisällytä kommentit (oletus: kyllä).
--filters — Sisällytä suodatinkirjasto (oletus: kyllä).
--played-moves — Sisällytä pelatut siirrot (oletus: kyllä).
--matches — Sisällytä ottelut (oletus: kyllä).
--collections — Sisällytä kokoelmat (oletus: ei).
--collection-ids — Vietävien kokoelmien tunnukset (pilkulla eroteltuna).
--match-ids — Vietävien otteluiden tunnukset (pilkulla eroteltuna, tyhjä = kaikki).
--tournament-ids — Vietävien turnausten tunnukset (pilkulla eroteltuna).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Tietokannan jakaminen: alkuperä ja salasana).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Esimerkkejä:

# 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

Valitsimet:

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

Valitsimet:

--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 — Hae asemia

Hae asemia tietokannasta yhdisteltävien kriteerien avulla.

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

Pääasialliset valitsimet:

--db — Tietokanta (pakollinen).
--format — Tulostusmuoto: table, json tai xgid (oletus: table).
--limit — Tulosten enimmäismäärä (0 = rajoittamaton).
--export — Vie tulokset uuteen tietokantaan.

Käytettävissä olevat suodattimet:

--decision — Päätöstyyppi: checker tai cube.
--dice — Nopanheitto. 5,3 hakee asemat, joissa molemmat nopat täsmäävät (järjestyksellä ei ole väliä). 5 hakee asemat, joissa 5 esiintyy jommassakummassa nopassa (toisen nopan arvo jätetään huomiotta). Sisältää --decision checker, jos --decision-arvoa ei ole annettu.
--pip-min / --pip-max — Pip-eron väli.
--winrate-min / --winrate-max — Voittoprosentin väli (%).
--cube — Tuplauskuution arvo.
--score1 / --score2 — Pelaajien pisteet.
--match-length — Ottelun pituus.
--error-min — Vähimmäisekvitettivirhe.
--move-error-min / --move-error-max — Pelatun siirron virhe (millipistettä).
--has-analysis — Vain asemat, joissa on analyysi.
--off1-min / --off2-min — Vähimmäismäärä ulospelattuja nappuloita (pelaaja 1/2).
--match-ids — Suodata otteluiden tunnusten mukaan (pilkulla eroteltuna).
--tournament-ids — Suodata turnausten tunnusten mukaan (pilkulla eroteltuna).
--position-ids — Suodata asemien tunnusten mukaan: väli 2,7 (asemat 2–7) tai puolipisteillä eroteltu eksplisiittinen luettelo 5;10;15.
--individual — Vain erikseen tuodut asemat, eli ne jotka lisäsit itse, eikä niitä jotka ottelun tuonti toi mukanaan.
--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.

Esimerkkejä:

# 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 — Luettele sisältö

Näytä tietokannan sisältö.

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

Tyypit:

matches — Luettelo tuoduista otteluista.
tournaments — Luettelo turnauksista.
positions — Luettelo asemista (oletuksena rajoitettu 10:een).
stats — Suorituskykytilastojen raportti: PR / Snowie ER / MWC (kokonais, nappulat, kuutio), liukuva PR viimeisten N päätöksen osalta, pahimmat virheet, jakauma kuutiotoiminnoittain ja virhesuuruuksien histogrammi.

Valinnat (vain ``stats``-tyyppi):

--metric — Näytettävä mittari: pr tai mwc (oletus: pr).
--player — Rajaa ilmoitettuun pelaajaan.
--tournament — Rajaa yhteen tai useampaan turnauksen tunnukseen (pilkulla eroteltuna).
--from — Aloituspäivä (VVVV-KK-PP).
--to — Lopetuspäivä (VVVV-KK-PP).
--decision-type — Päätöstyyppi: all, checker tai cube (oletus: all).
--top-blunders — Lueteltavien pahimpien virheiden määrä (oletus: 10).
--format — Tulostusmuoto: text tai json (oletus: text).

Esimerkkejä:

# 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 — Näytä ottelu

Näytä tuodun ottelun asemat ja analyysit.

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

Valitsimet:

--db — Tietokanta (pakollinen).
--id — Näytettävän ottelun tunnus (pakollinen).
--format — Tulostusmuoto: json, text tai summary (oletus: json).
--output — Tulostiedosto (oletus: vakiotuloste).

Esimerkkejä:

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

Valitsimet:

--format — Tulostusmuoto: text tai json (oletus: 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).

Esimerkkejä:

# 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 — Tietokannan metatiedot

Näytä tietokannan metatiedot ja tilastot.

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

Valitsimet:

--db — Tietokanta (pakollinen).
--format — Tulostusmuoto: text tai json (oletus: text).

Esimerkkejä:

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

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

6.14. edit — Muokkaa metatietoja

Muokkaa tietokannan käyttäjänimeä tai kuvausta.

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

Valitsimet:

--db — Tietokanta (pakollinen).
--user — Uusi käyttäjänimi.
--description — Uusi kuvaus.
--clear-user — Tyhjennä käyttäjänimi.
--clear-description — Tyhjennä kuvaus.

Vähintään yksi muokkausvalitsin vaaditaan.

Esimerkkejä:

# 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 — Tarkista eheys

Tarkista tietokannan eheys ja valinnaisesti vertaa ottelua sen lähdetiedostoon.

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

Valitsimet:

--db — Tietokanta (pakollinen).
--match — Tarkistettavan ottelun tunnus.
--mat — Verrattava MAT-tiedosto (käytetään yhdessä --match:n kanssa).

Ilman --match-valitsinta komento näyttää tietokannan yleiset tilastot. --match-valitsimen kanssa se tarkistaa ottelun tiedot ja voi verrata niitä alkuperäiseen lähdetiedostoon.

Esimerkkejä:

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

Valitsimet:

--db — Tietokanta (pakollinen).

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.

Esimerkki:

./blunderdb vacuum --db base.db

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

6.17. delete — Poista tietoja

Poista ottelu ja kaikki siihen liittyvät tiedot (pelit, siirrot, analyysit).

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

Valitsimet:

--db — Tietokanta (pakollinen).
--type — Poistotyyppi: match (pakollinen).
--id — Poistettavan kohteen tunnus (pakollinen).
--confirm — Poista pyytämättä vahvistusta.

Esimerkkejä:

# 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. Työnkulkuesimerkkejä

6.18.1. Turnaushakemiston tuonti

# 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. Säännöllinen varmuuskopiointi

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

6.18.3. Virheiden analysointi

# 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. Paluukoodit

0 — Onnistui.
1 — Virhe.

Tämä tekee CLI:stä sopivan käytettäväksi skripteissä virheenkäsittelyn kanssa:

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