Skip to content

Commit 1f1860b

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent d87eb06 commit 1f1860b

2 files changed

Lines changed: 253 additions & 0 deletions

File tree

‎assets/commands/blunderbase.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# TAGLINE
2+
3+
Personal chess database with engine analysis and an MCP coach
4+
5+
# TLDR
6+
7+
**Serve** the web app, API, analysis workers, and `/mcp`
8+
9+
```blunderbase serve --host 0.0.0.0 --port 8765```
10+
11+
Import games from a **Lichess** account
12+
13+
```blunderbase import lichess [username]```
14+
15+
Import a **PGN file** of someone else's games (study only, not statistics)
16+
17+
```blunderbase import pgn [path/to/games.pgn] --not-mine```
18+
19+
Register which username is **yours**
20+
21+
```blunderbase accounts add lichess [username]```
22+
23+
Register a **Stockfish** binary and assign the quick and deep roles
24+
25+
```blunderbase engines add sf-local stockfish --option Threads=4 --role quick --role deep```
26+
27+
Queue and run **deep analysis** for up to 50 pending games
28+
29+
```blunderbase analyze --tier deep --limit 50```
30+
31+
Set or **reset the owner password** (prompted twice, never echoed)
32+
33+
```blunderbase set-password```
34+
35+
Write an integrity-checked **database backup**
36+
37+
```blunderbase db backup [path/to/blunderbase.db]```
38+
39+
Run the **MCP coach** on stdio for a local client
40+
41+
```blunderbase mcp```
42+
43+
Print the **version**
44+
45+
```blunderbase --version```
46+
47+
# SYNOPSIS
48+
49+
**blunderbase** [_--version_] _command_ [_options_]
50+
51+
# PARAMETERS
52+
53+
**serve**
54+
> Run the HTTP API, web app, `/events` socket, `/mcp`, and analysis workers.
55+
56+
**--host** _address_
57+
> Bind address for **serve** (default `BLUNDERBASE_HOST`, usually `127.0.0.1`; the Docker image uses `0.0.0.0`).
58+
59+
**--port** _port_
60+
> Bind port for **serve** (default `BLUNDERBASE_PORT`, `8765`).
61+
62+
**--reload**
63+
> Restart **serve** when source files change (development).
64+
65+
**import** _source_ [_target_]
66+
> Import games. _source_ is `lichess`, `chesscom`, `fics`, or `pgn`. _target_ is the account to sync, or the PGN file to read.
67+
68+
**--username** _name_
69+
> Account to sync instead of the positional target.
70+
71+
**--path** _file_
72+
> PGN file instead of the positional target.
73+
74+
**--since** _cursor_
75+
> Resume from this cursor instead of the stored one. `all` reads the whole archive.
76+
77+
**--max-games** _N_
78+
> Stop after N games.
79+
80+
**--not-mine**
81+
> Store PGN games for study without counting them in statistics.
82+
83+
**accounts list**
84+
> Print every registered account and how many games are attributed to it.
85+
86+
**accounts add** _platform_ _username_
87+
> Register an account and claim games it has already played. _platform_ is `lichess`, `chesscom`, `fics`, or `otb`.
88+
89+
**accounts reconcile**
90+
> Re-run owner attribution over games already stored. Idempotent; does not revise a game whose side is already known.
91+
92+
**runners list**
93+
> List remote engine runners, advertised engines, and backlog.
94+
95+
**runners create** _name_
96+
> Register a runner and print its token and `runner.yaml` once (only a hash is stored).
97+
98+
**runners revoke** _name_
99+
> Delete a runner, its token, and the engines it advertised.
100+
101+
**--slots** _N_
102+
> Engine jobs at once when creating a runner (default 1).
103+
104+
**--server** _url_
105+
> How the runner reaches this server (default `BLUNDERBASE_PUBLIC_URL`).
106+
107+
**engines list**
108+
> List engine binaries on this machine, where they live, and which roles they serve.
109+
110+
**engines add** _name_ _path_
111+
> Register a binary. _path_ may be a file, a command line with arguments, or a name on `PATH`.
112+
113+
**engines remove** _name_
114+
> Delete an engine row and unqueue work only it could run.
115+
116+
**--kind** _{uci,maia}_
117+
> Engine kind for **engines add** (default `uci`).
118+
119+
**--option** _NAME=VALUE_
120+
> UCI option, validated against what the binary declares. Repeatable.
121+
122+
**--role** _{quick,deep,human}_
123+
> Assign a role, taking it from whatever holds it. Repeatable.
124+
125+
**--replace**
126+
> Update an existing engine of that name instead of refusing, and enable it.
127+
128+
**--disabled**
129+
> Register an engine without switching it on.
130+
131+
**analyze**
132+
> Enqueue engine analysis and drain the queue in this process. Safe while the server is up; the queue is rows in the database.
133+
134+
**--game-id** _N_
135+
> Analyse one game instead of every pending game.
136+
137+
**--tier** _{quick,deep}_
138+
> Analysis pass (default `quick`).
139+
140+
**--fen** _fen_
141+
> Analyse one position instead of a game.
142+
143+
**--ply-range** _START:END_
144+
> Half-move window for a deep pass (end exclusive).
145+
146+
**--multipv** _N_
147+
> Lines to keep.
148+
149+
**--nodes** _N_
150+
> Per-position node budget.
151+
152+
**--limit** _N_
153+
> Queue at most N games.
154+
155+
**--queue-only**
156+
> Enqueue without running workers.
157+
158+
**--timeout** _seconds_
159+
> Give up waiting (default 3600).
160+
161+
**mcp**
162+
> Run the MCP coach as its own process. **serve** already mounts `/mcp`; this is for a local client over stdio.
163+
164+
**--transport** _{stdio,http}_
165+
> MCP transport (default `stdio`). `http` needs `BLUNDERBASE_MCP_BEARER_KEY`.
166+
167+
**set-password**
168+
> Set or replace the owner's browser password. Asked twice, never echoed. Signs every open session out when replacing.
169+
170+
**db upgrade**
171+
> Apply pending SQLite migrations. Safe on an older backup; a no-op at the current revision.
172+
173+
**db backup** _output_
174+
> Write an integrity-checked copy of the complete database. **--force** replaces an existing output file.
175+
176+
**db restore** _input_
177+
> Replace the configured database with an integrity-checked backup. Stop every process using that file first. **--force** is required to overwrite.
178+
179+
**db rebuild-cards**
180+
> Recompute the stored card of every analysed game.
181+
182+
**db rebuild-stats**
183+
> Recompute the stored stat summary of every analysed game.
184+
185+
**db rebuild-book**
186+
> Recompute the explorer's precomputed opening book.
187+
188+
**demo create**
189+
> Build an anonymized, separate database for a read-only public demo.
190+
191+
**--version**
192+
> Print the version and exit.
193+
194+
# DESCRIPTION
195+
196+
**blunderbase** is a personal chess database. It imports games from Lichess, Chess.com, FICS, and PGN files, analyses them with UCI engines (typically Stockfish) and optionally Maia, and stores games, evaluations, notes, and statistics in one SQLite file you own.
197+
198+
The same library is used three ways: a web app (board, games list, explorer, statistics), an MCP server so an assistant can read the identical data, and this CLI for import, engines, analysis, backup, and headless setup. Everything is one process on one port (default **8765**). A companion binary, **blunderbase-runner**, runs engines on another machine and dials the server.
199+
200+
Typical deployment is the Docker image `ghcr.io/philphilphil/blunderbase:latest` (ships Stockfish; data in `/data`, database `/data/blunderbase.db`). Prefix CLI commands with `docker exec -it blunderbase` against a running container. Desktop installers exist for macOS and Windows; they bundle the app but ship no engine binary and have no MCP endpoint.
201+
202+
The first visitor to a fresh installation chooses the owner password (at least eight characters). There is no second account. MCP clients use minted keys (`bb_mcp_…`) or `BLUNDERBASE_MCP_BEARER_KEY`, not the browser password.
203+
204+
# CONFIGURATION
205+
206+
Every setting is an environment variable with a `BLUNDERBASE_` prefix. Empty means unset (the default applies). Engine budgets, classification thresholds, Maia rating, auto-sync interval, and the Lichess explorer token live in the database and are edited in the app.
207+
208+
**BLUNDERBASE_DB_PATH**
209+
> SQLite library file. Default `<data dir>/blunderbase.db` (`/data/blunderbase.db` in Docker). Decides which library every CLI command touches.
210+
211+
**BLUNDERBASE_DATA_DIR**
212+
> Uploaded PGN files, downloaded engines, and weights. Default `<root>/data`.
213+
214+
**BLUNDERBASE_HOST** / **BLUNDERBASE_PORT**
215+
> Bind address and port for **serve** (defaults `127.0.0.1` and `8765`).
216+
217+
**BLUNDERBASE_PUBLIC_URL**
218+
> How the installation is reached from outside. Written into `runner.yaml` when creating a runner.
219+
220+
**BLUNDERBASE_RUNTIME_MODE**
221+
> `server` (default), `desktop`, or `demo`. `demo` is read-only: no password, no `/mcp`, writes return 403.
222+
223+
**BLUNDERBASE_MCP_BEARER_KEY**
224+
> Extra token `/mcp` accepts, alongside keys minted on the Assistant page.
225+
226+
**BLUNDERBASE_ANALYSIS_WORKERS**
227+
> Whether this process runs analysis workers (default `true`). Turn off when draining the queue with **blunderbase analyze** on another schedule.
228+
229+
**BLUNDERBASE_ANALYSIS_CONCURRENCY**
230+
> Engine processes at once (default: cores minus two, never below 1).
231+
232+
# CAVEATS
233+
234+
Python 3.12+ for a source install (`uv run blunderbase …`). Docker is the supported server path. Restore replaces the database under the process: stop Blunderbase first; **--force** is required to overwrite. Backups include hashed credentials — store them like a password. The three **db rebuild-*** commands are never required for correctness; **serve** already sweeps stats and the book at start-up. Releases through **v0.9.0** were MIT; later releases are **AGPL-3.0-or-later**.
235+
236+
# HISTORY
237+
238+
Written by **Phil Baum**. Public versions began in **August 2026**; **v1.0.0** was cut on **2026-09-06**. The backend is Python (FastAPI, SQLAlchemy, SQLite WAL); the frontend is React. Licence changed from MIT to AGPL-3.0-or-later in **v0.12.0** (2026-09-05).
239+
240+
# SEE ALSO
241+
242+
[gnuchess](/man/gnuchess)(1), [sqlite3](/man/sqlite3)(1), [docker](/man/docker)(1)
243+
244+
# RESOURCES
245+
246+
```[Source code](https://github.com/philphilphil/blunderbase)```
247+
248+
```[Homepage](https://blunderbase.org)```
249+
250+
```[Documentation](https://blunderbase.org/manual/)```
251+
252+
<!-- verified: 2026-09-08 -->

‎assets/commands/index.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -770,6 +770,7 @@ bluetoothd.md
770770
bluetui.md
771771
bluetuith.md
772772
blueutil-tui.md
773+
blunderbase.md
773774
blurlock.md
774775
bmaptool.md
775776
bmm.md

0 commit comments

Comments
 (0)