A FUSE filesystem that manages your Lichess correspondence games as normal files and directories on your local machine.
- Create a Lichess API access token (See https://lichess.org/account/oauth/token).
- Export the required environment variable:
export CHESSFS_LICHESS_ACCESS_TOKEN="your-token-here"- Create a mount directory:
mkdir -p /mnt/chess- Start the filesystem:
chessfs /mnt/chessTo see the Lichess API requests and the underlying FUSE calls, enable debug mode:
chessfs -debug /mnt/chessThe mounted tree looks like this:
<mountpoint>/
├── correspondence/
│ ├── games/
│ │ ├── <white>(<rating>).<black>(<rating>).<game-id>/
│ │ │ ├── move
│ │ │ ├── resign
│ │ │ ├── draw
│ │ │ ├── takeback
│ │ │ ├── abort
│ │ │ ├── claim-victory
│ │ │ ├── claim-draw
│ │ │ └── status
│ │ └── ...
│ ├── results/
│ │ ├── <white>(<rating>).<black>(<rating>).<game-id>
│ │ └── ...
│ ├── challenge-random
│ ├── challenge-ai
│ └── ...
└── ...
correspondence/games/lists active correspondence games you are currently playing.- Each live game directory contains action files and a
statusfile. challenge-randomandchallenge-aiare writable action files used to start a new game.results/lists recent finished correspondence games with PGN files.- Read action files for instructions on how to write to it.
- Read the
statusfile for the current position, turn, etc.
This is required.
It should contain a valid Lichess personal access token used to authenticate requests to the Lichess API.
Example:
export CHESSFS_LICHESS_ACCESS_TOKEN="xxxxxxxxxxxxxxxx"You can generate a token in your Lichess account settings, then export it in your shell before starting chessfs.
These variables are optional and have defaults if omitted.
Controls how many finished correspondence games appear under correspondence/results.
- Default:
10 - Example:
export CHESSFS_MAX_FINISHED_CORRESPONDENCE_GAMES=25Controls how the board is rendered in the status file.
- Default:
styled - Valid values:
styledtext
Example:
export CHESSFS_BOARD_STYLE=textSets the color used for light squares in the styled board.
- Default:
#9AAABD - Accepts a hex value with or without the leading
#
Example:
export CHESSFS_LIGHT_SQUARE_HEX=F0F8FFSets the color used for dark squares in the styled board.
- Default:
#4D5D70 - Accepts a hex value with or without the leading
#
Example:
export CHESSFS_DARK_SQUARE_HEX=2F4F4FTurns on or off the dark-theme styling used by the board display in text mode.
- Default:
true - Accepts boolean values like
trueorfalse
Example:
export CHESSFS_DARK_MODE=falseIf Lichess responds with 429 Too Many Requests, chessfs waits 60 seconds and tries the request again. If the same error happens again, it returns an error.