Images on the Command Line

My current favorite feature in La Terminal is inline image support.

When Miguel first showed me La Terminal’s support for displaying images on the command line, my first thought was “That’s cute, but would anyone really ever use it?”. In the time since, though, I’ve found several ways to integrate images into my daily command line workflow. Some of this is perhaps just a reflection of how much more work I’m doing with images in general these days.

Regardless, if you work with images at all this post will provide a few practical uses for taking advantage of image support in La Terminal and other modern terminal emulators that support sixel encoding or Inline Images Protocol.

Sixel Images

The sixel image format was developed specifically for terminals and printers, and has been around for a while. It gets its name from the fact that sixel images are rendered from an ASCII encoding where each character is rendered as a pattern one-pixel wide and six-pixels high. Sixel is well supported in several popular command line tools.

ImageMagick

Because I spend a lot of time using ImageMagick to modify screenshots through command line scripts using convert, I find that my most common use of inline images is previewing intermediate image processing steps while I’m hacking image manipulation scripts. ImageMagick has native support for sixel, enabling it to save output to sixel format by specifying a *.six or *.sixel file extension. Images saved as sixel can be rendered in the terminal with a simple cat command. E.g.,

convert logo.png logo.six
cat logo.six

Alternatively, convert can send sixel content directly to the terminal using the sixel:- argument.

As an example, if I’ve taken a screenshot of the iPhone simulator app and I want to crop the application titlebar, I might run the following command:

convert Screenshot.png -crop +0+120 device.png

This takes Screenshot.png, crops the top 120 pixels off, and saves the new image as device.png. Now I’m curious, though. Did I actually remove the titlebar? In the old days, I would have to open this file with an external viewer to set my mind at ease, which is very damaging to my flow. With inline image support, though, I can now quickly inspect the output without leaving the command line by converting device.png to sixel, and dumping that out to the terminal:

convert device.png -resize 1000 sixel:-

Here, I added -resize 1000 to proportionally scale the image down to a comfortable viewing width of 1000px. Depending on what I’m working with, I might leave that part out, choose a more appropriate width for the display, or use crop to focus on the portion of the image I want to inspect.

lsix

The other way I end up using sixel when I’m working with images is via this wonderful lsix script. lsix is an ls command for images, and does pretty much what it advertises. If I’m in a directory with a bunch of images, lsix helps me get my bearings by generating previews for all of the images in the directory, respecting the terminal’s theme, and captioning each with their filename.

GnuPlot

GnuPlot generates charts and graphs from the command line. Like ImageMagick, GnuPlot also has native support for sixel format. This means that if I have, for instance, a server log that I would like to view as a graph, I can feed the data to GnuPlot and view the chart in place.

For a simple example of this, let’s create some data from listing the files in my images images directory:

ls -l > data.txt

By executing the following gnuplot command, I can generate a histogram of file sizes from that data:

gnuplot -e "set terminal six; set key autotitle columnhead; set xtics border in scale 1,0.5 nomirror rotate by -90 offset character 0, 0, 0;plot 'data.txt' using 5:xticlabels(9) with histogram"

This command first puts gnuplot into sixel mode, and then generates a histogram using values from the 5th column (file size in bytes) and labels from the 9th column (filenames).

I can now visually observe relative file sizes of the files in my images folder.

In addition to these use cases, the sixel format is being abused to perform a lot of really amazing tricks, including supporting video playback on the command line, and for rendering graphics for command line games. Check out the libsixel project for a showcase of many amazing sixel hacks.

Inline Image Protocol

There are few shortcomings of sixel. First, the image format is lossy, meaning that the quality of the file you see in the terminal might be degraded from the non-sixel image. Additionally, almost anything one might do with sixel is going to require installation of something that supports sixel encoding (i.e., ImageMagick).

For systems and occasions where I want to avoid those dependencies, or where I need to view the original file without any image quality loss that might occur during the conversion to sixel, I take advantage of La Terminal’s support of iTerm2’s inline image protocol. Images output using the inline image protocol escape sequence render natively in the terminal in their original format.

iTerm2 hosts several scripts that cover most of my use cases:

imgcat

The imgcat script just outputs an image on the command line, as-is.

imgls

imgls outputs thumbnails of every image in a directory as a list, similar to lsix, but with smaller thumbnails and a different layout.

divider

The divider script is a good example of how to integrate images into scripts. divider renders an image at 100% width, but only one line high, creating a nice visual break in output.

it2dl

Of inline image protocol use cases, the script I get the most use out of is probably it2dl. Rather than displaying an image inline, it2dl just downloads the specified file. This works for any file, not just images. When it2dl is run in La Terminal, the app will pop up a share sheet prompt to open a file, save it, or send it somewhere else.

Enrich your command line with images

La Terminal users can take advantage of inline images on the command line today. For a list of terminal applications that support sixel rendering, check Are we sixel yet? And, of course, if you’re not already using La Terminal, you can download La Terminal for iPad and iPhone from the App Store today.