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	Экспортировать данные.
search	Поиск позиций с фильтрами.
list	Отобразить содержимое базы.
match	Отобразить позиции и анализ матча.
info	Отобразить метаданные базы.
edit	Изменить метаданные базы.
verify	Проверить целостность базы.
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 (обязательно).
--file — Выходной файл (обязательно).
--analysis — Включить анализ (по умолчанию: да).
--comments — Включить комментарии (по умолчанию: да).
--filters — Включить библиотеку фильтров (по умолчанию: да).
--played-moves — Включить сыгранные ходы (по умолчанию: да).
--matches — Включить матчи (по умолчанию: да).
--collections — Включить коллекции (по умолчанию: нет).
--collection-ids — Идентификаторы коллекций для экспорта (через запятую).
--match-ids — Идентификаторы матчей для экспорта (через запятую, пусто = все).
--tournament-ids — Идентификаторы турниров для экспорта (через запятую).

Примеры:

# 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

6.7. 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 — Фильтр по идентификаторам турниров (через запятую).

Примеры:

# Rechercher les décisions de videau
./blunderdb search --db base.db --decision cube

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

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

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

Типы:

matches — Список импортированных матчей.
positions — Список позиций (ограничено 10 по умолчанию).
stats — Глобальная статистика (позиции, анализы, матчи, партии, ходы).

Примеры:

# Statistiques de la base
./blunderdb list --db base.db --type stats

# Liste des matchs
./blunderdb list --db base.db --type matches

# Premières 20 positions
./blunderdb list --db base.db --type positions --limit 20

6.9. 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.10. 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.11. 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.12. 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.13. 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.14. Примеры рабочих процессов

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

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

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

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