Gleeter

Stop interrupting your workflow for comic relief! Gleeter delivers the exact XKCD strip you need, right in your terminal. Need to gently nudge a colleague about off-by-one errors? Or perhaps illustrate the superpowers of regular expressions? Maybe teach a colleague why it is important to sanitize your database inputs? Gleeter's got you covered. Install now, and weaponize your command line with the power of XKCD.

This is a very simple and straightforward software to fetch and display comics from xkcd right in the terminal.

Supported commands are:

• latest: to show the latest comic
• random: to show a random comic
• id <number>: to show the comic with id <number>. Replace <number> with the desired comic ID.
• serve <port> <path> to create a web server which you can query with curl!
• You can also define aliases for the above commands (e.g. bobbytables) and fetch very specific comics using the configuration file. See the How to use section for more information and details about the commands.

For this to work, you need a terminal which understands the Terminal Graphics Protocol.

Gleeter is known to work well with the following terminals:

• Ghostty
• Kitty
• Wezterm
• ... and probably more

Test it out now

You can start using it without installing anything: simply curl -H "X-TERMINAL-ROWS: $(tput lines)" -H "X-TERMINAL-COLUMNS: $(tput cols)" https://xkcd.massi.rocks/comics/latest

Replace latest with random or id/<comic_id> to change the behavior, you can also check this file for a list of available aliases!

Screenshots

Latest comic

<div align="center"> <img src="./assets/latest.png" width="400px" /> </div>

Random Comic

<div align="center"> <img src="./assets/random.png" width="400px" /> </div>

Fetch a comic by ID

<div align="center"> <img src="./assets/id.png" width="400px" /> </div>

Running on Ghostty via Docker

<div align="center"> <img src="./assets/ghostty.png" width="400px" /> </div>

Serve mode using Docker and Ghostty

<div align="center"> <img src="./assets/docker.png" width="400px" /> </div>

How to use

Gleeter understands the following commands:

• help: Prints help information, this is also the default behavior if no arguments are provided.

• version: Prints the application version.

• latest: Fetches the latest comic from XKCD and displays it in the terminal. Use the --no-cache or -n flag to bypass the cache and fetch the comic directly from XKCD.

• random: Fetches a random comic from XKCD and displays it in the terminal. Gleeter will automatically skip the comics using an unsupported format (very old comics were using the JPG extension), so you should always get a valid comic. This is a technical limitation of the Terminal Graphics Protocol. Use the --no-cache or -n flag to bypass the cache and fetch the comic directly from XKCD. Warning: the -n (or --no-cache flag) must come before the command for it to work (e.g.: -n random will work, while random -n will not work); this behavior will be fixed in a future version.

• id <number>: Fetches the comic with the specified ID and displays it in the terminal. Replace <number> with the desired comic ID. Use the --no-cache or -n flag to bypass the cache and fetch the comic directly from XKCD. Warning: the -n (or --no-cache flag) must come before the command for it to work (e.g.: -n id 998 will work, while id 998 -n will not work); this behavior will be fixed in a future version.

• serve <port> <base_path>: Starts a web server to serve the comics. <port> is optional and defaults to 8080. <base_path> is also optional and defaults to "". For example, gleeter serve 3000 /comics will start the server on port 3000 and serve the comics under the /comics path.

• clearcache: Clears the local cache of comics.

Configuration File

Gleeter uses a TOML configuration file to customize its behavior. The configuration file allows you to configure the starting comic for random mode, set screen dimensions, and define aliases for comic IDs.

Syntax

Here's an example configuration file (based on test_data/config.toml):

random_start = 38

[screen]
max_cols = 80
max_lines = 23

[[alias]]
name = "bobbytables"
type = "id"
id = 987

[[alias]]
name = "rnd"
type = "random"

[[alias]]
name = "l"
type = "latest"

[metrics]
ignore_base_path = true
username = "your_username"
password = "your_password"

Structure and Usage

The configuration file is loaded when Gleeter starts. Gleeter checks for the configuration file in the following order:

1. $GLEETER_CONFIG_FILE: If this environment variable is set, Gleeter will attempt to load the configuration file from the path specified. This variable must point to a valid TOML file.
2. $XDG_CONFIG_HOME/gleeter/config.toml: If $GLEETER_CONFIG_FILE is not set, Gleeter will check for a configuration file in the $XDG_CONFIG_HOME directory, appending /gleeter/config.toml to the value of the variable.
3. $HOME/.config/gleeter/config.toml: If $XDG_CONFIG_HOME is not set, Gleeter will check for a configuration file in the $HOME directory, appending /.config/gleeter/config.toml to the value of the variable.
4. ./gleeter/config.toml: If none of the above environment variables are set, Gleeter will attempt to load the configuration file from the ./gleeter/config.toml path.

The settings defined in the file are used to initialize the application and control its behavior.

• random_start: Specifies the starting comic number for the random comic selection. If not specified, a default value is used.

• [screen]: This section configures the screen dimensions for displaying comics.

  • max_cols: Specifies the maximum number of columns to use for displaying the comic.
  • max_lines: Specifies the maximum number of lines to use for displaying the comic.

• [metrics]: This section configures the metrics endpoint and it is meaningful only for the serve mode.

  • ignore_base_path: If set to true, the /metrics endpoint will be accessible even when a base path is used. This allows accessing metrics at /metrics regardless of the configured base path.
  • username: An optional username for basic authentication on the /metrics endpoint. If provided, a password must also be specified.
  • password: An optional password for basic authentication on the /metrics endpoint. If provided, a username must also be specified.

• [[alias]]: This section defines aliases for accessing comics. You can define multiple aliases.

  • name: The name of the alias. Alias names must not be empty and must not contain any of the following characters: !, ;, $, :, \, ", ', (, ), space, tab, newline, or carriage return. Leading and trailing whitespaces will be automatically removed.
  • type: The type of alias. Valid values are "id", "random", and "latest".
  • id: (Only required for "id" aliases) The comic ID to associate with the alias.

The config.gleam file defines the structure of the configuration data and how it is parsed from the TOML file.

To modify Gleeter's behavior, simply edit the configuration file and restart the application.

Serve mode details

When Gleeter is run in serve mode, it starts an HTTP server that exposes the following endpoints:

• /: Serves the latest comic.
• /metrics/: Serves the Prometheus metrics endpoint.
• /latest: Serves the latest comic (same as /).
• /random: Serves a random comic.
• /id/<number>: Serves the comic with the specified ID. Replace <number> with the desired comic ID.

You can customize the base path for these endpoints by using the <base_path> argument. For example, if you start the server with gleeter serve 8080 /comics, the endpoints will be:

• /comics/
• /comics/metrics
• /comics/latest
• /comics/random
• /comics/id/<number>

Gleeter also supports receiving the terminal size via HTTP headers. You can send the X-TERMINAL-COLUMNS and X-TERMINAL-ROWS headers with your request to specify the terminal size. This allows Gleeter to properly format the comic for your terminal. If these headers are not provided, Gleeter will use a default terminal size. Please be aware that for the resizing to work, you need to send both headers.

Serve and Configuration file

Serve mode will also honour all the aliases defined in the configuration file, and expose them all at the root of the base_path. As a quick example, imagine you have the following defined in the config.toml file:

[[alias]]
name = "bobbytables"
type = "id"
id = 987

[[alias]]
name = "rnd"
type = "random"

[[alias]]
name = "l"
type = "latest"

And you start the server with gleeter serve 8080 /comics, on top of the URLs mentioned above, you will also get the following:

• /comics/bobbytables, which will be an alias for /comics/id/987
• /comics/rnd, which will be an alias for /comics/random
• /comics/l, which will be an alias for /comics/latest

Health Check

In addition to serving comics, Gleeter provides a /health endpoint. This endpoint returns a JSON structure with information about the server's status and performance. The structure includes the following fields:

• cache_status: A boolean indicating whether the cache is enabled.
• cache_elements: The number of elements currently stored in the cache.
• `processed_q