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 a string 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

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

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 varibles 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: last): 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

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

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:

text (required): The text being sent
is_binary (required): If False text is interpreted as a python string literal instead of plain text
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-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
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-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 (required): 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