# 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
```bash
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](https://stockfishchess.org/download/) 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:
```bash
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
```bash
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:
```bash
pytest -q
```
## Single-file executables
The repo provides scripts and CI workflow to create stand-alone binaries (no Python required).
### Local Apple-Silicon build
```bash
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`](.github/workflows/release.yml) publishes artefacts on every push tag:
- `blindbase_mac_x86_64` – native Intel Mac binary
- `blindbase.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.
1. Fork → feature branch → PR.
2. Run `pre-commit run --all-files` before pushing.
3. Ensure `pytest` and `ruff` pass.
## 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "blindbase",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "chess, cli, accessibility, stockfish, blind, pgn",
"author": null,
"author_email": "Alexey Streltsov <iitshak@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5f/fe/896a302c51b337c0195032a285dfd1347c96d0ae630db12db8bb23090f18/blindbase-0.12.10.tar.gz",
"platform": null,
"description": "# BlindBase \u2013 Accessible Chess-Study CLI\n\nBlindBase 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.\n\n## Features\n\n- Interactive board with Rich ASCII graphics or screen-reader-friendly layout.\n- Fast Stockfish analysis (multi-PV).\n- Masters moves tree (lichess.org database).\n- PGN navigation, variation editing, comments.\n- Broadcast streaming of live games.\n- Speech synthesis (optional) via `pyttsx3`.\n- Ships with Stockfish binaries for macOS (arm64 + x86_64) and Windows x64 \u2013 no separate download required.\n- Stand-alone executables ship with Stockfish (macOS arm64/x86_64 and Windows x64) \u2014 no separate download required, while the PyPI wheel stays slim and expects Stockfish in your PATH.\n\n## Quick start\n\n```bash\npip install blindbase # installs lightweight wheel (Stockfish required, see below)\n\nblindbase play games.pgn # open PGN browser\n```\n\nCommand list appears below the board; type `a`\n\n## Quick start (continued)\n\nCommand list appears below the board; type `a` to start engine analysis, `t` to view Masters moves, `m` to save.\n\n### Install Stockfish (required for pip users)\n\nThe PyPI wheel is lightweight and **does not include** the Stockfish engine. Install Stockfish once and make sure it is discoverable from the shell:\n\n\u2022 **macOS** \u2013 `brew install stockfish`\n\n\u2022 **Windows** \u2013 download `stockfish_15_x64_avx2.exe` (or the `..._noavx2.exe` if your CPU lacks AVX2) from the [official site](https://stockfishchess.org/download/) and place it somewhere in your `%PATH%` (e.g. `C:\\Windows\\System32`).\n\n\u2022 **Linux** \u2013 `sudo apt install stockfish` or your distro's package.\n\nAlternatively, pass an explicit path:\n\n```bash\nblindbase play games.pgn --engine /full/path/to/stockfish\n```\n\nThe single-file executables (`blindbase_mac_arm64`, `blindbase.exe`, \u2026) already contain the correct engine and do **not** need this step.\n\n## Building from source\n\n```bash\ngit clone https://github.com/itshak/blind-base-cli.git\ncd blind-base-cli\npip install -e .[dev] # editable install with dev extras\n```\n\nRun unit tests:\n\n```bash\npytest -q\n```\n\n## Single-file executables\n\nThe repo provides scripts and CI workflow to create stand-alone binaries (no Python required).\n\n### Local Apple-Silicon build\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install . pyinstaller\npython -m PyInstaller \\\n --clean --onefile --target-arch arm64 \\\n --name blindbase_mac_arm64 \\\n --add-binary blindbase/engine/mac/stockfish:engine \\\n blindbase/menu.py\n```\n\n`dist/blindbase_mac_arm64` runs on Apple-Silicon and Intel Macs (via Rosetta).\n\n### CI builds (Intel macOS & Windows)\n\nGitHub Actions workflow [`release.yml`](.github/workflows/release.yml) publishes artefacts on every push tag:\n\n- `blindbase_mac_x86_64` \u2013 native Intel Mac binary\n- `blindbase.exe` \u2013 Windows 64-bit binary\n\nDownload them from the **Actions \u2192 run \u2192 Artefacts** section.\n\n## Package layout\n\n```\nblindbase/\n \u251c\u2500 menu.py # interactive main menu\n \u251c\u2500 app.py # Typer entry-point\n \u251c\u2500 engine/ # bundled Stockfish binaries (for PyInstaller builds)\n \u2502 \u251c\u2500 mac/stockfish (arm64)\n \u2502 \u251c\u2500 mac/stockfish_x86 (x86_64)\n \u2502 \u2514\u2500 win/stockfish.exe (win64)\n \u2514\u2500 ...\npackaging/\n \u251c\u2500 build_macos.py # PyInstaller helper script\n \u2514\u2500 build_windows.py\n```\n\n## Contributing\n\nPull requests are welcome! Please open an issue first to discuss major changes.\n\n1. Fork \u2192 feature branch \u2192 PR.\n2. Run `pre-commit run --all-files` before pushing.\n3. Ensure `pytest` and `ruff` pass.\n\n## License\n\nBlindBase is licensed under the MIT License. Stockfish binaries are GPLv3; they are distributed unmodified in the `engine/` directory \u2013 see `engine/LICENSE`. By using the one-file executables you accept the terms of Stockfish's GPL.\n\n- CI builds produce single-file executables for macOS (arm64 + x86_64) and Windows x64.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Accessible CLI chess study tool with Stockfish analysis and Lichess integration.",
"version": "0.12.10",
"project_urls": {
"Homepage": "https://github.com/itshak/blind-base-cli"
},
"split_keywords": [
"chess",
" cli",
" accessibility",
" stockfish",
" blind",
" pgn"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "36e8b1eb1bb7a1e8241a3ffba4df7a13cafd6b60fc9eea9cfae70cf14c669cec",
"md5": "606975a9759a8d715d6122dd064d0c26",
"sha256": "39697c2d1040de79e2d5a203f17bb6e0bd4fa54e629c0e10c040755d8e16edd7"
},
"downloads": -1,
"filename": "blindbase-0.12.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "606975a9759a8d715d6122dd064d0c26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 54846,
"upload_time": "2025-07-17T13:29:30",
"upload_time_iso_8601": "2025-07-17T13:29:30.342698Z",
"url": "https://files.pythonhosted.org/packages/36/e8/b1eb1bb7a1e8241a3ffba4df7a13cafd6b60fc9eea9cfae70cf14c669cec/blindbase-0.12.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5ffe896a302c51b337c0195032a285dfd1347c96d0ae630db12db8bb23090f18",
"md5": "0f74900bd2971b230b9addf5276fda8d",
"sha256": "58bc097bfff1121013bf5a0281e9d33d81ec65ea3b0d571e64f581ff4d202b43"
},
"downloads": -1,
"filename": "blindbase-0.12.10.tar.gz",
"has_sig": false,
"md5_digest": "0f74900bd2971b230b9addf5276fda8d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 47583,
"upload_time": "2025-07-17T13:29:31",
"upload_time_iso_8601": "2025-07-17T13:29:31.535988Z",
"url": "https://files.pythonhosted.org/packages/5f/fe/896a302c51b337c0195032a285dfd1347c96d0ae630db12db8bb23090f18/blindbase-0.12.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 13:29:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "itshak",
"github_project": "blind-base-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "typer",
"specs": [
[
">=",
"0.9"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13"
]
]
},
{
"name": "python-chess",
"specs": [
[
">=",
"1.999"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.26"
]
]
},
{
"name": "pyinstaller",
"specs": [
[
">=",
"6.6.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"1.10"
]
]
},
{
"name": "pydantic-settings",
"specs": [
[
">=",
"2.0"
]
]
},
{
"name": "pygame",
"specs": [
[
"==",
"2.6.1"
]
]
},
{
"name": "pyobjc-core",
"specs": []
},
{
"name": "pyobjc-framework-Cocoa",
"specs": []
},
{
"name": "pytest",
"specs": [
[
">=",
"7"
]
]
},
{
"name": "tomlkit",
"specs": [
[
">=",
"0.12"
]
]
},
{
"name": "tomlkit",
"specs": [
[
">=",
"0.12"
]
]
}
],
"lcname": "blindbase"
}
JSON
