Scripting the mouse click#

kitty has support for terminal hyperlinks. These are generated by many terminal programs, such as ls, gcc, systemd, 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 ~/.config/kitty/open-actions.conf with the following:

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

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

Note

The ls comes with macOS does not support hyperlink, you need to install GNU Coreutils. If you install it via Homebrew, it will be gls.

Each entry in open-actions.conf consists of one or more Matching criteria, such as protocol and mime and one or more action entries. In the example above kitty uses the 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:

# 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.
URL_PATH: The path, query and fragment portions of the URL, without any unquoting.
EDITOR: The terminal based text editor. The configured editor in kitty.conf is preferred.
SHELL: The path to the shell. The configured shell in kitty.conf is preferred, without arguments.

Note

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

Matching criteria#

An entry in 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 a file named 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. MIME types are detected based on file extension, not file contents.
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

Scripting the opening of files with kitty on macOS#

On macOS you can use 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:

kitty +open file_or_url another_url ...

# macOS only
open -a kitty.app file_or_url another_url ...

Since macOS lacks an official interface to set default URL scheme handlers, kitty has a command you can use for it. The first argument for is the URL scheme, and the second optional argument is the bundle id of the app, which defaults to kitty, if not specified. For example:

# Set kitty as the handler for ssh:// URLs
kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' ssh
# Set someapp as the handler for xyz:// URLs
kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' xyz someapp.bundle.identifier

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

# Open script files
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 executable file
protocol file
mime inode/executable,application/vnd.microsoft.portable-executable
action launch --hold --type=os-window $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 kitten icat --hold $FILE_PATH

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