Working with the screen and history buffer contents - kitty
Description: You can pipe the contents of the current screen and history buffer as STDIN to an arbitrary program using the pipe function. The program can be displayed in a kitty window or overlay. For example, ...

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# Working with the screen and history buffer contents

Warning

The pipe action has been deprecated in favor of the launch action which is more powerful.

You can pipe the contents of the current screen and history buffer as `STDIN` to an arbitrary program using the `pipe` function. The program can be displayed in a kitty window or overlay.

For example, the following in `kitty.conf` will open the scrollback buffer in less in an overlay window, when you press `F1`:

    map f1 pipe @ansi overlay less +G -R

The syntax of the `pipe` function is:

    pipe <input placeholder> <destination window type> <command line to run>

## The piping environment

The program to which the data is piped has a special environment variable declared, `KITTY_PIPE_DATA` whose contents are:

    KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}

where `scrolled_by` is the number of lines kitty is currently scrolled by, `cursor_(x|y)` is the position of the cursor on the screen with `(1,1)` being the top left corner and `{lines},{columns}` being the number of rows and columns of the screen.

You can choose where to run the pipe program:

`overlay`

  An overlay window over the current kitty window

`window`

  A new kitty window

`os_window`

  A new top-level window

`tab`

  A new window in a new tab

`clipboard, primary`

  Copy the text directly to the clipboard. In this case the specified program is not run, so use some dummy program name for it.

`none`

  Run it in the background

## Input placeholders

There are various different kinds of placeholders

`@selection`

  Plain text, currently selected text

`@text`

  Plain text, current screen + scrollback buffer

`@ansi`

  Text with formatting, current screen + scrollback buffer

`@screen`

  Plain text, only current screen

`@ansi_screen`

  Text with formatting, only current screen

`@alternate`

  Plain text, secondary screen. The secondary screen is the screen not currently displayed. For example if you run a fullscreen terminal application, the secondary screen will be the screen you return to when quitting the application.

`@ansi_alternate`

  Text with formatting, secondary screen.

`@alternate_scrollback`

  Plain text, secondary screen + scrollback, if any.

`@ansi_alternate_scrollback`

  Text with formatting, secondary screen + scrollback, if any.

`none`

  No input

You can also add the suffix `_wrap` to the placeholder, in which case kitty will insert the carriage return at every line wrap location (where long lines are wrapped at screen edges). This is useful if you want to pipe to program that wants to duplicate the screen layout of the screen.