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

# 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_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 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

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`

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 kitty_mod+f9 clear_terminal reset active
    # Clear the terminal screen by erasing all contents
    map kitty_mod+f10 clear_terminal clear active
    # Clear the terminal scrollback by erasing it
    map kitty_mod+f11 clear_terminal scrollback active
    # Scroll the contents of the screen into the scrollback
    map kitty_mod+f12 clear_terminal scroll active
    # Clear everything up to the line with the cursor
    map kitty_mod+f9 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:

- Hints - `ctrl+shift+p>h` Insert selected hash

- Hints - `ctrl+shift+p>l` Insert selected line

- Hints - `ctrl+shift+p>f` Insert selected path

- Hints - `ctrl+shift+p>w` Insert selected word

- Hints - `ctrl+shift+p>shift+f` Open selected path

- Hints - `ctrl+shift+p>n` Open the selected file at the selected line

- Hints - `ctrl+shift+p>y` Open the selected hyperlink

- Unicode input - `ctrl+shift+u` Unicode input

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_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 form the scrollback buffer

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_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

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`