diff --git a/docs/remote-control.rst b/docs/remote-control.rst index 69db6377f..a6896d0bf 100644 --- a/docs/remote-control.rst +++ b/docs/remote-control.rst @@ -23,25 +23,25 @@ turn it on explicitly at the command line. Now, in the new |kitty| window, enter the command:: - kitty @ launch --title Output --keep-focus cat + kitten @ launch --title Output --keep-focus cat This will open a new window, running the :program:`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 + kitten @ send-text --match cmdline:cat Hello, World This will make ``Hello, World`` show up in the window running the :program:`cat` -program. The :option:`kitty @ send-text --match` option is very powerful, it +program. The :option:`kitten @ 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 :ref:`kitty @ send-text --help ` for details. +window, etc. See :ref:`kitten @ 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 + ls | kitten @ send-text --match 'title:^Output' --stdin This will show the output of :program:`ls` in the output window instead of the current window. You can use this technique to, for example, show the output of @@ -50,56 +50,55 @@ are endless. You can even have things you type show up in a different window. Run:: - kitty @ send-text --match 'title:^Output' --stdin + kitten @ send-text --match 'title:^Output' --stdin And type some text, it will show up in the output window, instead of the current window. Type :kbd:`Ctrl+D` when you are ready to stop. Now, let's open a new tab:: - kitty @ launch --type=tab --tab-title "My Tab" --keep-focus bash + kitten @ launch --type=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 to "New Title" with:: - kitty @ set-tab-title --match 'title:^My' New Title + kitten @ set-tab-title --match 'title:^My' New Title Let's change the title of the current tab:: - kitty @ set-tab-title Master Tab + kitten @ set-tab-title Master Tab Now lets switch to the newly opened tab:: - kitty @ focus-tab --match 'title:^New' + kitten @ 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' + kitten @ focus-window --match 'title:^Output' You can get a listing of available tabs and windows, by running:: - kitty @ ls + kitten @ ls This outputs a tree of data in JSON format. The top level of the tree is all :term:`OS windows `. Each OS window has an id and a list of :term:`tabs `. Each tab has its own id, a title and a list of :term:`kitty 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 :option:`kitty @ focus-window --match` to control +use this information with :option:`kitten @ focus-window --match` to control individual windows. -As you can see, it is very easy to control |kitty| using the ``kitty @`` +As you can see, it is very easy to control |kitty| using the ``kitten @`` messaging system. This tutorial touches only the surface of what is possible. -See ``kitty @ --help`` for more details. +See ``kitten @ --help`` for more details. -In the example's above, ``kitty @`` messaging works only when run +In the example's above, ``kitten @`` 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, see the section on :ref:`using a socket for remote control ` below. - 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 :option:`kitty --single-instance` option, see ``kitty --help`` for that. @@ -115,23 +114,23 @@ First, start |kitty| as:: The :option:`kitty --listen-on` option tells |kitty| to listen for control messages at the specified UNIX-domain socket. See ``kitty --help`` for details. -Now you can control this instance of |kitty| using the :option:`kitty @ --to` -command line argument to ``kitty @``. For example:: +Now you can control this instance of |kitty| using the :option:`kitten @ --to` +command line argument to ``kitten @``. For example:: - kitty @ --to unix:/tmp/mykitty ls + kitten @ --to unix:/tmp/mykitty ls 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 +|kitty| shell. Run ``kitten @`` 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 (:sc:`kitty_shell` by default). -.. note:: This has the added advantage that you don't need to use +.. note:: Using the keyboard shortcut has the added advantage that you don't need to use :opt:`allow_remote_control` to make it work. @@ -144,7 +143,7 @@ create a shortcut such as:: map ctrl+k launch --allow-remote-control some_program -Then programs running in windows created with that shortcut can use ``kitty @`` +Then programs running in windows created with that shortcut can use ``kitten @`` 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 @@ -156,7 +155,7 @@ other computers (for example, over SSH) or as other users. kitty, as if you were running with :opt:`allow_remote_control` turned on. You can further restrict what is allowed in these windows by using - :option:`kitty @ launch --remote-control-password`. + :option:`kitten @ launch --remote-control-password`. Fine grained permissions for remote control @@ -181,19 +180,19 @@ Let's see some examples: Now, using this password, you can, in scripts run the command:: - kitty @ --password="control colors" set-colors background=red + kitten @ --password="control colors" set-colors background=red Any script with access to the password can now change colors in kitty using remote control, but only that and nothing else. You can even supply the password via the :envvar:`KITTY_RC_PASSWORD` environment variable, or the file :file:`~/.config/kitty/rc-password` to avoid having to type it repeatedly. -See :option:`kitty @ --password-file` and :option:`kitty @ --password-env`. +See :option:`kitten @ --password-file` and :option:`kitten @ --password-env`. The :opt:`remote_control_password` can be specified multiple times to create different passwords with different capabilities. Run the following to get a list of all action names:: - kitty @ --help + kitten @ --help You can even use glob patterns to match action names, for example: @@ -203,7 +202,7 @@ You can even use glob patterns to match action names, for example: If no action names are specified, all actions are allowed. -If ``kitty @`` is run with a password that is not present in +If ``kitten @`` is run with a password that is not present in :file:`kitty.conf`, then kitty will interactively prompt the user to allow or disallow the remote control request. The user can choose to allow or disallow either just that request or all requests using that password. The user's @@ -216,7 +215,7 @@ decision is remembered for the duration of that kitty instance. using a password, :ref:`rc_crypto` is used to ensure the password is kept secure. This does mean that using password based authentication is slower as the entire command is encrypted before transmission. This - can be noticeable when using a command like ``kitty @ set-background-image`` + can be noticeable when using a command like ``kitten @ set-background-image`` which transmits large amounts of image data. Also, the clock on the remote system must match (within a few minutes) the clock on the local system. kitty uses a time based nonce to minimise the potential for replay attacks. @@ -274,7 +273,7 @@ you can map it in :file:`kitty.conf`. For example:: Then pressing the :kbd:`F1` key will set the active window margins to :code:`30`. The syntax for what follows :ac:`remote_control` is exactly the same -as the syntax for what follows :code:`kitty @` above. +as the syntax for what follows :code:`kitten @` above. If you wish to ignore errors from the command, prefix the command with an ``!``. For example, the following will not return an error when no windows