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

Or for unstable release from the source code:

$ python3 -m pip install .

Arch Linux

AUR version

Package is on AUR.

Using trizen:

$ trizen -S ai-dungeon-cli-git

Old school way:

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


Unless specified, all user inputs are considered Do actions.

Quoted input entries are automatically interpreted as Say actions, e.g.:

> "Hey dragon! You didn't invite me to the latest BBQ party!"

Do be explicit about the action type, prefix your input with a command:

  • /do
  • /say
  • /story
  • /remember

For example, the previous Say prompt could also be written:

> /say Hey dragon! You didn't invite me to the latest BBQ party!

To quit, either press Ctrl-C, Ctrl-D or type in the special /quit command.


In any case, you first need to create a configuration file.


$ ai-dungeon-cli

From source

With a conda env (assuming you're using anaconda):

$ cd ai-dungeon-cli
$ conda env create
$ conda activate ai-dungeon-cli-env
$ ./ai_dungeon_cli/

With a viltualenv:

$ cd ai-dungeon-cli
$ virtualenv -p $(command -v python3) ai-dungeon-cli-venv
$ source ai-dungeon-cli-venv/bin/activate
$ python3 -m pip install -r requirements.txt
$ ./ai_dungeon_cli/

Please note that all those examples use a virtual env in order to not mess up with the main Python env on your system.

Configuration (optional)

Several things can be tuned by resorting to a config file.

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


By default, if no authentication configuration is provided, an anonymous session is created.

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 the content of the connection_init message of the websocket communication (first sent message).

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

Slow Typing Animation

By default, responses are printed to the screen instantly.

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

slow_typing_effect: True


The default user prompt is '> '.

You can customize it with e.g. :

prompt: 'me: '

Command-line arguments

All configuration options are mapped to command-line arguments.

Additionally, some features (such as multi-player support) are only available through those arguments.

The list of all arguments can be retrieved by calling ai-dungeon-cli with either -h of --help.


One can use either the --auth-token <token> or --email <email> --password <password> arguments to authenticate.

Slow Typing Animation

Just append --slow-typing to your execution call to enable this fancy effect.


The custom prompt can be set with --prompt '<prompt>'.


To join an existing multi-player adventure, use arguments --adventure <public-adventure-id> --name <character-name>.


TO enable debug mode and see the responses from the API, use --debug. This option is mainly useful for developers.


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 /revert and /alterspecial actions are not supported.

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
  • Alexander Batyrgariev @sasha00123: help on porting to new websocket/gql-based version of the API

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.

Similar projects

Project details

Download files

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

Source Distribution

ai-dungeon-cli-0.4.5.tar.gz (16.0 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page