Command palette
=================

.. only:: man

    Overview
    --------------


The command palette lets you browse, search and trigger all keyboard shortcuts
and actions in |kitty| from a single searchable overlay. Press
:sc:`command_palette` to open it (default: :kbd:`Ctrl+Shift+F3`).

.. figure:: ../screenshots/command-palette.webp
    :alt: A screenshot of the command palette kitten
    :align: center
    :width: 100%

    The command palette showing search results for ``win close``.

All mapped actions (those with a keyboard shortcut) and unmapped actions (those
available but not bound to any key) are listed, organized by category. Mouse
bindings are shown in a separate section. Simply type to search, select a
result, and press :kbd:`Enter` to run it.


Searching
-----------

As you type into the search bar, the palette filters results in real time using
word-level matching across three columns: key, action, and category.

Multiple search terms are supported. Typing ``scroll page`` matches items that
contain both "scroll" and "page" in any column. Items matching more of your
search terms rank higher than those matching fewer.

The search also handles compound tokens that contain delimiters such as
underscores or slashes. For example, typing ``mouse_selection`` matches the
full compound name as a unit. Typo tolerance is built in for words of four
characters or longer.

Matched characters are highlighted in the results so you can see exactly where
each term matched.


Keyboard controls
-------------------

The following keys are available while the command palette is open:

.. list-table::
    :widths: auto
    :header-rows: 1

    * - Key
      - Action
    * - Any text
      - Filter results by typing a search query
    * - :kbd:`Enter`
      - Run the selected action
    * - :kbd:`Escape`
      - Clear the search query, or close the palette if the query is already empty
    * - :kbd:`Up` / :kbd:`Ctrl+K` / :kbd:`Ctrl+P`
      - Move selection up
    * - :kbd:`Down` / :kbd:`Ctrl+J` / :kbd:`Ctrl+N`
      - Move selection down
    * - :kbd:`Page Up`
      - Move selection up by a page
    * - :kbd:`Page Down`
      - Move selection down by a page
    * - :kbd:`Home`
      - Jump to the first result
    * - :kbd:`End`
      - Jump to the last result
    * - :kbd:`Backspace`
      - Delete the last character from the query
    * - :kbd:`F12`
      - Toggle display of unmapped actions
    * - Mouse click
      - Select and run the clicked action


Unmapped actions
------------------

By default, the palette shows both mapped actions (those bound to a shortcut)
and unmapped actions (those with no shortcut assigned). Unmapped actions appear
with an ``(unmapped)`` label in the key column. Press :kbd:`F12` to toggle
their visibility. This preference is remembered across sessions.

Unmapped actions are useful for discovering functionality that you may not have
configured a shortcut for. You can run them directly from the palette, or note
the action name and add a mapping in :file:`kitty.conf`.


Custom keyboard modes
-----------------------

If you have defined custom :ref:`keyboard modes <modal_mappings>` in your
configuration, their bindings appear under separate mode headers in the palette.
The ``push_keyboard_mode`` bindings are grouped with the target mode they
activate, making it easy to see how to enter each mode alongside its shortcuts.


Configuration
--------------

The default mapping to open the command palette is::

    map kitty_mod+f3 command_palette

You can change this in :file:`kitty.conf` like any other mapping. For example::

    map ctrl+p command_palette