Mappable actions#

The actions described below can be mapped to any key press or mouse action using the map and mouse_map directives in kitty.conf. For configuration examples, see the default shortcut links for each action.

Copy/paste#

clear_selection#

Clear the current selection

copy_and_clear_or_interrupt#

Copy the selected text from the active window to the clipboard and clear selection, if no selection, send SIGINT (aka ctrl+c)

copy_ansi_to_clipboard#

Copy the selected text from the active window to the clipboard with ANSI formatting codes

copy_or_interrupt#

Copy the selected text from the active window to the clipboard, if no selection, send SIGINT (aka ctrl+c)

copy_to_clipboard#

Copy the selected text from the active window to the clipboard

Default shortcuts using this action: ctrl+shift+c

pass_selection_to_program#

Pass the selected text from the active window to the specified program

Default shortcuts using this action: ctrl+shift+o

paste#

Paste the specified text into the current window

show_first_command_output_on_screen#

Show output from the first shell command on screen in a pager like less

Requires Shell integration to work

show_last_command_output#

Show output from the last shell command in a pager like less

Requires Shell integration to work

Default shortcuts using this action: ctrl+shift+g

show_last_non_empty_command_output#

Show the last non-empty output from a shell command in a pager like less

Requires Shell integration to work

show_last_visited_command_output#

Show the first command output below the last scrolled position via scroll_to_prompt

or the last mouse clicked command output in a pager like less

Requires Shell integration to work

show_scrollback#

Show scrollback in a pager like less

Default shortcuts using this action: ctrl+shift+h

copy_to_buffer#

Copy the selection from the active window to the specified buffer

See Multiple copy/paste buffers for details.

paste_from_buffer#

Paste from the specified buffer to the active window

See Multiple copy/paste buffers for details.

paste_from_clipboard#

Paste from the clipboard to the active window

Default shortcuts using this action: ctrl+shift+v

paste_from_selection#

Paste from the primary selection, if present, otherwise the clipboard to the active window

Default shortcuts using this action: ctrl+shift+s

Debugging#

dump_lines_with_attrs#

Show a dump of the current lines in the scrollback + screen with their line attributes

close_shared_ssh_connections#

Close all shared SSH connections

See share_connections for details.

debug_config#

Show the effective configuration kitty is running with

Default shortcuts using this action: ctrl+shift+f6

show_kitty_env_vars#

Show the environment variables that the kitty process sees

Layouts#

goto_layout#

Switch to the named layout

For example:

map f1 goto_layout tall
last_used_layout#

Go to the previously used layout

layout_action#

Perform a layout specific action. See Arrange windows for details

next_layout#

Go to the next enabled layout

Default shortcuts using this action: ctrl+shift+l

toggle_layout#

Toggle the named layout

Switches to the named layout if another layout is current, otherwise switches to the last used layout. Useful to “zoom” a window temporarily by switching to the stack layout. For example:

map f1 toggle_layout stack

Marks#

remove_marker#

Remove a previously created marker

scroll_to_mark#

Scroll to the next or previous mark of the specified type

toggle_marker#

Toggle the current marker on/off

create_marker#

Create a new marker

Miscellaneous#

send_text#

Send the specified text to the active window

See send_text for details.

Default shortcuts using this action: ctrl+shift+alt+h

show_kitty_doc#

Display the specified kitty documentation, preferring a local copy, if found.

For example:

# show the config docs
map f1 show_kitty_doc conf
# show the ssh kitten docs
map f1 show_kitty_doc kittens/ssh

Default shortcuts using this action: ctrl+shift+f1

signal_child#

Send the specified SIGNAL to the foreground process in the active window

For example:

map f1 signal_child SIGTERM
clear_terminal#

Clear the terminal

See reset_terminal for details. For example:

# Reset the terminal
map f1 clear_terminal reset active
# Clear the terminal screen by erasing all contents
map f1 clear_terminal clear active
# Clear the terminal scrollback by erasing it
map f1 clear_terminal scrollback active
# Scroll the contents of the screen into the scrollback
map f1 clear_terminal scroll active
# Clear everything up to the line with the cursor
map f1 clear_terminal to_cursor active

Default shortcuts using this action: cmd+k, ctrl+shift+delete

combine#

Combine multiple actions and map to a single keypress

The syntax is:

map key combine <separator> action1 <separator> action2 <separator> action3 ...

For example:

map kitty_mod+e combine : new_window : next_layout
disable_ligatures_in#

Turn on/off ligatures in the specified window

See disable_ligatures for details

discard_event#

Discard this event completely ignoring it

edit_config_file#

Edit the kitty.conf config file in your favorite text editor

Default shortcuts using this action: ctrl+shift+f2

input_unicode_character#

Input an arbitrary unicode character. See Unicode input for details.

kitten#

Run the specified kitten. See Custom kittens for details

Default shortcuts using this action:

kitty_shell#

Run the kitty shell to control kitty with commands

Default shortcuts using this action: ctrl+shift+escape

launch#

Launch the specified program in a new window/tab/etc.

See The launch command for details

load_config_file#

Reload the config file

If mapped without arguments reloads the default config file, otherwise loads the specified config files, in order. Loading a config file replaces all config options. For example:

map f5 load_config_file /path/to/some/kitty.conf

Default shortcuts using this action: ctrl+shift+f5

open_url#

Open the specified URL

Default shortcuts using this action: shift+cmd+/

open_url_with_hints#

Click a URL using the keyboard

Default shortcuts using this action: ctrl+shift+e

remote_control#

Run a remote control command

For example:

map f1 remote_control set-spacing margin=30

See Mapping key presses to remote control commands for details.

set_colors#

Change colors in the specified windows

For details, see kitty @ set-colors. For example:

map f5 set_colors --configured /path/to/some/config/file/colors.conf
toggle_macos_secure_keyboard_entry#

Toggle macOS secure keyboard entry

Default shortcuts using this action: opt+cmd+s

no_op#

Unbind a shortcut

Mapping a shortcut to no_op causes kitty to not intercept the key stroke anymore, instead passing it to the program running inside it.

Mouse actions#

mouse_click_url#

Click the URL under the mouse

mouse_click_url_or_select#

Click the URL under the mouse only if the screen has no selection

mouse_handle_click#

Handle a mouse click

Try to perform the specified actions one after the other till one of them is successful. Supported actions are:

selection - check for a selection and if one exists abort processing
link - if a link exists under the mouse, click it
prompt - if the mouse click happens at a shell prompt move the cursor to the mouse location

For examples, see Mouse actions

mouse_select_command_output#

Select clicked command output

Requires Shell integration to work

mouse_selection#

Manipulate the selection based on the current mouse position

For examples, see Mouse actions

mouse_show_command_output#

Show clicked command output in a pager like less

Requires Shell integration to work

paste_selection#

Paste the current primary selection

paste_selection_or_clipboard#

Paste the current primary selection or the clipboard if no selection is present

Scrolling#

scroll_end#

Scroll to the bottom of the scrollback buffer

Default shortcuts using this action: ctrl+shift+end

scroll_home#

Scroll to the top of the scrollback buffer

Default shortcuts using this action: ctrl+shift+home

scroll_line_down#

Scroll down by one line

Default shortcuts using this action: ctrl+shift+down

scroll_line_up#

Scroll up by one line

Default shortcuts using this action: ctrl+shift+up

scroll_page_down#

Scroll down by one page

Default shortcuts using this action: ctrl+shift+page_down

scroll_page_up#

Scroll up by one page

Default shortcuts using this action: ctrl+shift+page_up

scroll_prompt_to_bottom#

Scroll prompt to the bottom of the screen, filling in extra lines from the scrollback buffer

scroll_prompt_to_top#

Scroll prompt to the top of the screen, filling screen with empty lines

scroll_to_prompt#

Scroll to the previous/next shell command prompt

Allows easy jumping from one command to the next. Requires working Shell integration. Takes a single, optional, number as argument which is the number of prompts to jump, negative values jump up and positive values jump down. A value of zero will jump to the last prompt visited by this action. For example:

map ctrl+p scroll_to_prompt -1  # jump to previous
map ctrl+n scroll_to_prompt 1   # jump to next
map ctrl+o scroll_to_prompt 0   # jump to last visited

Default shortcuts using this action: ctrl+shift+x, ctrl+shift+z

Tab management#

close_other_tabs_in_os_window#

Close all the tabs in the current OS window other than the currently active tab

close_tab#

Close the current tab

Default shortcuts using this action: ctrl+shift+q

detach_tab#

Detach a tab, moving it to another OS Window

See detaching windows for details.

goto_tab#

Go to the specified tab, by number, starting with 1

Zero and negative numbers go to previously active tabs

move_tab_backward#

Move the active tab backward

Default shortcuts using this action: ctrl+shift+,

move_tab_forward#

Move the active tab forward

Default shortcuts using this action: ctrl+shift+.

new_tab#

Create a new tab

Default shortcuts using this action: ctrl+shift+t

new_tab_with_cwd#

Create a new tab with working directory for the window in it set to the same as the active window

next_tab#

Make the next tab active

Default shortcuts using this action: ctrl+shift+right

previous_tab#

Make the previous tab active

Default shortcuts using this action: ctrl+shift+left

select_tab#

Interactively select a tab to switch to

set_tab_title#

Change the title of the active tab interactively, by typing in the new title.

If you specify an argument to this action then that is used as the title instead of asking for it. Use the empty string (“”) to reset the title to default. For example:

# interactive usage
map f1 set_tab_title
# set a specific title
map f2 set_tab_title some title
# reset to default
map f3 set_tab_title ""

Default shortcuts using this action: ctrl+shift+alt+t

Window management#

close_other_windows_in_tab#

Close all windows in the tab other than the currently active window

eighth_window#

Focus the eighth window

Default shortcuts using this action: ctrl+shift+8

fifth_window#

Focus the fifth window

Default shortcuts using this action: ctrl+shift+5

first_window#

Focus the first window

Default shortcuts using this action: ctrl+shift+1

focus_visible_window#

Focus a visible window by pressing the number of the window. Window numbers are displayed

over the windows for easy selection in this mode. See visual_window_select_characters.

Default shortcuts using this action: ctrl+shift+f7

fourth_window#

Focus the fourth window

Default shortcuts using this action: ctrl+shift+4

move_window#

Move the window in the specified direction

For example:

map ctrl+left move_window left
map ctrl+down move_window bottom
move_window_backward#

Move active window backward (swap it with the previous window)

Default shortcuts using this action: ctrl+shift+b

move_window_forward#

Move active window forward (swap it with the next window)

Default shortcuts using this action: ctrl+shift+f

move_window_to_top#

Move active window to the top (make it the first window)

Default shortcuts using this action: ctrl+shift+`

neighboring_window#

Focus the neighboring window in the current tab

For example:

map ctrl+left neighboring_window left
map ctrl+down neighboring_window bottom
next_window#

Focus the next window in the current tab

Default shortcuts using this action: ctrl+shift+]

ninth_window#

Focus the ninth window

Default shortcuts using this action: ctrl+shift+9

nth_window#

Focus the nth window if positive or the previously active windows if negative. When the number is larger

than the number of windows focus the last window. For example:

# focus the previously active window
map ctrl+p nth_window -1
# focus the first window
map ctrl+1 nth_window 0
previous_window#

Focus the previous window in the current tab

Default shortcuts using this action: ctrl+shift+[

reset_window_sizes#

Reset window sizes undoing any dynamic resizing of windows

resize_window#

Resize the active window by the specified amount

See Resizing windows for details.

second_window#

Focus the second window

Default shortcuts using this action: ctrl+shift+2

seventh_window#

Focus the seventh window

Default shortcuts using this action: ctrl+shift+7

sixth_window#

Focus the sixth window

Default shortcuts using this action: ctrl+shift+6

swap_with_window#

Swap the current window with another window in the current tab, selected visually. See visual_window_select_characters

Default shortcuts using this action: ctrl+shift+f8

tenth_window#

Focus the tenth window

Default shortcuts using this action: ctrl+shift+0

third_window#

Focus the third window

Default shortcuts using this action: ctrl+shift+3

change_font_size#

Change the font size for the current or all OS Windows

See Font sizes for details.

Default shortcuts using this action: ctrl+shift+minus, ctrl+shift+equal, ctrl+shift+backspace

close_os_window#

Close the currently active OS Window

Default shortcuts using this action: shift+cmd+w

close_window#

Close the currently active window

Default shortcuts using this action: ctrl+shift+w

close_window_with_confirmation#

Close window with confirmation

Asks for confirmation before closing the window. If you don’t want the confirmation when the window is sitting at a shell prompt (requires Shell integration), use:

map f1 close_window_with_confirmation ignore-shell
detach_window#

Detach a window, moving it to another tab or OS Window

See detaching windows for details.

new_os_window#

New OS Window

Default shortcuts using this action: ctrl+shift+n

new_os_window_with_cwd#

New OS Window with the same working directory as the currently active window

new_window#

Create a new window

Default shortcuts using this action: ctrl+shift+enter

new_window_with_cwd#

Create a new window with working directory same as that of the active window

nth_os_window#

Focus the nth OS window

quit#

Quit, closing all windows

set_background_opacity#

Set the background opacity for the active OS Window

For example:

map f1 set_background_opacity +0.1
map f2 set_background_opacity -0.1
map f3 set_background_opacity 0.5

Default shortcuts using this action: ctrl+shift+a>l, ctrl+shift+a>1, ctrl+shift+a>m, ctrl+shift+a>d

start_resizing_window#

Resize the active window interactively

See Resizing windows for details.

Default shortcuts using this action: ctrl+shift+r

toggle_fullscreen#

Toggle the fullscreen status of the active OS Window

Default shortcuts using this action: ctrl+shift+f11

toggle_maximized#

Toggle the maximized status of the active OS Window

Default shortcuts using this action: ctrl+shift+f10