Package: cli-chess
A highly customizable way to play chess in your terminal. Supports playing online (via Lichess.org) and
offline against the Fairy-Stockfish engine. All Lichess variants are supported.DemoOffline against Fairy-StockfishWatching Lichess Bullet TVMain FeaturesPlay online using your Lichess.org accountPlay offline against the Fairy-Stockfish engineSupports playing all LichessvariantsTheme the chess board and pieces to the colors of your choiceTheme UI components to the colors of your choiceSupports making moves in UCI, SAN, or LANPlay blindfold chessWatch Lichess TVGetting startedOpen your terminal and runpip install cli-chessTypecli-chessto startUse your keyboard arrows, tab, or click to navigate the menus. Multi value menu options
(e.g. changing the variant) can be cycled by pressing spacebar, enter, or by clicking
on the value.Playing OnlineIn order to play online using your Lichess account you will need to create an API token for cli-chess to
authenticate with. Follow the steps below to create the token and register it with cli-chess. Generally, these
steps will only need to be run once as cli-chess will remember the API token.Open your browser and login to your Lichess accountClickhereto create a Lichess API token for cli-chess to authenticate with(NOTE: Do not uncheck any of the
token permissions as these are required by cli-chess)Click "Create"Highlight and copy the tokenRun cli-chess using the following command:cli-chess --token ****(replace *'s with your API token)Custom stylingNearly every component of cli-chess can be styled by overriding parts of thedefault style elementsin thecustom_style.pyfile. This file will be located at$HOME/.config/cli-chess/for Linux and macOS and$APPDATA/cli-chess/for Windows.Colors are expected to beHTML color names(e.g.seagreen)
orHTML hex colors(e.g.#2E8B57). The display of selected
colors is dependent on the terminal supporting true colors and theTerminal Color Depthoption in cli-chess program
settings being set toTrue Colors). If the terminal does not support true colors, the colors selected will be mapped
to the closest supported color.Restarting cli-chess, or pressingCtrl+Ron any screen will force a style refresh. If this custom style sheet is
invalid in any way, the default cli-chess style will be applied. This file must be kept in dictionary format.Examplecustom_style.pyto override board and piece colors:{"light-square":"bg:wheat","light-square.light-piece":"fg:white","light-square.dark-piece":"fg:black","dark-square":"bg:#2E8B57","dark-square.light-piece":"fg:white","dark-square.dark-piece":"fg:black","last-move":"bg:slateblue","last-move.light-piece":"fg:white","last-move.dark-piece":"fg:black","in-check":"bg:#FFA500","in-check.light-piece":"fg:white","in-check.dark-piece":"fg:black"}Questions1. How do I make a move?Moves are case-sensitive and must be made in SAN, LAN, or UCI. Moves cannot be made using the mouse.
Pawn promotions must specify the promotion piece type (e.g.e8=Qore7e8q).
Moves that are ambiguous must specify thefrom squarewhen using SAN (e.g.Ncd6).
To drop a piece in Crazyhouse, use the@symbol (e.g.Q@g4).If you need more information on move notation, see Appendix C ofFIDE Laws of Chess.2. How do I increase the size of the board?The only way to increase the size of the board is to increase the size of the
font you're using. Many terminals also supportCtrl +to increase the terminal size.3. The board or chess pieces aren't aligned or displaying properly, how can I fix this?As cli-chess is a terminal based program, it has been designed to be used
with a monospace type font. A monospace font should always be used in order for
character alignment to be consistent. The display of cli-chess can change drastically
depending on the font being used, so it's important to choose a font that works best
for your terminal and display preferences. The fonts that I have found to work best with
cli-chess for piece alignment areUbuntu Mono,MS Gothic, andNSimSun.4. What operating systems are supported?Linux, Windows, and macOS. Development is mainly focused and will be prioritized for
Linux as it's readily available for me to test on. Regardless of operating system,
please report any issues found and I will do my best to support.5. Can I use a different chess engine?Playing offline vs the computer iscurrentlyonly directly compatible with theFairy-Stockfishengine.
For simplicity, the Fairy-Stockfish binaries come pre-built with cli-chess for Linux, Windows, and macOS(x86-64 (and arm64 for macOS) architecture).