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.