From 102823809b72b3f6a3fb77a52f5016094dcf303b Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 10 Jan 2018 12:54:21 +0530 Subject: [PATCH] Add a tutorial for controlling kitty from scripts --- README.asciidoc | 9 ++++++ remote-control.asciidoc | 62 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 remote-control.asciidoc diff --git a/README.asciidoc b/README.asciidoc index dd1ac54c6..aed3b899c 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -231,6 +231,15 @@ windows are: |=== +== Controlling kitty from scripts + +You can control kitty from the command line/scripts by sending it messages. +You can tell kitty to open/close/rename tabs and windows. You can even send +arbitrary input/text to any specified window. Messages can be sent using +```kitty @```. Note that you must set `allow_remote_control yes` in your +kitty.conf to use this feature. It even works over SSH connections. This +feature is best illustrated with a link:remote-control.asciidoc[tutorial]. + == The scrollback buffer diff --git a/remote-control.asciidoc b/remote-control.asciidoc new file mode 100644 index 000000000..c7913b3d1 --- /dev/null +++ b/remote-control.asciidoc @@ -0,0 +1,62 @@ += Controlling kitty from scripts or the shell + +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 `--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 + +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.