kitty.conf.example

#: Keyboard shortcuts {{{

#: Keys are identified simply by their lowercase Unicode characters.
#: For example: a for the A key, [ for the left square bracket key,
#: etc. For functional keys, such as Enter or Escape, the names are
#: present at Functional key definitions
#: <https://sw.kovidgoyal.net/kitty/keyboard-protocol/#functional>.
#: For modifier keys, the names are ctrl (control, ⌃), shift (⇧), alt
#: (opt, option, ⌥), super (cmd, command, ⌘).

#: Simple shortcut mapping is done with the map directive. For full
#: details on advanced mapping including modal and per application
#: maps, see mapping <https://sw.kovidgoyal.net/kitty/mapping/>. Some
#: quick examples to illustrate common tasks::

#:     # unmap a keyboard shortcut, passing it to the program running in kitty
#:     map kitty_mod+space
#:     # completely ignore a keyboard event
#:     map ctrl+alt+f1 discard_event
#:     # combine multiple actions
#:     map kitty_mod+e combine : new_window : next_layout
#:     # multi-key shortcuts
#:     map ctrl+x>ctrl+y>z action

#: The full list of actions that can be mapped to key presses is
#: available here <https://sw.kovidgoyal.net/kitty/actions/>.

# kitty_mod ctrl+shift

#: Special modifier key alias for default shortcuts. You can change
#: the value of this option to alter all default shortcuts that use
#: kitty_mod.

# clear_all_shortcuts no

#: Remove all shortcut definitions up to this point. Useful, for
#: instance, to remove the default shortcuts.

# action_alias

#: E.g. action_alias launch_tab launch --type=tab --cwd=current

#: Define action aliases to avoid repeating the same options in
#: multiple mappings. Aliases can be defined for any action and will
#: be expanded recursively. For example, the above alias allows you to
#: create mappings to launch a new tab in the current working
#: directory without duplication::

#:     map f1 launch_tab vim
#:     map f2 launch_tab emacs

#: Similarly, to alias kitten invocation::

#:     action_alias hints kitten hints --hints-offset=0

# kitten_alias

#: E.g. kitten_alias hints hints --hints-offset=0

#: Like action_alias above, but specifically for kittens. Generally,
#: prefer to use action_alias. This option is a legacy version,
#: present for backwards compatibility. It causes all invocations of
#: the aliased kitten to be substituted. So the example above will
#: cause all invocations of the hints kitten to have the --hints-
#: offset=0 option applied.

#: Clipboard {{{

#: Copy to clipboard

# map kitty_mod+c copy_to_clipboard
# map cmd+c       copy_to_clipboard

#::  There is also a copy_or_interrupt action that can be optionally
#::  mapped to Ctrl+C. It will copy only if there is a selection and
#::  send an interrupt otherwise. Similarly,
#::  copy_and_clear_or_interrupt will copy and clear the selection or
#::  send an interrupt if there is no selection.

#: Paste from clipboard

# map kitty_mod+v paste_from_clipboard
# map cmd+v       paste_from_clipboard

#: Paste from selection

# map kitty_mod+s  paste_from_selection
# map shift+insert paste_from_selection

#: Pass selection to program

# map kitty_mod+o pass_selection_to_program

#::  You can also pass the contents of the current selection to any
#::  program with pass_selection_to_program. By default, the system's
#::  open program is used, but you can specify your own, the selection
#::  will be passed as a command line argument to the program. For
#::  example::

#::      map kitty_mod+o pass_selection_to_program firefox

#::  You can pass the current selection to a terminal program running
#::  in a new kitty window, by using the @selection placeholder::

#::      map kitty_mod+y new_window less @selection

#: }}}

#: Scrolling {{{

#: Scroll line up

# map kitty_mod+up    scroll_line_up
# map kitty_mod+k     scroll_line_up
# map opt+cmd+page_up scroll_line_up
# map cmd+up          scroll_line_up

#: Scroll line down

# map kitty_mod+down    scroll_line_down
# map kitty_mod+j       scroll_line_down
# map opt+cmd+page_down scroll_line_down
# map cmd+down          scroll_line_down

#: Scroll page up

# map kitty_mod+page_up scroll_page_up
# map cmd+page_up       scroll_page_up

#: Scroll page down

# map kitty_mod+page_down scroll_page_down
# map cmd+page_down       scroll_page_down

#: Scroll to top

# map kitty_mod+home scroll_home
# map cmd+home       scroll_home

#: Scroll to bottom

# map kitty_mod+end scroll_end
# map cmd+end       scroll_end

#: Scroll to previous shell prompt

# map kitty_mod+z scroll_to_prompt -1

#::  Use a parameter of 0 for scroll_to_prompt to scroll to the last
#::  jumped to or the last clicked position. Requires shell
#::  integration <https://sw.kovidgoyal.net/kitty/shell-integration/>
#::  to work.

#: Scroll to next shell prompt

# map kitty_mod+x scroll_to_prompt 1

#: Browse scrollback buffer in pager

# map kitty_mod+h show_scrollback

#::  You can pipe the contents of the current screen and history
#::  buffer as STDIN to an arbitrary program using launch --stdin-
#::  source. For example, the following opens the scrollback buffer in
#::  less in an overlay window::

#::      map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting --type=overlay less +G -R

#::  For more details on piping screen and buffer contents to external
#::  programs, see launch <https://sw.kovidgoyal.net/kitty/launch/>.

#: Browse output of the last shell command in pager

# map kitty_mod+g show_last_command_output

#::  You can also define additional shortcuts to get the command
#::  output. For example, to get the first command output on screen::

#::      map f1 show_first_command_output_on_screen

#::  To get the command output that was last accessed by a keyboard
#::  action or mouse action::

#::      map f1 show_last_visited_command_output

#::  You can pipe the output of the last command run in the shell
#::  using the launch action. For example, the following opens the
#::  output in less in an overlay window::

#::      map f1 launch --stdin-source=@last_cmd_output --stdin-add-formatting --type=overlay less +G -R

#::  To get the output of the first command on the screen, use
#::  @first_cmd_output_on_screen. To get the output of the last jumped
#::  to command, use @last_visited_cmd_output.

#::  Requires shell integration
#::  <https://sw.kovidgoyal.net/kitty/shell-integration/> to work.

#: }}}

#: Window management {{{

#: New window

# map kitty_mod+enter new_window
# map cmd+enter       new_window

#::  You can open a new kitty window running an arbitrary program, for
#::  example::

#::      map kitty_mod+y launch mutt

#::  You can open a new window with the current working directory set
#::  to the working directory of the current window using::

#::      map ctrl+alt+enter launch --cwd=current

#::  You can open a new window that is allowed to control kitty via
#::  the kitty remote control facility with launch --allow-remote-
#::  control. Any programs running in that window will be allowed to
#::  control kitty. For example::

#::      map ctrl+enter launch --allow-remote-control some_program

#::  You can open a new window next to the currently active window or
#::  as the first window, with::

#::      map ctrl+n launch --location=neighbor
#::      map ctrl+f launch --location=first

#::  For more details, see launch
#::  <https://sw.kovidgoyal.net/kitty/launch/>.

#: New OS window

# map kitty_mod+n new_os_window
# map cmd+n       new_os_window

#::  Works like new_window above, except that it opens a top-level OS
#::  window. In particular you can use new_os_window_with_cwd to open
#::  a window with the current working directory.

#: Close window

# map kitty_mod+w close_window
# map shift+cmd+d close_window

#: Next window

# map kitty_mod+] next_window

#: Previous window

# map kitty_mod+[ previous_window

#: Move window forward

# map kitty_mod+f move_window_forward

#: Move window backward

# map kitty_mod+b move_window_backward

#: Move window to top

# map kitty_mod+` move_window_to_top

#: Start resizing window

# map kitty_mod+r start_resizing_window
# map cmd+r       start_resizing_window

#: First window

# map kitty_mod+1 first_window
# map cmd+1       first_window

#: Second window

# map kitty_mod+2 second_window
# map cmd+2       second_window

#: Third window

# map kitty_mod+3 third_window
# map cmd+3       third_window

#: Fourth window

# map kitty_mod+4 fourth_window
# map cmd+4       fourth_window

#: Fifth window

# map kitty_mod+5 fifth_window
# map cmd+5       fifth_window

#: Sixth window

# map kitty_mod+6 sixth_window
# map cmd+6       sixth_window

#: Seventh window

# map kitty_mod+7 seventh_window
# map cmd+7       seventh_window

#: Eighth window

# map kitty_mod+8 eighth_window
# map cmd+8       eighth_window

#: Ninth window

# map kitty_mod+9 ninth_window
# map cmd+9       ninth_window

#: Tenth window

# map kitty_mod+0 tenth_window

#: Visually select and focus window

# map kitty_mod+f7 focus_visible_window

#::  Display overlay numbers and alphabets on the window, and switch
#::  the focus to the window when you press the key. When there are
#::  only two windows, the focus will be switched directly without
#::  displaying the overlay. You can change the overlay characters and
#::  their order with option visual_window_select_characters.

#: Visually swap window with another

# map kitty_mod+f8 swap_with_window

#::  Works like focus_visible_window above, but swaps the window.

#: }}}

#: Tab management {{{

#: Next tab

# map kitty_mod+right next_tab
# map shift+cmd+]     next_tab
# map ctrl+tab        next_tab

#: Previous tab

# map kitty_mod+left previous_tab
# map shift+cmd+[    previous_tab
# map ctrl+shift+tab previous_tab

#: New tab

# map kitty_mod+t new_tab
# map cmd+t       new_tab

#: Close tab

# map kitty_mod+q close_tab
# map cmd+w       close_tab

#: Close OS window

# map shift+cmd+w close_os_window

#: Move tab forward

# map kitty_mod+. move_tab_forward

#: Move tab backward

# map kitty_mod+, move_tab_backward

#: Set tab title

# map kitty_mod+alt+t set_tab_title
# map shift+cmd+i     set_tab_title


#: You can also create shortcuts to go to specific tabs, with 1 being
#: the first tab, 2 the second tab and -1 being the previously active
#: tab, and any number larger than the last tab being the last tab::

#:     map ctrl+alt+1 goto_tab 1
#:     map ctrl+alt+2 goto_tab 2

#: Just as with new_window above, you can also pass the name of
#: arbitrary commands to run when using new_tab and new_tab_with_cwd.
#: Finally, if you want the new tab to open next to the current tab
#: rather than at the end of the tabs list, use::

#:     map ctrl+t new_tab !neighbor [optional cmd to run]
#: }}}

#: Layout management {{{

#: Next layout

# map kitty_mod+l next_layout


#: You can also create shortcuts to switch to specific layouts::

#:     map ctrl+alt+t goto_layout tall
#:     map ctrl+alt+s goto_layout stack

#: Similarly, to switch back to the previous layout::

#:     map ctrl+alt+p last_used_layout

#: There is also a toggle_layout action that switches to the named
#: layout or back to the previous layout if in the named layout.
#: Useful to temporarily "zoom" the active window by switching to the
#: stack layout::

#:     map ctrl+alt+z toggle_layout stack
#: }}}

#: Font sizes {{{

#: You can change the font size for all top-level kitty OS windows at
#: a time or only the current one.

#: Increase font size

# map kitty_mod+equal  change_font_size all +2.0
# map kitty_mod+plus   change_font_size all +2.0
# map kitty_mod+kp_add change_font_size all +2.0
# map cmd+plus         change_font_size all +2.0
# map cmd+equal        change_font_size all +2.0
# map shift+cmd+equal  change_font_size all +2.0

#: Decrease font size

# map kitty_mod+minus       change_font_size all -2.0
# map kitty_mod+kp_subtract change_font_size all -2.0
# map cmd+minus             change_font_size all -2.0
# map shift+cmd+minus       change_font_size all -2.0

#: Reset font size

# map kitty_mod+backspace change_font_size all 0
# map cmd+0               change_font_size all 0


#: To setup shortcuts for specific font sizes::

#:     map kitty_mod+f6 change_font_size all 10.0

#: To setup shortcuts to change only the current OS window's font
#: size::

#:     map kitty_mod+f6 change_font_size current 10.0
#: }}}

#: Select and act on visible text {{{

#: Use the hints kitten to select text and either pass it to an
#: external program or insert it into the terminal or copy it to the
#: clipboard.

#: Open URL

# map kitty_mod+e open_url_with_hints

#::  Open a currently visible URL using the keyboard. The program used
#::  to open the URL is specified in open_url_with.

#: Insert selected path

# map kitty_mod+p>f kitten hints --type path --program -

#::  Select a path/filename and insert it into the terminal. Useful,
#::  for instance to run git commands on a filename output from a
#::  previous git command.

#: Open selected path

# map kitty_mod+p>shift+f kitten hints --type path

#::  Select a path/filename and open it with the default open program.

#: Insert selected line

# map kitty_mod+p>l kitten hints --type line --program -

#::  Select a line of text and insert it into the terminal. Useful for
#::  the output of things like: `ls -1`.

#: Insert selected word

# map kitty_mod+p>w kitten hints --type word --program -

#::  Select words and insert into terminal.

#: Insert selected hash

# map kitty_mod+p>h kitten hints --type hash --program -

#::  Select something that looks like a hash and insert it into the
#::  terminal. Useful with git, which uses SHA1 hashes to identify
#::  commits.

#: Open the selected file at the selected line

# map kitty_mod+p>n kitten hints --type linenum

#::  Select something that looks like filename:linenum and open it in
#::  vim at the specified line number.

#: Open the selected hyperlink

# map kitty_mod+p>y kitten hints --type hyperlink

#::  Select a hyperlink (i.e. a URL that has been marked as such by
#::  the terminal program, for example, by `ls --hyperlink=auto`).


#: The hints kitten has many more modes of operation that you can map
#: to different shortcuts. For a full description see hints kitten
#: <https://sw.kovidgoyal.net/kitty/kittens/hints/>.
#: }}}

#: Miscellaneous {{{

#: Show documentation

# map kitty_mod+f1 show_kitty_doc overview

#: Toggle fullscreen

# map kitty_mod+f11 toggle_fullscreen
# map ctrl+cmd+f    toggle_fullscreen

#: Toggle maximized

# map kitty_mod+f10 toggle_maximized

#: Toggle macOS secure keyboard entry

# map opt+cmd+s toggle_macos_secure_keyboard_entry

#: Unicode input

# map kitty_mod+u    kitten unicode_input
# map ctrl+cmd+space kitten unicode_input

#: Edit config file

# map kitty_mod+f2 edit_config_file
# map cmd+,        edit_config_file

#: Open the kitty command shell

# map kitty_mod+escape kitty_shell window

#::  Open the kitty shell in a new window / tab / overlay / os_window
#::  to control kitty using commands.

#: Increase background opacity

# map kitty_mod+a>m set_background_opacity +0.1

#: Decrease background opacity

# map kitty_mod+a>l set_background_opacity -0.1

#: Make background fully opaque

# map kitty_mod+a>1 set_background_opacity 1

#: Reset background opacity

# map kitty_mod+a>d set_background_opacity default

#: Reset the terminal

# map kitty_mod+delete clear_terminal reset active
# map opt+cmd+r        clear_terminal reset active

#::  You can create shortcuts to clear/reset the terminal. 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

#::  If you want to operate on all kitty windows instead of just the
#::  current one, use all instead of active.

#::  Some useful functions that can be defined in the shell rc files
#::  to perform various kinds of clearing of the current window:

#::  .. code-block:: sh

#::      clear-only-screen() {
#::          printf "\e[H\e[2J"
#::      }

#::      clear-screen-and-scrollback() {
#::          printf "\e[H\e[3J"
#::      }

#::      clear-screen-saving-contents-in-scrollback() {
#::          printf "\e[H\e[22J"
#::      }

#::  For instance, using these escape codes, it is possible to remap
#::  Ctrl+L to both scroll the current screen contents into the
#::  scrollback buffer and clear the screen, instead of just clearing
#::  the screen. For ZSH, in ~/.zshrc, add:

#::  .. code-block:: zsh

#::      ctrl_l() {
#::          builtin print -rn -- $'\r\e[0J\e[H\e[22J' >"$TTY"
#::          builtin zle .reset-prompt
#::          builtin zle -R
#::      }
#::      zle -N ctrl_l
#::      bindkey '^l' ctrl_l

#: Clear up to cursor line

# map cmd+k clear_terminal to_cursor active

#: Reload kitty.conf

# map kitty_mod+f5 load_config_file
# map ctrl+cmd+,   load_config_file

#::  Reload kitty.conf, applying any changes since the last time it
#::  was loaded. Note that a handful of options cannot be dynamically
#::  changed and require a full restart of kitty. Particularly, when
#::  changing shortcuts for actions located on the macOS global menu
#::  bar, a full restart is needed. You can also map a keybinding to
#::  load a different config file, for example::

#::      map f5 load_config /path/to/alternative/kitty.conf

#::  Note that all options from the original kitty.conf are discarded,
#::  in other words the new configuration *replace* the old ones.

#: Debug kitty configuration

# map kitty_mod+f6 debug_config
# map opt+cmd+,    debug_config

#::  Show details about exactly what configuration kitty is running
#::  with and its host environment. Useful for debugging issues.

#: Send arbitrary text on key presses

#::  E.g. map ctrl+shift+alt+h send_text all Hello World

#::  You can tell kitty to send arbitrary (UTF-8) encoded text to the
#::  client program when pressing specified shortcut keys. For
#::  example::

#::      map ctrl+alt+a send_text all Special text

#::  This will send "Special text" when you press the Ctrl+Alt+A key
#::  combination. The text to be sent decodes ANSI C escapes
#::  <https://www.gnu.org/software/bash/manual/html_node/ANSI_002dC-
#::  Quoting.html> so you can use escapes like \e to send control
#::  codes or \u21fb to send Unicode characters (or you can just input
#::  the Unicode characters directly as UTF-8 text). You can use
#::  `kitten show_key` to get the key escape codes you want to
#::  emulate.

#::  The first argument to send_text is the keyboard modes in which to
#::  activate the shortcut. The possible values are normal,
#::  application, kitty or a comma separated combination of them. The
#::  modes normal and application refer to the DECCKM cursor key mode
#::  for terminals, and kitty refers to the kitty extended keyboard
#::  protocol. The special value all means all of them.

#::  Some more examples::

#::      # Output a word and move the cursor to the start of the line (like typing and pressing Home)
#::      map ctrl+alt+a send_text normal Word\e[H
#::      map ctrl+alt+a send_text application Word\eOH
#::      # Run a command at a shell prompt (like typing the command and pressing Enter)
#::      map ctrl+alt+a send_text normal,application some command with arguments\r

#: Open kitty Website

# map shift+cmd+/ open_url https://sw.kovidgoyal.net/kitty/

#: Hide macOS kitty application

# map cmd+h hide_macos_app

#: Hide macOS other applications

# map opt+cmd+h hide_macos_other_apps

#: Minimize macOS window

# map cmd+m minimize_macos_window

#: Quit kitty

# map cmd+q quit

#: }}}

#: }}}