Documentation for the kitty remote control protocol — kitty 0.19.1 documentation

# Documentation for the kitty remote control protocol

The kitty remote control protocol is a simple protocol that involves sending data to kitty in the form of JSON. Any individual command of kitty has the form:

    <ESC>P@kitty-cmd<JSON object><ESC>\

Where `<ESC>` is the byte `0x1b`. The JSON object has the form:

    {
        "cmd": "command name",
        "version": <kitty version>,
        "no_response": Optional Boolean,
        "payload": <Optional JSON object>,
    }

The `version` above is an array of the form `[0, 14, 2]`. If you are developing a standalone client, use the kitty version that you are developing against. Using a version greater than the version of the kitty instance you are talking to, will cause a failure.

Set `no_response` to `true` if you don’t want a response from kitty.

The optional payload is a JSON object that is specific to the actual command being sent. The fields in the object for every command are documented below.

## close-tab

Fields are:

`match (default: None)`

  Which tab to close

`self (default: False)`

  Boolean indicating whether to close the window the command is run in

## close-window

Fields are:

`match (default: None)`

  Which window to close

`self (default: False)`

  Boolean indicating whether to close the window the command is run in

## create-marker

Fields are:

`match (default: None)`

  Which window to detach

`self (default: False)`

  Boolean indicating whether to detach the window the command is run in

`marker_spec (optional)`

  A list or arguments that define the marker specification, for example: [‘text’, ‘1’, ‘ERROR’]

## detach-tab

Fields are:

`match (default: None)`

  Which tab to detach

`target (optional)`

  Which OS Window to move the detached tab to

`self (default: False)`

  Boolean indicating whether to detach the tab the command is run in

## detach-window

Fields are:

`match (default: None)`

  Which window to detach

`target (optional)`

  Which tab to move the detached window to

`self (default: False)`

  Boolean indicating whether to detach the window the command is run in

## disable-ligatures

Fields are:

`strategy (required)`

  One of `never`, `always` or `cursor`

`match_window (optional)`

  Window to change opacity in

`match_tab (default: None)`

  Tab to change opacity in

`all (default: False)`

  Boolean indicating operate on all windows

## focus-tab

Fields are:

`match (default: None)`

  The tab to focus

## focus-window

Fields are:

`match (default: None)`

  The window to focus

## get-colors

Fields are:

`match (default: None)`

  The window to get the colors for

`configured (default: False)`

  Boolean indicating whether to get configured or current colors

## get-text

Fields are:

`match (default: None)`

  The tab to focus

`extent (default: screen)`

  One of `screen`, `all`, or `selection`

`ansi (default: False)`

  Boolean, if True send ANSI formatting codes

`self (default: False)`

  Boolean, if True use window command was run in

## goto-layout

Fields are:

`layout (required)`

  The new layout name

`match (default: None)`

  Which tab to change the layout of

## kitten

Fields are:

`kitten (required)`

  The name of the kitten to run

`args (optional)`

  Arguments to pass to the kitten as a list

`match (default: None)`

  The window to run the kitten over

## last-used-layout

Fields are:

`match (default: None)`

  Which tab to change the layout of

`all (default: False)`

  Boolean to match all tabs

## launch

Fields are:

`args (required)`

  The command line to run in the new window, as a list, use an empty list to run the default shell

`match (default: None)`

  The tab to open the new window in

`window_title (default: None)`

  Title for the new window

`cwd (default: None)`

  Working directory for the new window

`env (default: [])`

  List of environment variables of the form NAME=VALUE

`tab_title (default: None)`

  Title for the new tab

`type (default: window)`

  The type of window to open

`keep_focus (default: False)`

  Boolean indicating whether the current window should retain focus or not

`copy_colors (default: False)`

  Boolean indicating whether to copy the colors from the current window

`copy_cmdline (default: False)`

  Boolean indicating whether to copy the cmdline from the current window

`copy_env (default: False)`

  Boolean indicating whether to copy the environ from the current window

`location (default: default)`

  Where in the tab to open the new window

`allow_remote_control (default: False)`

  Boolean indicating whether to allow remote control from the new window

`stdin_source (default: none)`

  Where to get stdin for thew process from

`stdin_add_formatting (default: False)`

  Boolean indicating whether to add formatting codes to stdin

`stdin_add_line_wrap_markers (default: False)`

  Boolean indicating whether to add line wrap markers to stdin

`no_response (default: False)`

  Boolean indicating whether to send back the window id

`marker (default: None)`

  Specification for marker for new window, for example: “text 1 ERROR”

## ls

No payload

## new-window

Fields are:

`args (required)`

  The command line to run in the new window, as a list, use an empty list to run the default shell

`match (default: None)`

  The tab to open the new window in

`title (default: None)`

  Title for the new window

`cwd (default: None)`

  Working directory for the new window

`tab_title (default: None)`

  Title for the new tab

`window_type (default: kitty)`

  One of `kitty` or `os`

`keep_focus (default: False)`

  Boolean indicating whether the current window should retain focus or not

## remove-marker

Fields are:

`match (default: None)`

  Which window to remove the marker from

`self (default: False)`

  Boolean indicating whether to detach the window the command is run in

## resize-window

Fields are:

`match (default: None)`

  Which window to resize

`self (default: False)`

  Boolean indicating whether to close the window the command is run in

`increment (default: 2)`

  Integer specifying the resize increment

`axis (default: horizontal)`

  One of `horizontal, vertical` or `reset`

## scroll-window

Fields are:

`amount (required)`

  The amount to scroll, a two item list with the first item being either a number or the keywords, start and end. And the second item being either ‘p’ for pages or ‘l’ for lines.

`match (default: None)`

  The window to scroll

## send-text

Fields are:

`data (required)`

  The data being sent. Can be either: text: followed by text or base64: followed by standard base64 encoded bytes

`match (default: None)`

  A string indicating the window to send text to

`match_tab (default: None)`

  A string indicating the tab to send text to

## set-background-image

Fields are:

`data (required)`

  Chunk of at most 512 bytes of PNG data, base64 encoded. Must send an empty chunk to indicate end of image. Or the special value - to indicate image must be removed.

`img_id (required)`

  Unique uuid (as string) used for chunking

`match (default: None)`

  Window to change opacity in

`layout (default: None)`

  The image layout

`all (default: False)`

  Boolean indicating operate on all windows

`configured (default: False)`

  Boolean indicating if the configured value should be changed

## set-background-opacity

Fields are:

`opacity (required)`

  A number between 0.1 and 1

`match_window (optional)`

  Window to change opacity in

`match_tab (default: None)`

  Tab to change opacity in

`all (default: False)`

  Boolean indicating operate on all windows

## set-colors

Fields are:

`colors (required)`

  An object mapping names to colors as 24-bit RGB integers

`cursor_text_color (optional)`

  A 24-bit color for text under the cursor, or null to use background.

`match_window (optional)`

  Window to change colors in

`match_tab (default: None)`

  Tab to change colors in

`all (default: False)`

  Boolean indicating change colors everywhere or not

`configured (default: False)`

  Boolean indicating whether to change the configured colors. Must be True if reset is True

`reset (default: False)`

  Boolean indicating colors should be reset to startup values

## set-font-size

Fields are:

`size (required)`

  The new font size in pts (a positive number)

`all (default: False)`

  Boolean whether to change font size in the current window or all windows

`increment_op (optional)`

  The string `+` or `-` to interpret size as an increment

## set-spacing

Fields are:

`settings (required)`

  An object mapping margins/paddings using canonical form {‘margin-top’: 50, ‘padding-left’: null} etc

`match_window (optional)`

  Window to change colors in

`match_tab (default: None)`

  Tab to change colors in

`all (default: False)`

  Boolean indicating change colors everywhere or not

`configured (default: False)`

  Boolean indicating whether to change the configured colors. Must be True if reset is True

## set-tab-title

Fields are:

`title (required)`

  The new title

`match (default: None)`

  Which tab to change the title of

## set-window-title

Fields are:

`title (optional)`

  The new title

`match (default: None)`

  Which windows to change the title in

`temporary (default: False)`

  Boolean indicating if the change is temporary or permanent

## signal-child

Fields are:

`signals (optional)`

  The signals, a list of names, such as SIGTERM, SIGKILL, SIGUSR1, etc.

`match (default: None)`

  Which windows to change the title in