kitty @
--------------------------------------------------------------------------------
.. program:: kitty @


.. highlight:: sh
.. code-block:: sh

  kitty @ [options] command ...

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

Options
______________________________
.. option:: --to <TO>

    An address for the kitty instance to control. Corresponds to the address given to the kitty instance via the :option:`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.

.. _at_close-tab:

kitty @ close-tab
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ close-tab


.. highlight:: sh
.. code-block:: sh

  kitty @ close-tab [options] 

Close the specified tab(s)

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. option:: --self

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

.. _at_close-window:

kitty @ close-window
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ close-window


.. highlight:: sh
.. code-block:: sh

  kitty @ close-window [options] 

Close the specified window(s)

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. option:: --self

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

.. _at_focus-tab:

kitty @ focus-tab
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ focus-tab


.. highlight:: sh
.. code-block:: sh

  kitty @ focus-tab [options] 

The active window in the specified tab will be focused.

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. option:: --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: :code:`false`

.. _at_focus-window:

kitty @ focus-window
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ focus-window


.. highlight:: sh
.. code-block:: sh

  kitty @ focus-window [options] 

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

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. option:: --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: :code:`false`

.. _at_get-colors:

kitty @ get-colors
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ get-colors


.. highlight:: sh
.. code-block:: sh

  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
______________________________
.. option:: --configured, -c

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

.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. _at_get-text:

kitty @ get-text
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ get-text


.. highlight:: sh
.. code-block:: sh

  kitty @ get-text [options] 

Get text from the specified window

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. option:: --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: :code:`screen`
    Choices: :code:`all, screen, selection`

.. option:: --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.

.. option:: --self

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

.. _at_goto-layout:

kitty @ goto-layout
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ goto-layout


.. highlight:: sh
.. code-block:: sh

  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 :italic:`all` to set the layout in all tabs.

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. _at_kitten:

kitty @ kitten
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ kitten


.. highlight:: sh
.. code-block:: sh

  kitty @ kitten [options] kitten_name

Run a kitten over the specified window (active window by default). The :italic:`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
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. _at_last-used-layout:

kitty @ last-used-layout
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ last-used-layout


.. highlight:: sh
.. code-block:: sh

  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 :italic:`all` to set the layout in all tabs.

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. _at_ls:

kitty @ ls
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ ls


.. highlight:: sh
.. code-block:: sh

  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 :italic:`id` and a list of :italic:`tabs`. Each tab has its own :italic:`id`, a :italic:`title` and a list of :italic:`windows`. Each window has an :italic:`id`, :italic:`title`, :italic:`current working directory`, :italic:`process id (PID)`,  :italic:`command-line` and :italic:`environment` of the process running in the window.

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

.. _at_new-window:

kitty @ new-window
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ new-window


.. highlight:: sh
.. code-block:: sh

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

Open a new window in the specified tab. If you use the :option:`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 :option:`--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:
:italic:`kitty @ new-window --title Email mutt`

Options
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. option:: --title <TITLE>

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

.. option:: --cwd <CWD>

    The initial working directory for the new window.

.. option:: --keep-focus

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

.. option:: --window-type <WINDOW_TYPE>

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

.. option:: --new-tab

    Open a new tab

.. option:: --tab-title <TAB_TITLE>

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

.. option:: --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: :code:`false`

.. _at_resize-window:

kitty @ resize-window
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ resize-window


.. highlight:: sh
.. code-block:: sh

  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
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. option:: --increment <INCREMENT>, -i <INCREMENT>

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

.. option:: --axis <AXIS>, -a <AXIS>

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

.. option:: --self

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

.. _at_send-text:

kitty @ send-text
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ send-text


.. highlight:: sh
.. code-block:: sh

  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 :italic:`\x1b` to send control codes and :italic:`\u21fa` to send unicode characters. If you use the :option:`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
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. option:: --stdin

    Read the text to be sent from :italic:`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.

.. option:: --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.

.. _at_set-background-opacity:

kitty @ set-background-opacity
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ set-background-opacity


.. highlight:: sh
.. code-block:: sh

  kitty @ set-background-opacity [options] OPACITY

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

Options
______________________________
.. option:: --all, -a

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

.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. option:: --match-tab <MATCH_TAB>, -t <MATCH_TAB>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. _at_set-colors:

kitty @ set-colors
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ set-colors


.. highlight:: sh
.. code-block:: sh

  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
______________________________
.. option:: --all, -a

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

.. option:: --configured, -c

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

.. option:: --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.

.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

.. option:: --match-tab <MATCH_TAB>, -t <MATCH_TAB>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. _at_set-font-size:

kitty @ set-font-size
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ set-font-size


.. highlight:: sh
.. code-block:: sh

  kitty @ set-font-size FONT_SIZE

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

.. _at_set-tab-title:

kitty @ set-tab-title
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ set-tab-title


.. highlight:: sh
.. code-block:: sh

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

Set the title for the specified tab(s). If you use the :option:`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
______________________________
.. option:: --match <MATCH>, -m <MATCH>

    The tab to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, env, cmdline. You can use the :italic:`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.

.. _at_set-window-title:

kitty @ set-window-title
------------------------------------------------------------------------------------------------------------------------
.. program:: kitty @ set-window-title


.. highlight:: sh
.. code-block:: sh

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

Set the title for the specified window(s). If you use the :option:`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
______________________________
.. option:: --temporary

    By default, if you use :italic:`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.

.. option:: --match <MATCH>, -m <MATCH>

    The window to match. Match specifications are of the form: :italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num, env. You can use the :italic:`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 :italic:`ls` command). The window id of the current window is available as the KITTY_WINDOW_ID environment variable. When using the :italic:`env` field to match on environment variables you can specify only the environment variable name or a name and value, for example, :italic:`env:MY_ENV_VAR=2`

