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.
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:
| Key | Description 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.
