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. ANSI C escapes are decoded.

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

In case there are multiple layouts with the same name and different options, specify the full layout definition or a unique prefix of the full definition.

For example:

map f1 goto_layout tall
map f2 goto_layout fat:bias=20
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. Can optionally supply an integer to jump by the specified number.

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

hide_macos_app

Hide macOS kitty application

Default shortcuts using this action: cmd+h

hide_macos_other_apps

Hide macOS other applications

Default shortcuts using this action: opt+cmd+h

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

minimize_macos_window

Minimize macOS window

Default shortcuts using this action: cmd+m

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
sleep

Sleep for the specified time period. Suffix can be s for seconds, m, for minutes, h for hours and d for days. The time can be fractional.

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 when in main screen

Default shortcuts using this action: ctrl+shift+end

scroll_home

Scroll to the top of the scrollback buffer when in main screen

Default shortcuts using this action: ctrl+shift+home

scroll_line_down

Scroll down by one line when in main screen

Default shortcuts using this action: ctrl+shift+down

scroll_line_up

Scroll up by one line when in main screen

Default shortcuts using this action: ctrl+shift+up

scroll_page_down

Scroll down by one page when in main screen

Default shortcuts using this action: ctrl+shift+page_down

scroll_page_up

Scroll up by one page when in main screen

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, when in main screen

scroll_prompt_to_top

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

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. Use a space (” “) to indicate that the prompt should not be pre-filled. 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 ""
# interactive usage without prefilled prompt
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

Default shortcuts using this action: cmd+q

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