# icat

Display images in the terminal

The `icat` kitten can be used to display arbitrary images in the kitty terminal. Using it is as simple as:

    kitty +kitten icat image.jpeg

It supports all image types supported by ImageMagick. It even works over SSH. For details, see the kitty graphics protocol.

You might want to create an alias in your shell’s configuration files:

    alias icat="kitty +kitten icat"

Then you can simply use `icat image.png` to view images.

Note

ImageMagick must be installed for `icat` to work.

Note

kitty’s image display protocol may not work when used within a terminal multiplexer such as `screen` or `tmux`, depending on whether the multiplexer has added support for it or not.

The `icat` kitten has various command line arguments to allow it to be used from inside other programs to display images. In particular, `--place`, `--detect-support` and `--print-window-size`.

## Source code for icat

The source code for this kitten is available on GitHub.

## Command Line Interface

    kitty +kitten icat [options] image-file-or-url-or-directory ...

A cat like utility to display images in the terminal. You can specify multiple image files and/or directories. Directories are scanned recursively for image files. If STDIN is not a terminal, image data will be read from it as well. You can also specify HTTP(S) or FTP URLs which will be automatically downloaded and displayed.

### Options

--align <ALIGN>

  Horizontal alignment for the displayed image. Default: `center` Choices: `center, left, right`

--place <PLACE>

  Choose where on the screen to display the image. The image will be scaled to fit into the specified rectangle. The syntax for specifying rectangles is <width>x<height>@<left>x<top>. All measurements are in cells (i.e. cursor positions) with the origin (0, 0) at the top-left corner of the screen.

--scale-up

  When used in combination with `--place` it will cause images that are smaller than the specified area to be scaled up to use as much of the specified area as possible.

--clear

  Remove all images currently displayed on the screen.

--transfer-mode <TRANSFER_MODE>

  Which mechanism to use to transfer images to the terminal. The default is to auto-detect. file means to use a temporary file and stream means to send the data via terminal escape codes. Note that if you use the file transfer mode and you are connecting over a remote session then image display will not work. Default: `detect` Choices: `detect, file, stream`

--detect-support

  Detect support for image display in the terminal. If not supported, will exit with exit code 1, otherwise will exit with code 0 and print the supported transfer mode to stderr, which can be used with the `--transfer-mode` option.

--detection-timeout <DETECTION_TIMEOUT>

  The amount of time (in seconds) to wait for a response form the terminal, when detecting image display support. Default: `10`

--print-window-size

  Print out the window size as widthxheight (in pixels) and quit. This is a convenience method to query the window size if using kitty icat from a scripting language that cannot make termios calls.

--stdin <STDIN>

  Read image data from stdin. The default is to do it automatically, when STDIN is not a terminal, but you can turn it off or on explicitly, if needed. Default: `detect` Choices: `detect, no, yes`

--silent

  Do not print out anything to STDOUT during operation.

--z-index <Z_INDEX>, -z <Z_INDEX>

  Z-index of the image. When negative, text will be displayed on top of the image. Use a double minus for values under the threshold for drawing images under cell background colors. For example, –1 evaluates as -1,073,741,825. Default: `0`

--loop <LOOP>, -l <LOOP>

  Number of times to loop animations. Negative values loop forever. Zero means only the first frame of the animation is displayed. Otherwise, the animation is looped the specified number of times. Default: `-1`

--hold

  Wait for a key press before exiting after displaying the images.