Skip to content
🏰 A cli client to
Python Shell
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.

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: '

Slow Typing Animation

By default, responses are printed to the screen instantly.

To enable a fun "slow" typing animation, use:

slow_typing_effect: True


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).

Contributors & acknowledgements

Major contributions:

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

Minor contributions:

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

Code for slow typing effect inspired by this message from Magnus Lycka on the Python Tutor mailing list.

You can’t perform that action at this time.