Get your daily dose of xkcd directly from the terminal! 🤩

xkcd is a webcomic created by Randall Munroe. It is a comic of Language, Math, Romance and Sarcasm and a couple of other categories.

If kitty, iterm or any terminal that has support for the sixel file format is used as the terminal, the xkcd comic will be rendered directly in the terminal, otherwise the default viewer for PNG images is used. This tool requires fzf to be installed on the machine to filter available comics by their title.

Install this package directly from the Python Package Index (PyPI). The CLI tool requires Python >= 3.8 to be installed.

$ pip install dcs-xkcd-cli

This will install a CLI tool named xkcd which can be used as described below.

Installation with pipx is similar to the pip variant above, but uses pipx instead of pip.

$ pipx install dcs-xkcd-cli

Note that with pipx, this package can be tried out without the need to install it permanently.

$ pipx run dcs-xkcd-cli <args>

$ xkcd show

This functionality requires fzf to be installed.

$ xkcd show --latest

$ xkcd show --random

$ xkcd show --comic-id 207

By default images are upscaled to match the terminal dimensions. This behavior can be controlled with the --terminal-scale-up / --no-terminal-scale-up options. Images can be also rendered with an explicit width by using the --width CLI option.

$ xkcd show --comic-id 207 --no-terminal-scale-up    # disable scaling
$ xkcd show --comic-id 207 --width 1200              # set explicit width

$ xkcd show --no-terminal-graphics

This command will disable the automatic image protocol detection and directly open the image with the help of xdg-open in the default image viewer.

Under the hood this tool uses a cache which is updated once per day transparently. The cache is used to remember the list of xkcd comics from the archive.

To disable the cache, use the following command

$ xkcd show --no-cache

To update the cache manually, use the following command

$ xkcd update-cache

This repository manages Python dependencies with poetry. To install the package and its dependencies run:

$ poetry install

The code is formatted with black and type checked with pyright.

Then run the the following commands to lint and test the code:

$ poetry run python -m black --check --diff .   # tests for any lint issues
$ poetry run python -m black .                  # auto-formats the code

$ poetry run python -m pyright                  # runs static code analysis

$ poetry run python -m pytest --cov="xkcd_cli/" --cov-report term --cov-report html   # run tests with code coverage report