6. コマンドラインインターフェース（CLI）

6.1. はじめに

blunderDBはグラフィカルインターフェースと同じ実行ファイルに完全なコマンドラインインターフェース（CLI）を搭載しています。CLIは特に以下の用途に便利です：

マッチの一括インポート：1つのコマンドでマッチファイル（XG、SGF、MAT、BGF…）のディレクトリ全体をインポートする、
自動化：定期的なバックアップ、スケジュールされたエクスポート、または処理パイプラインのためにblunderDBをシェルスクリプトに統合する、
サーバー使用：グラフィカル環境のないマシンでデータベースを管理する、
クイック検査：グラフィカルインターフェースを起動せずにデータベースのコンテンツや整合性を確認する。

CLIはグラフィカルインターフェースとまったく同じデータベース形式を共有しています。CLI経由で実行された操作はグラフィカルインターフェースですぐに確認でき、その逆も同様です。

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. ポジションのインポート

テキストファイル（1行に1つのJSONポジション）からポジションをインポートします：

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

6.5.3. 一括インポート

1回の操作でディレクトリのすべてのマッチファイルをインポートします。これは多数のマッチをインポートする最も効率的な方法です。

# 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 — エクスポートするコレクションのID（カンマ区切り）。
--match-ids — エクスポートするマッチのID（カンマ区切り、空=すべて）。
--tournament-ids — エクスポートするトーナメントのID（カンマ区切り）。

例：

# 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 の値が指定されていない場合は --decision checker を意味します。
--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 — マッチIDでフィルタリングする（カンマ区切り）。
--tournament-ids — トーナメントIDでフィルタリングする（カンマ区切り）。

例：

# 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 — 表示するマッチの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 — 説明を削除する。

少なくとも1つの編集オプションが必要です。

例：

# 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 — 確認するマッチのID。
--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 — 削除する要素の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