# Controlling kitty from scripts or the shell¶

## Tutorial¶

kitty can be controlled from scripts or the shell prompt. You can open new windows, send arbitrary text input to any window, name windows and tabs, etc. Let’s walk through a few examples of controlling kitty.

Start by running kitty as:

kitty -o allow_remote_control=yes -o enabled_layouts=tall


In order for control to work, allow_remote_control must be enabled in kitty.conf. Here we turn it on explicitly at the command line.

Now, in the new kitty window, enter the command:

kitty @ new-window --title Output --keep-focus cat


This will open a new window, running the cat program that will appear next to the current window.

Let’s send some text to this new window:

kitty @ send-text --match cmdline:cat Hello, World


This will make Hello, World show up in the window running the cat program. The kitty @ send-text --match option is very powerful, it allows selecting windows by their titles, the command line of the program running in the window, the working directory of the program running in the window, etc. See kitty @ send-text --help for details.

More usefully, you can pipe the output of a command running in one window to another window, for example:

ls | kitty @ send-text --match title:Output --stdin


This will show the output of ls in the output window instead of the current window. You can use this technique to, for example, show the output of running make in your editor in a different window. The possibilities are endless.

You can even have things you type show up in a different window. Run:

kitty @ send-text --match title:Output --stdin


And type some text, it will show up in the output window, instead of the current window. Type Ctrl+D when you are ready to stop.

Now, let’s open a new tab:

kitty @ new-window --new-tab --tab-title "My Tab" --keep-focus bash


This will open a new tab running the bash shell with the title “My Tab”. We can change the title of the tab with:

kitty @ set-tab-title --match title:My  New Title


Let’s change the title of the current tab:

kitty @ set-tab-title Master Tab


Now lets switch to the newly opened tab:

kitty @ focus-tab --match title:New


Similarly, to focus the previously opened output window (which will also switch back to the old tab, automatically):

kitty @ focus-window --match title:Output


You can get a listing of available tabs and windows, by running:

kitty @ ls


This outputs a tree of data in JSON format. The top level of the tree is all operating system kitty windows. Each OS window has an id and a list of tabs. Each tab has its own id, a title and a list of windows. Each window has an id, title, current working directory, process id (PID) and command-line of the process running in the window. You can use this information with kitty @ focus-window --match to control individual windows.

As you can see, it is very easy to control kitty using the kitty @ messaging system. This tutorial touches only the surface of what is possible. See kitty @ --help for more details.

Note that in the example’s above, kitty @ messaging works only when run inside a kitty window, not anywhere. But, within a kitty window it even works over SSH. If you want to control kitty from programs/scripts not running inside a kitty window, you have to implement a couple of extra steps. First start kitty as:

kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty


The kitty --listen-on option tells kitty to listen for control messages at the specified path. See kitty --help for details. Now you can control this instance of kitty using the kitty @ --to command line argument to kitty @. For example:

kitty @ --to unix:/tmp/mykitty ls


Note that if all you want to do is run a single kitty “daemon” and have subsequent kitty invocations appear as new top-level windows, you can use the simpler kitty --single-instance option, see kitty --help for that.

## The builtin kitty shell¶

You can explore the kitty command language more easily using the builtin kitty shell. Run kitty @ with no arguments and you will be dropped into the kitty shell with completion for kitty command names and options.

You can even open the kitty shell inside a running kitty using a simple keyboard shortcut (ctrl+shift+escape by default). This has the added advantage that you don’t need to use allow_remote_control to make it work.

## Allowing only some windows to control kitty¶

If you do not want to allow all programs running in kitty to control it, you can selectively enable remote control for only some kitty windows. Simply create a shortcut such as:

map ctrl+k new_window @ some_program


Then programs running in windows created with that shortcut can use kitty @ to control kitty. Note that any program with the right level of permissions can still write to the pipes of any other program on the same computer and therefore can control kitty. It can, however, be useful to block programs running on other computers (for example, over ssh) or as other users.

## kitty @¶

kitty @ [options] command ...


Control kitty by sending it commands. Set the allow_remote_control option to yes in kitty.conf for this to work.

### Options¶

--to <TO>

An address for the kitty instance to control. Corresponds to the address given to the kitty instance via the kitty --listen-on option. If not specified, messages are sent to the controlling terminal for this process, i.e. they will only work if this process is run within an existing kitty window.

## kitty @ close-tab¶

kitty @ close-tab [options]


Close the specified tab(s)

### Options¶

--match <MATCH>, -m <MATCH>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

--self

If specified close the tab this command is run in, rather than the active tab.

## kitty @ close-window¶

kitty @ close-window [options]


Close the specified window(s)

### Options¶

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

--self

If specified close the window this command is run in, rather than the active window.

## kitty @ focus-tab¶

kitty @ focus-tab [options]


The active window in the specified tab will be focused.

### Options¶

--match <MATCH>, -m <MATCH>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

--no-response

Don’t wait for a response indicating the success of the action. Note that using this option means that you will not be notified of failures. Default: false

## kitty @ focus-window¶

kitty @ focus-window [options]


Focus the specified window, if no window is specified, focus the window this command is run inside.

### Options¶

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

--no-response

Don’t wait for a response from kitty. This means that even if no matching window is found, the command will exit with a success code. Default: false

## kitty @ get-colors¶

kitty @ get-colors [options] ...


Get the terminal colors for the specified window (defaults to active window). Colors will be output to stdout in the same syntax as used for kitty.conf

### Options¶

--configured, -c

Instead of outputting the colors for the specified window, output the currently configured colors.

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

## kitty @ get-text¶

kitty @ get-text [options]


Get text from the specified window

### Options¶

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

--extent <EXTENT>

What text to get. The default of screen means all text currently on the screen. all means all the screen+scrollback and selection means currently selected text. Default: screen Choices: all, screen, selection

--ansi

By default, only plain text is returned. If you specify this flag, the text will include the formatting escape codes for colors/bold/italic/etc. Note that when getting the current selection, the result is always plain text.

--self

If specified get text from the window this command is run in, rather than the active window.

## kitty @ goto-layout¶

kitty @ goto-layout [options] LAYOUT_NAME


Set the window layout in the specified tab (or the active tab if not specified). You can use special match value all to set the layout in all tabs.

### Options¶

--match <MATCH>, -m <MATCH>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

## kitty @ kitten¶

kitty @ kitten [options] kitten_name


Run a kitten over the specified window (active window by default). The kitten_name can be either the name of a builtin kitten or the path to a python file containing a custom kitten. If a relative path is used it is searched for in the kitty config directory.

### Options¶

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

## kitty @ last-used-layout¶

kitty @ last-used-layout [options] ...


Switch to the last used window layout in the specified tab (or the active tab if not specified). You can use special match value all to set the layout in all tabs.

### Options¶

--match <MATCH>, -m <MATCH>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

## kitty @ ls¶

kitty @ ls


List all windows. The list is returned as JSON tree. The top-level is a list of operating system kitty windows. Each OS window has an id and a list of tabs. Each tab has its own id, a title and a list of windows. Each window has an id, title, current working directory, process id (PID), command-line and environment of the process running in the window.

You can use these criteria to select windows/tabs for the other commands.

## kitty @ new-window¶

kitty @ new-window [options] [CMD ...]


Open a new window in the specified tab. If you use the kitty @ new-window --match option the first matching tab is used. Otherwise the currently active tab is used. Prints out the id of the newly opened window (unless --no-response is used). Any command line arguments are assumed to be the command line used to run in the new window, if none are provided, the default shell is run. For example: kitty @ new-window –title Email mutt

### Options¶

--match <MATCH>, -m <MATCH>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

--title <TITLE>

The title for the new window. By default it will use the title set by the program running in it.

--cwd <CWD>

The initial working directory for the new window.

--keep-focus

Keep the current window focused instead of switching to the newly opened window

--window-type <WINDOW_TYPE>

What kind of window to open. A kitty window or a top-level OS window. Default: kitty Choices: kitty, os

--new-tab

Open a new tab

--tab-title <TAB_TITLE>

When using –new-tab set the title of the tab.

--no-response

Don’t wait for a response giving the id of the newly opened window. Note that using this option means that you will not be notified of failures and that the id of the new window will not be printed out. Default: false

## kitty @ resize-window¶

kitty @ resize-window [options]


Resize the specified window in the current layout. Note that not all layouts can resize all windows in all directions.

### Options¶

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

--increment <INCREMENT>, -i <INCREMENT>

The number of cells to change the size by, can be negative to decrease the size. Default: 2

--axis <AXIS>, -a <AXIS>

The axis along which to resize. If horizontal, it will make the window wider or narrower by the specified increment. If vertical, it will make the window taller or shorter by the specified increment. The special value reset will reset the layout to its default configuration. Default: horizontal Choices: horizontal, reset, vertical

--self

If specified resize the window this command is run in, rather than the active window.

## kitty @ send-text¶

kitty @ send-text [options] [TEXT TO SEND]


Send arbitrary text to specified windows. The text follows Python escaping rules. So you can use escapes like x1b to send control codes and u21fa to send unicode characters. If you use the kitty @ send-text --match option the text will be sent to all matched windows. By default, text is sent to only the currently active window.

### Options¶

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

--stdin

Read the text to be sent from stdin. Note that in this case the text is sent as is, not interpreted for escapes. If stdin is a terminal, you can press Ctrl-D to end reading.

--from-file <FROM_FILE>

Path to a file whose contents you wish to send. Note that in this case the file contents are sent as is, not interpreted for escapes.

## kitty @ set-background-opacity¶

kitty @ set-background-opacity [options] OPACITY


Set the background opacity for the specified windows. This will only work if you have turned on dynamic_background_opacity in kitty.conf. The background opacity affects all kitty windows in a single os_window. For example: kitty @ set-background-opacity 0.5

### Options¶

--all, -a

By default, colors are only changed for the currently active window. This option will cause colors to be changed in all windows.

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

--match-tab <MATCH_TAB>, -t <MATCH_TAB>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

## kitty @ set-colors¶

kitty @ set-colors [options] COLOR_OR_FILE ...


Set the terminal colors for the specified windows/tabs (defaults to active window). You can either specify the path to a conf file (in the same format as kitty.conf) to read the colors from or you can specify individual colors, for example: kitty @ set-colors foreground=red background=white

### Options¶

--all, -a

By default, colors are only changed for the currently active window. This option will cause colors to be changed in all windows.

--configured, -c

Also change the configured colors (i.e. the colors kitty will use for new windows or after a reset).

--reset

Restore all colors to the values they had at kitty startup. Note that if you specify this option, any color arguments are ignored and –configured and –all are implied.

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2

--match-tab <MATCH_TAB>, -t <MATCH_TAB>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

## kitty @ set-font-size¶

kitty @ set-font-size FONT_SIZE


Sets the font size to the specified size, in pts.

## kitty @ set-tab-title¶

kitty @ set-tab-title [options] TITLE ...


Set the title for the specified tab(s). If you use the kitty @ set-tab-title --match option the title will be set for all matched tabs. By default, only the tab in which the command is run is affected. If you do not specify a title, the title of the currently active window in the tab is used.

### Options¶

--match <MATCH>, -m <MATCH>

The tab to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the ls command to get a list of tabs. Note that for numeric fields such as id and pid the expression is interpreted as a number, not a regular expression. When using title or id, first a matching tab is looked for and if not found a matching window is looked for, and the tab for that window is used.

## kitty @ set-window-title¶

kitty @ set-window-title [options] TITLE ...


Set the title for the specified window(s). If you use the kitty @ set-window-title --match option the title will be set for all matched windows. By default, only the window in which the command is run is affected. If you do not specify a title, the last title set by the child process running in the window will be used.

### Options¶

--temporary

By default, if you use set-window-title the title will be permanently changed and programs running in the window will not be able to change it again. If you want to allow other programs to change it afterwards, use this option.

--match <MATCH>, -m <MATCH>

The window to match. Match specifications are of the form: field:regexp. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the ls command to get a list of windows. Note that for numeric fields such as id, pid and num the expression is interpreted as a number, not a regular expression. The field num refers to the window position in the current tab, starting from zero and counting clockwise (this is the same as the order in which the windows are reported by the ls command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the env field to match on environment variables you can specify only the environment variable name or a name and value, for example, env:MY_ENV_VAR=2