# command-line-chess puts a brute-force engine and a terminal board in one pip package

> command-line-chess is a small Python program that renders a chessboard in the terminal and plays against a brute-force engine, with two-player mode, PGN output and a legal-move list. It is easy to install and easy to outgrow.

**marcusbuffett/command-line-chess** — A python program to play chess against an AI in the terminal.

- Repository: https://github.com/marcusbuffett/command-line-chess
- Stars: 533 · Forks: 182
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/marcusbuffett-command-line-chess

## A terminal chessboard for people who already live in the terminal

The pitch is short: a Python program to play chess against an AI in the terminal. The package installs from PyPI under the name cl-chess and exposes a single console command, chess, declared in setup.py as an entry point pointing at src.main:main. The dependency list is one entry, colored, and the source layout is a src package with a tests directory, a pytest.ini and a mypy.ini at the top level.

That tells you a lot about the shape of the project. This is a teaching and hobby implementation rather than a performance engine, and the same README that describes the game also points readers to a separate chess training site, so the audience is people who want a quick game or a readable codebase rather than a serious competitor.

The board is drawn in the terminal, and the default theme is plain. A checkered theme is available behind a flag. The color of each player is configurable as well, which sounds trivial until you realize the default is the literal string white and the literal string black, so the option is a cosmetic preference for how the pieces are rendered, not a way to swap which side the engine plays.

## The engine counts material and searches every branch without pruning

The technical section of the README is the most revealing part of the project, because it states the engine's limits outright. The AI is described as a simple brute-force AI with no pruning. It evaluates a position by counting the value of the pieces for each side, with pawn worth 1, knight and bishop worth 3, rook worth 5 and queen worth 9.

That is the whole evaluation function, and it is worth being blunt about what it means. There is no positional term, no king safety term, no mobility, no passed-pawn or bishop-pair bonus. The engine cannot see a fork unless the material count after the fork is higher, and it will happily give up a queen for a rook in the wrong line if the arithmetic of that particular branch favours it. It also cannot recognise a checkmate as more valuable than a winning piece count.

The search itself evaluates the tree of moves and takes the path that produces the greatest gain. With no pruning, the search space grows with the depth of the tree, and the README links to a longer post explaining how the search works. The practical consequence is that playing against it is easy once you know how it sees the board, and that is exactly the reason to look at this project if your interest is in reading a small, legible game-AI implementation rather than in winning games.

The legal move list command, l, prints every legal move for the current position, which is a good way to check that the board state is being tracked correctly and a shortcut to legal moves in the input syntax.

## One command, one board, and a small set of prompt commands

Interaction is by typed text at the board, and the command set is documented as a list. A move looks like a3, Nc3 or Qxa, in other words the usual algebraic notation. Then there is l to print every legal move, r to make a random move, u to undo your last move, quit to resign the current game, gm to print the moves of the current game in PGN format, and ? to print help with all available commands.

The undo command is the one that changes how the program feels in practice. In a terminal chess program, an accidental input, or a move the human regrets, is otherwise fatal to the session, and restarting a whole game to fix a single bad move is punishing. Being able to take the last move back removes that friction.

The random move command has a different purpose. It is a way to hand control to the engine and watch the line play out, and combined with undo it is a reasonable way to explore a position. The PGN export via gm is a small but real feature, since it gives you a portable record of a game you can load into other chess tooling, and it is the only output format the README mentions.

Two-player mode is a flag rather than a subcommand in practice. The README also mentions running chess --two to enter it, and the usage output spells the same option out as -t, --two, to play a 2-player game, default False.

## Installing from PyPI or from source takes two commands either way

Installation is the least interesting part of this project, and that is a compliment to a hobby tool. From PyPI, the README gives a single command:

```bash
pip install cl-chess
```

The install from source route starts with a clone:

```bash
git clone https://github.com/marcusbuffett/command-line-chess
```

You then move into the newly created command-line-chess directory and install the package in place:

```bash
pip install .
```

Either path gives you the chess command. The README points to the help flag for the full option list, and the usage block it prints looks like this:

```sh
usage: chess [-h] [-t] [-w W] [-b B] [-c]
A python program to play chess against an AI in the terminal.
optional arguments:
  -h, --help       show this help message and exit
  -t, --two        to play a 2-player game (default: False)
  -w W, --white W  color for white player (default: white)
  -b B, --black B  color for black player (default: black)
  -c, --checkered  use checkered theme for the chess board (default: False)
Enjoy the game!
```

The four options are all cosmetic or mode switches. There is no option for search depth, no option to set a time control, no option to load a position from FEN and no option to select an opponent. That absence is the design, not an oversight, and it is the first thing to check if you want more than the defaults.

## No releases, no depth control, and a last push in April 2026

Two maintenance facts bear on any decision here. The repository has no GitHub releases, so there is no changelog to read and no tagged upgrade path, even though the project is published on PyPI under the name cl-chess. The version string in setup.py reads 1.2.7, which is the only version marker visible in the source, and there is no way to tell from the repository alone which PyPI release corresponds to which commit.

Second, the last push to the repository was on 2026-04-13. The README carries a maintenance badge, but a badge is a static image, not a status you can rely on. Nothing in the documentation indicates an ongoing release schedule, and the last commit date is the fact to plan around if you depend on this package.

The license is MIT, and the repository ships a LICENSE file, a CODE-OF-CONDUCT.md, a CONTRIBUTING.md and a FUNDING.yml. The contribution guide points contributors at a pre-commit configuration, and the presence of .flake8, mypy.ini and pytest.ini suggests the project takes its own linting and test setup seriously, even though the test suite itself is not described in the README.

There is also a hosted path worth noting. The README carries a Run on Repl.it badge, so the program can be launched in a browser-hosted Python environment rather than installed locally.

## Where command-line-chess is the wrong tool

The failure mode is not a crash, it is a ceiling. Because the evaluation counts material alone, a player who understands that a queen is worth 9 can beat the engine without any chess theory at all. Push a pawn, trade when the count improves, and the arithmetic will hand you wins that a beginner would not win against a real opponent. If your goal is a fair game at any level, this is the wrong tool, and no amount of waiting for an update will change the evaluation function.

There is a second gap. There is no option to set search depth, and no time control, so you cannot trade strength for speed or the other way round. The move list command, the undo command and the random move command are all there for inspection and convenience, but the engine itself has one fixed behaviour.

For a real opponent, the difference in approach is that established engines evaluate with many positional terms and use pruning to search deep enough, whereas this one searches a tree with no pruning and a single material term. A GUI chess client on the desktop, or a training site, gives you a rating, a puzzle flow and a graphical view; this gives you a text board you can drive from the keyboard and a source tree small enough to read in one sitting. The tool to pick depends on whether you want to play or to understand how a small engine is put together.

## Conclusion

command-line-chess fits an engineer who wants a terminal chessboard that installs with pip and runs with no GUI, and who is content to lose to a piece-counting opponent. It does not fit anyone who needs opening theory, a tablebase or a real rating. Before adopting, check that the version you install matches your Python 3 environment, and note that the last push to the repository was on 2026-04-13, which leaves the strength of the engine and the board rendering in need of your own verification.

## FAQ

### How do I install command-line-chess on my machine?

Install the PyPI package with pip install cl-chess, or clone the repository and run pip install . from the command-line-chess directory. Either route gives you the chess command.

### How strong is the AI opponent in command-line-chess?

The README describes it as a simple brute-force AI with no pruning that evaluates positions by counting piece values only, with pawns at 1, knights and bishops at 3, rooks at 5 and queens at 9. There is no depth or difficulty option in the usage output.

### Can I play two-player chess in command-line-chess?

Yes. Pass the two-player option, which the usage output lists as -t, --two, to play a 2-player game instead of against the engine.

### Can I export a game from command-line-chess to PGN?

Yes, the gm command prints the moves of the current game in PGN format.

## Sources

- [Issues](https://github.com/marcusbuffett/command-line-chess/issues)
- [License: MIT](https://github.com/marcusbuffett/command-line-chess/blob/master/LICENSE)
- [marcusbuffett/command-line-chess on GitHub](https://github.com/marcusbuffett/command-line-chess)
- [README](https://github.com/marcusbuffett/command-line-chess/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/marcusbuffett-command-line-chess