Controlling kitty from scripts or the shell — kitty 0.11.3 documentation

# 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 --window-layout 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 is 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 dont need to use `allow_remote_control` to make it work.

## 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, 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. 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.

`--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, 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 @ 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. 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.

## 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. 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.

## 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. 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.

`--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 @ 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) and command-line 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. 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, 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

`--new-tab```

  Open a new tab

`--tab-title``<TAB_TITLE>`

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

## 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. 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.

`--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 close 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. 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.

`--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. 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.

`--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, 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. 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.

`--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, 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, 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. 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.