xkcd cli tool

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

recording.mp4

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.

Installation

With pip

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.

With pipx

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>

Usage

Search by title

$ xkcd show

This functionality requires fzf to be installed.

Show latest xkcd comic

$ xkcd show --latest

Show random xkcd comic

$ xkcd show --random

Show xkcd comic by its ID

$ xkcd show --comic-id 207

Upscaling / width of comics

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

Disable rendering in terminals

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

Disable or update cache

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

Development

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