BlindBase – Accessible Chess-Study CLI
BlindBase is a text-mode chess study tool that brings Stockfish analysis, Lichess Masters statistics and speech feedback to the terminal. It is designed for visually-impaired players but equally useful for anyone who prefers a distraction-free CLI over a GUI.
Features
- Interactive board with Rich ASCII graphics or screen-reader-friendly layout.
- Fast Stockfish analysis (multi-PV).
- Masters moves tree (lichess.org database).
- PGN navigation, variation editing, comments.
- Broadcast streaming of live games.
- Speech synthesis (optional) via
pyttsx3. - Ships with Stockfish binaries for macOS (arm64 + x86_64) and Windows x64 – no separate download required.
- Stand-alone executables ship with Stockfish (macOS arm64/x86_64 and Windows x64) — no separate download required, while the PyPI wheel stays slim and expects Stockfish in your PATH.
Quick start
pip install blindbase # installs lightweight wheel (Stockfish required, see below)
blindbase play games.pgn # open PGN browser
Command list appears below the board; type a
Quick start (continued)
Command list appears below the board; type a to start engine analysis, t to view Masters moves, m to save.
Install Stockfish (required for pip users)
The PyPI wheel is lightweight and does not include the Stockfish engine. Install Stockfish once and make sure it is discoverable from the shell:
• macOS – brew install stockfish
• Windows – download stockfish_15_x64_avx2.exe (or the ..._noavx2.exe if your CPU lacks AVX2) from the official site and place it somewhere in your %PATH% (e.g. C:\Windows\System32).
• Linux – sudo apt install stockfish or your distro's package.
Alternatively, pass an explicit path:
blindbase play games.pgn --engine /full/path/to/stockfish
The single-file executables (blindbase_mac_arm64, blindbase.exe, …) already contain the correct engine and do not need this step.
Building from source
git clone https://github.com/itshak/blind-base-cli.git
cd blind-base-cli
pip install -e .[dev] # editable install with dev extras
Run unit tests:
pytest -q
Single-file executables
The repo provides scripts and CI workflow to create stand-alone binaries (no Python required).
Local Apple-Silicon build
python3 -m venv venv
source venv/bin/activate
pip install . pyinstaller
python -m PyInstaller \
--clean --onefile --target-arch arm64 \
--name blindbase_mac_arm64 \
--add-binary blindbase/engine/mac/stockfish:engine \
blindbase/menu.py
dist/blindbase_mac_arm64 runs on Apple-Silicon and Intel Macs (via Rosetta).
CI builds (Intel macOS & Windows)
GitHub Actions workflow release.yml publishes artefacts on every push tag:
blindbase_mac_x86_64– native Intel Mac binaryblindbase.exe– Windows 64-bit binary
Download them from the Actions → run → Artefacts section.
Package layout
blindbase/
├─ menu.py # interactive main menu
├─ app.py # Typer entry-point
├─ engine/ # bundled Stockfish binaries (for PyInstaller builds)
│ ├─ mac/stockfish (arm64)
│ ├─ mac/stockfish_x86 (x86_64)
│ └─ win/stockfish.exe (win64)
└─ ...
packaging/
├─ build_macos.py # PyInstaller helper script
└─ build_windows.py
Contributing
Pull requests are welcome! Please open an issue first to discuss major changes.
- Fork → feature branch → PR.
- Run
pre-commit run --all-filesbefore pushing. - Ensure
pytestandruffpass.
License
BlindBase is licensed under the MIT License. Stockfish binaries are GPLv3; they are distributed unmodified in the engine/ directory – see engine/LICENSE. By using the one-file executables you accept the terms of Stockfish's GPL.
- CI builds produce single-file executables for macOS (arm64 + x86_64) and Windows x64.
1 maintainer
Metadata
1 maintainer
Release files for blindbase 0.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| blindbase-0.13.0.tar.gz | 52.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| blindbase-0.13.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 113.7 kB
Release files / blindbase-0.13.0.tar.gz
| Download URL | blindbase-0.13.0.tar.gz |
|---|---|
| Size | 52.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b74c128ca6fdc4a6b4a9cc709262654afdde0718af24c82778ac13dfeccd0027
|
|
BLAKE2b-256 checksum How to use checksums |
bc3ac46b73eb395370cbfb8598db73babab5280ed361776f5a0abc8de2302217
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 20, 2025.
Transparency logRelease files / blindbase-0.13.0-py3-none-any.whl
| Download URL | blindbase-0.13.0-py3-none-any.whl |
|---|---|
| Size | 60.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7eb590ba8379219c8ba51ecfb9be3daa068f24bd4ad53709e6172cd90a958a14
|
|
BLAKE2b-256 checksum How to use checksums |
c4dd2b9a0fcc3c75bf32f1b0533b4e914926b1111eb0d9527b22c939e92aa46c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 20, 2025.
Transparency log
