Skip to main content

Viewing and Modifying Kitty Keyboard Shortcuts

Perfect — here is the corrected, fully updated article, with all inaccuracies removed and the mental model aligned with what kitty actually does today.

This is ready to drop in under the frontmatter.

Viewing and Modifying Kitty Keyboard Shortcuts

Kitty’s keyboard shortcuts are explicit and configurable, but AFAIK they are not exposed via a traditional in-terminal “help panel” like tmux. Instead, kitty relies on configuration files and generated documentation.

This article explains the actual, correct ways to:

  1. View existing kitty keyboard shortcuts
  2. Modify or add your own shortcuts
  3. Debug key behavior when needed

1. Viewing Kitty Keyboard Shortcuts​

Kitty’s authoritative list of default keybindings lives in the example config file shipped with the package:

/usr/share/doc/kitty/examples/kitty.conf

Search for keybindings:

grep '^map ' /usr/share/doc/kitty/examples/kitty.conf

This file contains:

  • All default shortcuts
  • Inline comments explaining what they do
  • The actual source used by kitty

This is the most reliable and terminal-native reference.

1.2 Browser-based help (generated from your active config)​

Inside a kitty window, press:

Ctrl + Shift + F1

This generates an HTML help page and opens it in your default web browser.

What it shows:

  • Active keybindings
  • Defaults plus your overrides
  • Generated from your running configuration

Notes:

  • This opens outside the terminal
  • It is accurate, but involves a context switch
  • Useful for browsing, not ideal as a primary reference

1.3 What does not exist (important clarification)​

There is no built-in kitten that lists all keybindings in-terminal.

Specifically, commands like:

kitty +kitten show_keybindings

do not exist and will fail.

Kitty does not provide a TUI or CLI command that prints the full active keymap.

2. Debugging Key Input (Advanced)​

Kitty does provide a diagnostic tool for inspecting raw key events:

kitty +kitten show_key

This does not show shortcuts.

Instead, it displays:

  • The raw key events kitty receives
  • Escape sequences
  • Modifier states

Use this only when:

  • Writing custom keybindings
  • Debugging unexpected behavior
  • Investigating how a key combo is interpreted

Exit with:

Ctrl + D

3. Modifying Kitty Keyboard Shortcuts​

All keyboard customization happens in one file:

~/.config/kitty/kitty.conf

Create it if needed:

mkdir -p ~/.config/kitty
nano ~/.config/kitty/kitty.conf

3.1 Basic keybinding syntax​

map <key-combo> <action>

Example:

map ctrl+shift+o copy_last_cmd_output

This binds:

Ctrl + Shift + O

to copying the previous command’s output.

3.2 Overriding default shortcuts​

Redefining a key automatically overrides the default.

Example:

map ctrl+shift+h show_scrollback

No explicit “disable” step is required.

3.3 Unbinding a shortcut​

To disable a default binding:

map ctrl+shift+t noop

This is useful for removing features you don’t use (tabs, layouts, etc.).

3.4 Discovering available actions​

Actions you can bind are listed in the example config file:

/usr/share/doc/kitty/examples/kitty.conf

Search for:

# Actions

Common examples include:

  • copy_to_clipboard
  • paste_from_clipboard
  • show_scrollback
  • copy_last_cmd_output
  • new_window
  • close_window

If an action exists, it’s documented there.

4. Applying changes​

After editing kitty.conf:

  • Close all kitty windows
  • Relaunch kitty

Kitty reads its configuration at startup.

To keep things sane:

  • Treat the example config as the source of truth
  • Use browser help for occasional browsing
  • Use show_key only for debugging
  • Keep your custom bindings minimal and intentional

Kitty favors explicit configuration over runtime introspection.

TL;DR​

  • There is no in-terminal keybinding viewer

  • Default shortcuts live in:

    /usr/share/doc/kitty/examples/kitty.conf

  • Ctrl + Shift + F1 opens browser-based help

  • kitty +kitten show_key is for debugging keys, not listing shortcuts

  • Modify bindings via ~/.config/kitty/kitty.conf