Skip to main content

Play ai dungeon from your terminal

Project description

AI Dungeon CLI

This is basically a cli client to

This allows playing AI Dungeon 2 inside a terminal.

I primarily did this to play the game on a DEC VT320 hardware terminal for a more faithful experience.

For more context, read the accompanying blog post.

AI DUngeon on a VT320



PyPI version

$ python3 -m pip install ai-dungeon-cli

Of for unstable release from the source code:

$ python3 -m pip install .

Arch Linux

Package is on AUR.

$ git clone
$ cd ai-dungeon-cli-git
$ makepkg -si


In either way, you first need to create a configuration file.

If installed with pip:

$ ai-dungeon-cli

Or from source:

$ cd ai-dungeon-cli
$ python3 -m pip install -r requirements.txt
$ ./ai_dungeon_cli/

Please note that it is recommended to do it in a virtual env in order to not mess up with the main Python env on your system.


Create a file config.yml either:

  • in the same folder in your home folder: $HOME/.config/ai-dungeon-cli/config.yml
  • in the same folder as the sources: ./ai-dungeon-cli/ai_dungeon_cli/config.yml

Authentication (mandatory)

ai-dungeon-cli supports 2 ways to configure user authentication.

Either precise a couple of credentials in conf:

email: '<MY-USER-EMAIL>'
password: '<MY-USER-PASSWORD>'

Or sniff a Authentication Token and use it directly:

auth_token: '<MY-AUTH-TOKEN>'

To get this token, you need to first login in a web browser to

Then you can find the token either in your browser localStorage or in X-Auth-Token Request Header of the POST inputs requests made while playing.

Either way, developer tools (F12) is your friend.


The default user prompt is '> '.

You can customize it with e.g. :

prompt: 'me: '


Please have a look at requirements.txt.

Limitations and future improvements

Right now, the code is over-optimistic: we don't catch cleanly when the backend is down.

A better user experience could be achieved with the use of the curses library.

For now, only the /quit and remember actions are supported. I need to enable the others (/revert, /alter...).

It would also be nice to add support for browsing other players' stories (Explore menu).

Implementation details

We fallback to a pure ASCII version of the splash logo if we detect an incompatible locale / terminal type.


As you might have heard, hosting AI Dungeon costs a lot of money.

This cli client relies on the same infrastructure as the online version (

So don't hesitate to help support the hosting fees to keep the game up and running.


Jordan Besly @p3r7 (blog).


Major contributions:

  • Idan Gur @idangur: OOP rewrite of game logic
  • Alberto Oporto Ames @otreblan: packaging, submission to AUR

Minor contributions:

  • Robert Davis @bdavs: pip requirements
  • @Jezza: suggested login using creds

Project details

Release history Release notifications

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ai-dungeon-cli, version 0.1.3
Filename, size File type Python version Upload date Hashes
Filename, size ai_dungeon_cli-0.1.3-py2-none-any.whl (8.3 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size ai-dungeon-cli-0.1.3.tar.gz (7.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page