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	データをエクスポートする。
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. ポジションのインポート

テキストファイル（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、または mat（1つまたは複数のマッチをJellyfish .mat トランスクリプションでエクスポート）（必須）。
--file — 出力ファイル（--dirと併用する --type mat を除き必須）。
--dir — バッチ .mat エクスポートの出力ディレクトリ（複数のマッチ、マッチごとに1ファイル。--match-idsなしの場合、すべてのマッチがエクスポートされます）。
--analysis — 分析を含める（デフォルト：はい）。
--comments — コメントを含める（デフォルト：はい）。
--filters — フィルターライブラリを含める（デフォルト：はい）。
--played-moves — プレイされた手を含める（デフォルト：はい）。
--matches — マッチを含める（デフォルト：はい）。
--collections — コレクションを含める（デフォルト：いいえ）。
--collection-ids — エクスポートするコレクションのID（カンマ区切り）。
--match-ids — エクスポートするマッチのID（カンマ区切り、空=すべて）。
--tournament-ids — エクスポートするトーナメントのID（カンマ区切り）。
--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 の値が指定されていない場合は --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でフィルタリングする（カンマ区切り）。
--position-ids — ポジションIDでフィルタリングする：範囲 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（全体、チェッカー、ダブリングキューブ）、直近N手の決定に対する移動平均PR、トップブランダー、ダブリングキューブアクション別の内訳、エラーの大きさのヒストグラム。

オプション（``stats`` タイプのみ）：

--metric — 表示するメトリック：pr または mwc（デフォルト：pr）。
--player — 指定したプレイヤーに限定する。
--tournament — 1つまたは複数のトーナメントIDに限定する（カンマ区切り）。
--from — 開始日（YYYY-MM-DD）。
--to — 終了日（YYYY-MM-DD）。
--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 — 表示するマッチの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 — 説明を削除する。

少なくとも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.15. 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.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 — 削除する要素の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