# 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.

Note

ImageMagick must be installed for `icat` to work.

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`.

## Command Line Interface

    kitty +kitten icat [options] image-file ...

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.

### Options

`--align``<ALIGN>`

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

`--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 rectanges 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: `stream, detect, file`

`--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.