Skip to main content

Frequently Asked Questions

The board looks corrupted or shows weird characters​

chess-tui uses Unicode chess symbols and box-drawing characters. If your board looks broken:

  1. Use a Unicode-capable font — Install a patched font like Nerd Fonts and set your terminal to use it.
  2. Switch to ASCII mode — If your terminal has poor Unicode support, switch the display mode in your config: 
    # CONFIG_DIR/chess-tui/config.toml
    display_mode = "ASCII"
    Or press s in-game to cycle to the ASCII skin.
  3. Try a different terminal — iTerm2, Alacritty, Kitty, and WezTerm have good Unicode support.

Pieces are tiny or huge​

Use Ctrl + and Ctrl - to zoom in and out. Piece rendering automatically adapts to the cell size.

note

Zoom shortcuts may differ depending on your terminal. If Ctrl+/- doesn't work, try resizing the terminal window directly.

The bot never moves / hangs​

  1. Make sure your engine path is valid and the binary is executable.
  2. Test the engine manually: echo "uci" | /path/to/engine — you should see uciok.
  3. Some engines like GNU Chess require a --uci flag: 
    chess-tui -e "/path/to/gnuchess --uci"
  4. Enable debug logging to see what's happening: 
    log_level = "DEBUG"
    Then check CONFIG_DIR/chess-tui/logs/.

See Bot Configuration for full setup details.

No sound​

Sound requires an audio device. In Docker or headless environments it is automatically disabled. You can also explicitly disable it with --no-sound or sound_enabled = false in your config.

See Sound for full details.

chess-tui doesn't work well on Windows​

chess-tui is tested on Windows in CI. Known limitations:

  • Broken characters — cmd.exe and old PowerShell have poor Unicode support. Use Windows Terminal for the best experience.
  • Sound issues — Use --no-sound if sound causes problems.
  • Font — Make sure your terminal is using a font with Unicode chess symbol support.

Lichess token keeps getting rejected​

  1. Make sure you generated the token with the correct scopes: Read preferences, Create/read/update/delete games, Read puzzle activity.
  2. Tokens can expire — generate a new one at lichess.org/account/oauth/token.
  3. Check your internet connection — the token is validated against the Lichess API on first use.

See Lichess Setup for full details.

How do I update chess-tui?​

# Homebrew
brew upgrade chess-tui

# Cargo
cargo install chess-tui

# Debian/Ubuntu — re-run the install one-liner from the Installation guide

Where is the config file?​

PlatformPath
Linux$XDG_CONFIG_HOME/chess-tui/ or $HOME/.config/chess-tui/
macOS$HOME/Library/Application Support/chess-tui/
Windows%APPDATA%\chess-tui\

The config file is config.toml and the skins file is skins.json inside that directory.