kitty/docs/open_actions.rst

Scripting the mouse click
======================================================

|kitty| has support for `terminal hyperlinks
<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These
are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on these
hyperlinks in |kitty|.

You can tell kitty to take arbitrarily many, complex actions
when a link is clicked. Let us illustrate with some examples, first. Create
the file :file:`~/.config/kitty/open-actions.conf` with the following:

.. code:: conf

    # Open any image in the full kitty window by clicking on it
    protocol file
    mime image/*
    action launch --type=overlay kitty +kitten icat --hold ${FILE_PATH}

Now, run ``ls --hyperlink=auto`` in kitty and click on the filename of an
image, holding down :kbd:`ctrl+shift`. It will be opened over the current
window. Press any key to close it.

Each entry in :file:`open-actions.conf` consists of one or more
:ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more
``action`` entries. In the example above kitty uses the :doc:`launch <launch>`
action which can be used to run external programs. Entries are separated by
blank lines.

Actions are very powerful, anything that you can map to a key combination in
`kitty.conf` can be used as an action. You can specify more than one action per
entry if you like, for example:


.. code:: conf

    # Tail a log file (*.log) in a new OS Window and reduce its font size
    protocol file
    ext log
    action launch --title ${FILE} --type=os-window tail -f ${FILE_PATH}
    action change_font_size current -2


In the action specification you can expand environment variables, as shown in
the examples above. In addition to regular environment variables, there are
some special variables, documented below:

``URL``
    The full URL being opened

``FILE_PATH``
    The path portion of the URL (unquoted)

``FILE``
    The file portion of the path of the URL (unquoted)

``FRAGMENT``
    The fragment (unquoted), if any of the URL or the empty string.


.. note::
   You can use the :opt:`action_alias` option just as in kitty.conf to
   define aliases for frequently used actions.


.. _matching_criteria:

Matching criteria
------------------

An entry in :file:`open-actions.conf` must have one or more matching criteria.
URLs that match all criteria for an entry will trigger that entry's actions.
Processing stops at the first matching entry, so put more specific matching
criteria at the start of the list. Entries in the file are separated by blank
lines. The various available criteria are:

``protocol``
    A comma separated list of protocols, for example: ``http, https``. If
    absent, there is no constraint on protocol

``url``
    A regular expression that must match against the entire (unquoted) URL

``fragment_matches``
    A regular expression that must match against the fragment (part after #) in
    the URL

``mime``
    A comma separated list of MIME types, for example: ``text/*, image/*,
    application/pdf``. You can add MIME types to kitty by creating the
    :file:`mime.types` in the kitty configuration directory. Useful if your
    system MIME database does not have definitions you need. This file is
    in the standard format of one definition per line, like: ``text/plain rst
    md``. Note that the MIME type for directories is ``inode/directory``.

``ext``
    A comma separated list of file extensions, for example: ``jpeg, tar.gz``

``file``
    A shell glob pattern that must match the filename, for example:
    ``image-??.png``


.. _launch_actions:

Scripting the opening of files with kitty on macOS
-------------------------------------------------------

On macOS you can use :guilabel:`Open With` in Finder or drag and drop files and
URLs onto the kitty dock icon to open them with kitty. The default actions are:

* Open text files in your editor and images using the icat kitten.
* Run shell scripts in a shell
* Open SSH urls using the ssh command

These actions can also be executed from the command line by running::

    open -a kitty.app file_or_url ... (on macOS only)
    or
    kitty +open file_or_url ...

Since macOS lacks an official interface to set default URL scheme handler, you
can set it with the following command. The first argument for
``cocoa_set_url_handler`` is the URL scheme, and the second optional argument is
the bundle id of the app, which defaults to kitty's. (Restores when the second
argument is an empty string.)

.. code-block:: sh

    kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; print(cocoa_set_url_handler("ssh", "net.kovidgoyal.kitty"));'

You can customize these actions by creating a :file:`launch-actions.conf` file
in the kitty config directory, just like
the :file:`open-actions.conf` file above. For example:

.. code:: conf

    # Open script files based on their shebangs
    protocol file
    ext sh,command,tool
    action launch --hold --type=os-window kitty +shebang $FILE_PATH {SHELL}

    # Open shell specific script files
    protocol file
    ext fish,bash,zsh
    action launch --hold --type=os-window kitty +shebang $FILE_PATH __ext__

    # Open directories
    protocol file
    mime inode/directory
    action launch --type=os-window --cwd $FILE_PATH

    # Open text files without fragments in the editor
    protocol file
    mime text/*
    action launch --type=os-window $EDITOR $FILE_PATH

    # Open image files with icat
    protocol file
    mime image/*
    action launch --type=os-window kitty +kitten icat --hold $FILE_PATH

    # Open ssh URLs with ssh command
    protocol ssh
    action launch --type=os-window ssh $URL