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

- 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

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`