Kitty

https://sw.kovidgoyal.net/kitty/
Admin
Kitty is a GPU-based terminal emulator with support for tabs, windows, layouts, and extensible...
Tokens:499,222
Snippets:3,812
Trust Score:9.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Develop docs with live reloading

Source: https://sw.kovidgoyal.net/kitty/build/

Installs documentation dependencies and starts the docs server with live reloading for development.

```bash
./dev.sh deps -for-docs && ./dev.sh docs -live-reload
```

--------------------------------

### send_text examples for normal and application modes

Source: https://sw.kovidgoyal.net/kitty/conf/

Shows how to send a word and move the cursor to the start of the line, and how to run a command at a shell prompt. The first argument specifies keyboard modes: normal, application, kitty, or a combination.

```kitty.conf
# 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
```

--------------------------------

### Start kitty with save_as_session mapping

Source: https://sw.kovidgoyal.net/kitty/sessions/

Starts kitty with a key mapping (F1) to save the current session. Use this to interactively save a complex session setup.

```shell
kitty -o 'map f1 save_as_session --use-foreground-process --relocatable'
```

--------------------------------

### exe_search_path configuration example

Source: https://sw.kovidgoyal.net/kitty/conf/

Shows how to prepend, append, and remove paths from the executable search order. A simple path is prepended, a path starting with '+' is appended after ~/bin, and a path starting with '-' is removed from the entire search order.

```conf
exe_search_path /some/prepended/path
exe_search_path +/some/appended/path
exe_search_path -/some/excluded/path
```

--------------------------------

### Start resizing window

Source: https://sw.kovidgoyal.net/kitty/_downloads/433dadebd0bf504f8b008985378086ce/kitty.conf

Default mappings to start resizing the window, using kitty_mod+r and cmd+r with fallback to shifted and ascii keys.

```conf
# map --allow-fallback=shifted,ascii kitty_mod+r start_resizing_window
# map --allow-fallback=shifted,ascii cmd+r start_resizing_window
```

--------------------------------

### Install nightly kitty build with installer

Source: https://sw.kovidgoyal.net/kitty/binary/

Use this command to install the latest nightly kitty build. The installer script is fetched via curl and executed with the installer=nightly option.

```bash
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin \
    installer=nightly
```

--------------------------------

### Install kitty with the official installer script

Source: https://sw.kovidgoyal.net/kitty/binary/

Run this command in a terminal to download and execute the kitty installer. It installs to /Applications/kitty.app on macOS and ~/.local/kitty.app on Linux. Re-run the command to update kitty. Do not copy the binary out of the installation folder; create a symlink in a systemwide PATH directory instead.

```bash
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin
```

--------------------------------

### close_session configuration examples

Source: https://sw.kovidgoyal.net/kitty/actions/

Examples of mapping the close_session action to keys in kitty.conf. The first example prompts for the session to close, the second closes the currently active session, the third closes a session by name, and the fourth closes a session by path to a session file.

```kitty.conf
# Ask for the session to close
map f1 close_session
```

```kitty.conf
# Close the currently active session
map f1 close_session .
```

```kitty.conf
# Close session by name
map f1 close_session "my session"
```

```kitty.conf
# Close session by path to session file
map f1 close_session "/path/to/session/file.kitty-session"
```

--------------------------------

### Example ssh.conf configuration

Source: https://sw.kovidgoyal.net/kitty/kittens/ssh/

Example configuration for the SSH kitten, showing how to copy files, set environment variables, and define per-host settings.

```conf
# Copy the files and directories needed to setup some common tools
copy .zshrc .vimrc .vim
# Setup some environment variables
env SOME_VAR=x
# COPIED_VAR will have the same value on the remote host as it does locally
env COPIED_VAR=_kitty_copy_env_var_

# Create some per hostname settings
hostname someserver-*
copy env-files
env SOMETHING=else

hostname someuser@somehost
copy --dest=foo/bar some-file
copy --glob some/files.*
```

--------------------------------

### show_kitty_doc example

Source: https://sw.kovidgoyal.net/kitty/actions/

Shows how to map a key to display kitty documentation, preferring a local copy if found. The first mapping shows the configuration docs, the second shows the ssh kitten docs.

```kitty config
# show the config docs
map f1 show_kitty_doc conf
# show the ssh kitten docs
map f1 show_kitty_doc kittens/ssh
```

--------------------------------

### macos-launch-services-cmdline example

Source: https://sw.kovidgoyal.net/kitty/faq/

Example contents for the macos-launch-services-cmdline file, which kitty reads when launched from the GUI on macOS. The file is only read when running via the GUI and contains the command line in shell syntax.

```shell
--single-instance --override background=red
```

--------------------------------

### Example kitty session file with major keywords

Source: https://sw.kovidgoyal.net/kitty/sessions/

A complete example session file showing all major keywords: layout, cd, launch, new_tab, enabled_layouts, new_os_window, os_window_size, os_window_title, os_window_class, os_window_name, os_window_state, resize_window, focus, focus_os_window, focus_tab, and complex splits. Note that launch in a session file cannot create new OS windows or tabs.

```kitty-session
# Set the layout for the current tab
layout tall
# Set the working directory for windows in the current tab. Relative paths
# are resolved with respect to the location of this session file.
cd ~
# Create a window and run the specified command in it
launch zsh
# Create a window with some environment variables set and run vim in it
launch --env FOO=BAR vim
# Set the title for the next window
launch --title "Chat with x" irssi --profile x
# Run a short lived command and see its output
launch --hold message-of-the-day

# Create a new tab
# The part after new_tab is the optional tab title which will be displayed in
# the tab bar, if omitted, the title of the active window will be used instead.
new_tab my tab
cd somewhere
# Set the layouts allowed in this tab
enabled_layouts tall,stack
# Set the current layout
layout stack
launch zsh

# Create a new OS window
# Any definitions specified before the first new_os_window will apply to first OS window.
new_os_window
# Set new window size to 80x24 cells
os_window_size 80c 24c
# Set the --title for the new OS window
os_window_title my fancy os window
# Set the --class for the new OS window
os_window_class mywindow
# Set the --name for the new OS window
os_window_name myname
# Change the OS window state to normal, fullscreen, maximized or minimized
os_window_state normal
launch sh
# Resize the current window (see the resize_window action for details)
resize_window wider 2
# Make the current window the active (focused) window in its tab
focus
# Make the current OS Window the globally active window
focus_os_window
launch emacs

# Create another tab
new_tab logs
launch tail -f /var/log/syslog

# Focus the first tab (index 0) when the session loads
# You can also use a match expression like: focus_tab title:logs
focus_tab 0

# Create a complex layout using multiple splits. Creates two columns of
# windows with two windows in each column. The windows in the first column are
# split 50:50. In the second column the windows are not evenly split.
new_tab complex tab
layout splits
# First window, set a user variable on it so we can focus it later
launch --var window=first
# Create the second column by splitting the first window vertically
launch --location=vsplit
# Create the third window in the second column by splitting the second window horizontally
# Make it take 40% of the height instead of 50%
launch --location=hsplit --bias=40
# Go back to focusing the first window, so that we can split it
focus_matching_window var:window=first
# Create the final window in the first column
launch --location=hsplit
```

--------------------------------

### Zsh: Mark command start with OSC 133 C

Source: https://sw.kovidgoyal.net/kitty/shell-integration/

Prints an OSC 133 C sequence with the command line to mark the start of a command. This is used in a preexec hook, and the comment warns that it may work incorrectly if a preexec hook that prints is installed before it.

```zsh
# This will work incorrectly in the presence of a preexec hook that
# prints. For example, if MichaelAquilina/zsh-you-should-use installs
# its preexec hook before us, we'll incorrectly mark its output as
# belonging to the command (as if the user typed it into zle) rather
# than command output.
builtin print -nu "$_ksi_fd" -f '\e]133;C;cmdline=%q\a' -- "$1"
(( _ksi_state = 1 ))
```

--------------------------------

### Custom launch-actions.conf example

Source: https://sw.kovidgoyal.net/kitty/open_actions/

Example configuration for launch-actions.conf to customize default actions. Includes rules for script files, directories, executables, text files, images, and ssh URLs.

```conf
# Open script files. Change confirm-always to confirm-never or confirm-if-needed to
# disable confirmation for all or executable files respectively.
protocol file
ext sh,command,tool
action launch --hold --type=os-window kitten __shebang__ confirm-always $FILE_PATH $SHELL

# Open shell specific script files
protocol file
ext fish,bash,zsh
action launch --hold --type=os-window kitten __shebang__ confirm-always $FILE_PATH __ext__

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

# Open executable file. Remove kitten __confirm_and_run_exe__ to execute
# without confirmation.
protocol file
mime inode/executable,application/vnd.microsoft.portable-executable
action launch --hold --type=os-window -- kitten __confirm_and_run_exe__ $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
```

--------------------------------

### Quickstart: show multiple cursors with printf

Source: https://sw.kovidgoyal.net/kitty/multiple-cursors-protocol/

Example from the Quickstart section showing how to use the protocol. The first printf displays a cursor of the same shape as the main cursor at y=4, x=5. The second printf displays more cursors on the seventh line with various shapes, including the underline shape twice.

```shell
# Show cursors of the same shape as the main cursor at y=4, x=5
printf "\e[>29;2:4:5 q"
# Show more cursors on the seventh line, of various shapes, the underline shape is shown twice
printf "\e[>1;2:7:1 q\e[>2;2:7:3 q\e[>3;2:7:5;2:7:7 q"
```

--------------------------------

### move_window configuration examples

Source: https://sw.kovidgoyal.net/kitty/actions/

Shows how to map the move_window action to move the active window in a specified direction.

```kitty config
map ctrl+left move_window left
map ctrl+down move_window bottom
```

--------------------------------

### Example session file for a project

Source: https://sw.kovidgoyal.net/kitty/sessions/

A session file that sets the layout to tall, changes to the project directory, and launches three windows: an editor, a shell, and a log viewer. Save as ~/path/to/myproject/launch.kitty-session.

```kitty session
# Set the layout for the current tab
layout tall
# Set the working directory for windows in the current tab
cd ~/path/to/myproject
# Create the "main" window and run an editor in it to edit the project files
launch --title "Edit My Project" /usr/bin/nvim
# Create a side window to run a shell to build or test project
launch --title "Build My Project"
# Create another side window to keep an eye on some useful log file
launch --title "Log for my project" /usr/bin/tail -f /path/to/project/log/file
```

--------------------------------

### Install kitty without launching with launch=n

Source: https://sw.kovidgoyal.net/kitty/binary/

Prevents the installer from launching kitty after installation by setting launch=n. Useful for scripted or non-interactive installs.

```bash
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin \
    launch=n
```

--------------------------------

### combine syntax and examples

Source: https://sw.kovidgoyal.net/kitty/actions/

Shows the syntax for the combine action, which combines multiple actions into a single keypress. The examples map kitty_mod+e to either new_window followed by next_layout, or new_tab followed by goto_tab -1, using different separators.

```kitty config
map key combine <separator> action1 <separator> action2 <separator> action3 ...
```

```kitty config
map kitty_mod+e combine : new_window : next_layout
map kitty_mod+e combine | new_tab | goto_tab -1
```

--------------------------------

### Start quick access terminal hidden

Source: https://sw.kovidgoyal.net/kitty/kittens/quick-access-terminal/

Whether to start the quick access terminal hidden. Useful if starting it as part of system startup.

```config
start_as_hidden no
```

--------------------------------

### Install specific kitty version with installer=version-0.35.2

Source: https://sw.kovidgoyal.net/kitty/binary/

Installs a specific kitty version by passing the version identifier to the installer option. Replace the version string with the desired release.

```bash
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin \
    installer=version-0.35.2
```

--------------------------------

### Build kitty documentation locally

Source: https://sw.kovidgoyal.net/kitty/build/

Installs documentation dependencies and builds the kitty documentation for local viewing.

```bash
./dev.sh deps -for-docs && ./dev.sh docs
```

--------------------------------

### Install nightly kitty to custom destination with dest

Source: https://sw.kovidgoyal.net/kitty/binary/

Installs the nightly build to a custom location by specifying the dest option. Useful for parallel installations alongside the released version.

```bash
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin \
    installer=nightly dest=/some/other/location
```

--------------------------------

### goto_layout key mapping example

Source: https://sw.kovidgoyal.net/kitty/actions/

Shows how to bind keys to switch to specific layouts using the goto_layout action. The example maps f1 to the 'tall' layout and f2 to the 'fat' layout with a bias option.

```kitty config
map f1 goto_layout tall
map f2 goto_layout fat:bias=20
```

--------------------------------

### Show build script help

Source: https://sw.kovidgoyal.net/kitty/build/

Displays help for the various options supported by the build script.

```bash
./dev.sh build -h
```

--------------------------------

### Start selecting text in a rectangle

Source: https://sw.kovidgoyal.net/kitty/conf/

Maps ctrl+alt+left press to start a rectangular selection.

```kitty.conf
mouse_map ctrl+alt+left press ungrabbed mouse_selection rectangle
```

--------------------------------

### Map launch with --stdin-source=@screen_scrollback to pass screen contents

Source: https://sw.kovidgoyal.net/kitty/launch/

Maps F1 to launch less, passing the contents of the current screen and scrollback to the started process.

```kitty.conf
map f1 launch --stdin-source=@screen_scrollback less
```

--------------------------------

### STARTED response with transmission_type=rsync

Source: https://sw.kovidgoyal.net/kitty/file-transfer-protocol/

Terminal responds with STARTED and transmission_type=rsync if the file exists and signature data can be sent.

```protocol
← action=status id=someid file_id=f1 status=STARTED transmission_type=rsync
```

--------------------------------

### Install kitty desktop integration with stow

Source: https://sw.kovidgoyal.net/kitty/binary/

Use this command with stow to manage the kitty installation, assuming dest=~/.local/stow.

```shell
cd ~/.local/stow
stow -v kitty.app
```

--------------------------------

### Example: map f1 launch my-program @active-kitty-window-id

Source: https://sw.kovidgoyal.net/kitty/launch/

Example key mapping that uses the @active-kitty-window-id special argument to pass the active window id to a program launched with the launch command.

```kitty config
map f1 launch my-program @active-kitty-window-id
```

--------------------------------

### Map launch with --cwd=current to inherit working directory

Source: https://sw.kovidgoyal.net/kitty/launch/

Maps F1 to launch a new window with the same working directory as the currently active window.

```kitty.conf
map f1 launch --cwd=current
```

--------------------------------

### Start send command

Source: https://sw.kovidgoyal.net/kitty/file-transfer-protocol/

The client initiates a send session by sending a start send command with a session id.

```protocol
→ action=send id=someid
```
Tokens:
Raw