6. Интерфейс командной строки (CLI)

6.1. Введение

blunderDB включает полноценный интерфейс командной строки (CLI) в том же исполняемом файле, что и графический интерфейс. CLI особенно полезен для:

массового импорта матчей: импортировать весь каталог файлов матчей (XG, SGF, MAT, BGF…) одной командой,
автоматизации: интегрировать blunderDB в shell-скрипты для регулярного резервного копирования, запланированного экспорта или конвейерной обработки,
работы на сервере: управлять базами данных на машинах без графического окружения,
быстрой проверки: проверить содержимое или целостность базы данных без запуска графического интерфейса.

CLI использует тот же формат базы данных, что и графический интерфейс. Любая операция, выполненная через CLI, немедленно отражается в GUI и наоборот.

6.2. Общий синтаксис

Режим определяется автоматически: если первый аргумент является командой CLI, blunderDB запускается в безголовом режиме, иначе запускается графический интерфейс.

# Mode graphique (aucun argument)
./blunderdb

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

6.3. Доступные команды

Команда	Описание
create	Создать новую базу данных.
import	Импортировать данные (матч, позиция, пакет).
export	Экспортировать данные.
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	Поиск позиций с фильтрами.
list	Отобразить содержимое базы.
match	Отобразить позиции и анализ матча.
epc	Calcule l’Effective Pip Count et le verdict de videau d’une position de sortie (XGID).
info	Отобразить метаданные базы.
edit	Изменить метаданные базы.
verify	Проверить целостность базы.
vacuum	Compacte le fichier de base de données, récupère l’espace libéré.
delete	Удалить данные.
help	Показать справку.
version	Показать версию.

Каждая команда принимает опцию --help для отображения подробной справки.

6.4. create — Создать базу данных

Создаёт новый файл базы данных с необязательными метаданными.

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

Параметры:

--db — Путь к файлу базы данных для создания (обязательно).
--user — Имя владельца базы данных.
--description — Описание базы данных.
--force — Перезаписать файл, если он уже существует.

Расширение .db добавляется автоматически, если оно отсутствует. Родительские каталоги создаются при необходимости.

Пример:

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

6.5. import — Импорт данных

Импортирует файлы матчей или позиций в базу данных.

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

Параметры:

--db — Путь к базе данных (обязательно).
--type — Тип импорта: match, position или batch (обязательно).
--file — Файл для импорта (для match и position).
--dir — Каталог для импорта (для batch).
--recursive — Рекурсивный просмотр подкаталогов (по умолчанию: да).

6.5.1. Импорт матча

Поддерживаемые форматы: eXtreme Gammon (.xg, .xgp), GNUbg (.sgf), Jellyfish (.mat, .txt) и BGBlitz (.bgf).

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

6.5.2. Импорт позиций

Импортирует позиции из текстового файла (одна JSON-позиция на строку):

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

6.5.3. Пакетный импорт

Импортирует все файлы матчей из каталога в одной операции. Это наиболее эффективный метод для импорта большого числа матчей.

# 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

Итоговая таблица показывает для каждого файла: импорт прошёл успешно (✓), не удался (✗) или это дубликат (⊘).

6.6. export — Экспорт данных

Экспортирует содержимое базы в файлы.

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

Параметры:

--db — Исходная база (обязательно).
--type — Тип экспорта: database, positions, matches или mat (экспорт одного или нескольких матчей в транскрипции Jellyfish .mat) (обязательно).
--file — Выходной файл (обязательно, кроме случая --type mat, используемого с --dir).
--dir — Выходной каталог для пакетного экспорта .mat (несколько матчей, один файл на матч; без --match-ids экспортируются все матчи).
--analysis — Включить анализ (по умолчанию: да).
--comments — Включить комментарии (по умолчанию: да).
--filters — Включить библиотеку фильтров (по умолчанию: да).
--played-moves — Включить сыгранные ходы (по умолчанию: да).
--matches — Включить матчи (по умолчанию: да).
--collections — Включить коллекции (по умолчанию: нет).
--collection-ids — Идентификаторы коллекций для экспорта (через запятую).
--match-ids — Идентификаторы матчей для экспорта (через запятую, пусто = все).
--tournament-ids — Идентификаторы турниров для экспорта (через запятую).
--password — Enveloppe le résultat dans un conteneur chiffré (.dbx).
--watermark — Écrit une déclaration d’origine signée dans le fichier exporté (voir Распространение базы: происхождение и пароль).
--watermark-note — Texte libre associé au filigrane (conditions d’usage, contact) ; utilisé avec --watermark.

Примеры:

# 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

Параметры:

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

Параметры:

--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 — Поиск позиций

Поиск позиций в базе данных по комбинируемым критериям.

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

Основные параметры:

--db — База данных (обязательно).
--format — Формат вывода: table, json или xgid (по умолчанию: table).
--limit — Максимальное количество результатов (0 = без ограничений).
--export — Экспортировать результаты в новую базу данных.

Доступные фильтры:

--decision — Тип решения: checker или cube.
--dice — Бросок кубиков. 5,3 ищет позиции, где оба кубика совпадают (в любом порядке). 5 ищет позиции, где 5 выпадает на одном из кубиков (значение второго кубика игнорируется). Подразумевает --decision checker, если значение --decision не указано.
--pip-min / --pip-max — Диапазон разницы пипкаунта.
--winrate-min / --winrate-max — Диапазон процента побед (%).
--cube — Значение куба.
--score1 / --score2 — Счёт игроков.
--match-length — Длина матча.
--error-min — Минимальная ошибка эквити.
--move-error-min / --move-error-max — Ошибка сыгранного хода (миллипункты).
--has-analysis — Только позиции с анализом.
--off1-min / --off2-min — Минимальное количество снятых шашек (игрок 1/2).
--match-ids — Фильтр по идентификаторам матчей (через запятую).
--tournament-ids — Фильтр по идентификаторам турниров (через запятую).
--position-ids — Фильтр по идентификаторам позиций: интервал 2,7 (позиции с 2 по 7) или явный список через точку с запятой 5;10;15.
--individual — Только позиции, импортированные отдельно, то есть те, которые вы добавили сами, а не пришедшие с импортом матча.
--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.

Примеры:

# 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 — Список содержимого

Отображает содержимое базы данных.

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

Типы:

matches — Список импортированных матчей.
tournaments — Список турниров.
positions — Список позиций (ограничено 10 по умолчанию).
stats — Отчёт со статистикой производительности: PR / Snowie ER / MWC (глобально, шашки, куб), скользящий PR за последние N решений, худшие ошибки, разбивка по действиям куба и гистограмма величин ошибок.

Опции (только для типа ``stats``):

--metric — Отображаемая метрика: pr или mwc (по умолчанию: pr).
--player — Ограничить указанным игроком.
--tournament — Ограничить одним или несколькими идентификаторами турниров (через запятую).
--from — Дата начала (ГГГГ-ММ-ДД).
--to — Дата окончания (ГГГГ-ММ-ДД).
--decision-type — Тип решения: all, checker или cube (по умолчанию: all).
--top-blunders — Количество перечисляемых худших ошибок (по умолчанию: 10).
--format — Формат вывода: text или json (по умолчанию: text).

Примеры:

# 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 — Отобразить матч

Отображает позиции и анализ импортированного матча.

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

Параметры:

--db — База данных (обязательно).
--id — Идентификатор матча для отображения (обязательно).
--format — Формат вывода: json, text или summary (по умолчанию: json).
--output — Выходной файл (по умолчанию: стандартный вывод).

Примеры:

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

Параметры:

--format — Формат вывода: text или json (по умолчанию: 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).

Примеры:

# 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 — Метаданные базы данных

Отображает метаданные и статистику базы данных.

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

Параметры:

--db — База данных (обязательно).
--format — Формат вывода: text или json (по умолчанию: text).

Примеры:

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

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

6.14. edit — Изменить метаданные

Изменяет имя пользователя или описание базы данных.

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

Параметры:

--db — База данных (обязательно).
--user — Новое имя пользователя.
--description — Новое описание.
--clear-user — Очистить имя пользователя.
--clear-description — Очистить описание.

Требуется хотя бы одна опция изменения.

Примеры:

# 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 — Проверка целостности

Проверяет целостность базы данных и, при необходимости, сравнивает матч с исходным файлом.

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

Параметры:

--db — База данных (обязательно).
--match — Идентификатор матча для проверки.
--mat — Файл MAT для сравнения (используется с --match).

Без опции --match команда отображает общую статистику базы. С --match она проверяет данные матча и может сравнить их с оригинальным исходным файлом.

Примеры:

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

Параметры:

--db — База данных (обязательно).

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.

Пример:

./blunderdb vacuum --db base.db

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

6.17. delete — Удалить данные

Удаляет матч и все связанные данные (партии, ходы, анализы).

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

Параметры:

--db — База данных (обязательно).
--type — Тип удаления: match (обязательно).
--id — Идентификатор элемента для удаления (обязательно).
--confirm — Удалить без запроса подтверждения.

Примеры:

# 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. Примеры рабочих процессов

6.18.1. Импорт каталога турнира

# 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. Регулярное резервное копирование

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

6.18.3. Анализ ошибок

# 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. Коды возврата

0 — Успех.
1 — Ошибка.

Это позволяет использовать CLI в скриптах с обработкой ошибок:

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