Eclectic Media Git caffeine / V0.1

Tree @V0.1 (Download .tar.gz)


Executes a user script that either enables or disables a screensaver, then "gives the user a coffee" by rendering an image of a coffeecup as ascii art.

The script uses the developer API to obtain random images of coffee cups, then uses asciiview/aview to display that image as asciiart in the terminal. To obtain your own developer key, please see


The repository provides a utility script to enroll new key's securely, so the user does not need to enter their API key every time. See utils/ for more.

Take a look at a demo here:


Almost all dependencies are handled via Pypi/pip, so one can install amost everything with:

pip3 install -r requirements.txt; pip3 install .

You should probably do that in a virtual environment...

python3 -m venv venv; source venv/bin/activate; pip3 install requirements.txt; pip3 install .

Unfortunately, aview is not something that can be handled via the pip installer. Obtain it with apt (or other package managers):

sudo apt-get install aview imagemagick  # imagemagick is a helper library for aview

It is also useful to save your API key to local storage and ensure that the file is only read access to you and no other users. To do so, use the utility script:

./utils/  # saves key to ~/.config/caffeine/keyfile

The software will always attempt to run a script, and will fail if no script can be found. The software looks for scripts on the following paths:



for the software to discover the script properly, it must be executable and contain a shebang line.

The software will call your script with one of two arguments:

enable --OR-- disable

Your script should handle these argument states, where enable tells the script to enable the screensaver. Aside from handling the argument and being executable, there are no specific requirements for what the script should do. This is so that you can patch in whatever method you need for screensaver interaction. Therefore, to complete the setup you will need to set up your script and include it on one of the above paths. For example scripts, check the examples/ directory.


Once the module has been installed via Pypi/pip, you can simply run:

caffeine  # disables screen saver (passes 'disable' to script)
decaf     # enables screen saver (passes 'enable' to script)


Under the MIT license, circa 2020 by Ariana Giroux (


To submit a bug, include any relavent details in an email to

We use a git native pull request workflow for patch submission.

First, clone the repository:

git clone git://

Then, once you've made your changes, push your copy to a publicly accessible location (i.e GitLab):

git remote add upstream $(git remote get-url origin)  # keep the master repository link as upstream
git remote set-url origin *YOUR REPO URL*  # change origin to your public URL

git push origin

Once you are confident in your changes, submit a git native pull request to

git request-pull origin upstream  # outputs pull request text, copy this into your email.

Please ensure you include a short description of the changed you've made.