Table of Contents

Inline Images Protocol

iTerm2 is able to display images within the terminal. Using a similar mechanism, it can also facilitate file transfers over any transport (such as ssh or telnet), even in a non-8-bit-clean environment.

Just want to try it out and don't care about the protocol? Use the imgcat tool. Download imgcat here

Example: imgcat

Using the imgcat script, one or more images may be displayed in a terminal session. For example:

Critically, animated GIFs are supported as of version 2.9.20150512.

Protocol

iTerm2 extends the xterm protocol with a set of proprietary escape sequences. In general, the pattern is:

ESC ] 1337 ; key = value ^G

Whitespace is shown here for ease of reading: in practice, no spaces should be used.

For file transfer and inline images, the code is:

ESC ] 1337 ; File = [arguments] : base-64 encoded file contents ^G

The arguments are formatted as key=value with a semicolon between each key-value pair. They are described below:

KeyDescription of value
name  base-64 encoded filename. Defaults to "Unnamed file".
size  File size in bytes. The file transfer will be canceled if this size is exceeded.
width  Optional. Width to render. See notes below.
height  Optional. Height to render. See notes below.
preserveAspectRatio  Optional. If set to 0, then the image's inherent aspect ratio will not be respected; otherwise, it will fill the specified width and height as much as possible without stretching. Defaults to 1.
inline  Optional. If set to 1, the file will be displayed inline. Otherwise, it will be downloaded with no visual representation in the terminal session. Defaults to 0.

The width and height are given as a number followed by a unit, or the word "auto".

  • N: N character cells.
  • Npx: N pixels.
  • N%: N percent of the session's width or height.
  • auto: The image's inherent size will be used to determine an appropriate dimension.

More on File Transfers

By omitting the inline argument (or setting its value to 0), files will be downloaded and saved in the Downloads folder instead of being displayed inline. Any kind of file may be downloaded, but only images will display inline. Any image format that macOS supports will display inline, including PDF, PICT, or any number of bitmap data formats (PNG, GIF, etc.). A new menu item titled Downloads will be added to the menu bar after a download begins, where progress can be monitored and the file can be located, opened, or removed.

If the file's size exceeds the declared size, the transfer may be canceled. This is a security measure to prevent a download gone wrong from using unbounded memory.

Sample Code

Sample code for displaying images may be found here.

imgls

Provides an augmented directory listing that includes a thumbnail of each image in a directory.

imgcat

Displays one or more images inline at their full size.

it2dl

Downloads a file, but does not display it inline.

divider

Draws a full-width, one line-tall graphical divider.