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

  kitty [options] [program-to-run ...]

Run the :italic:`kitty` terminal emulator. You can also specify the :italic:`program`
to run inside :italic:`kitty` as normal arguments following the :italic:`options`.
For example: kitty sh -c "echo hello, world. Press ENTER to quit; read"

For comprehensive documentation for kitty, please see: https://sw.kovidgoyal.net/kitty/

Options
------------------------------
.. option:: --class <CLS>

    Set the class part of the :italic:`WM_CLASS` window property. On Wayland, it sets the app id.
    Default: :code:`kitty`

.. option:: --name <NAME>

    Set the name part of the :italic:`WM_CLASS` property (defaults to using the value from :option:`kitty --class`)

.. option:: --title <TITLE>, -T <TITLE>

    Set the window title. This will override any title set by the program running inside kitty. So only use this if you are running a program that does not set titles. If combined with :option:`kitty --session` the title will be used for all windows created by the session, that do not set their own titles.

.. option:: --config <CONFIG>, -c <CONFIG>

    Specify a path to the configuration file(s) to use. All configuration files are merged onto the builtin kitty.conf, overriding the builtin values. This option can be specified multiple times to read multiple configuration files in sequence, which are merged. Use the special value NONE to not load a config file.

    If this option is not specified, config files are searched for in the order: :file:`$XDG_CONFIG_HOME/kitty/kitty.conf`, :file:`~/.config/kitty/kitty.conf`, :file:`$XDG_CONFIG_DIRS/kitty/kitty.conf`. The first one that exists is used as the config file.

    If the environment variable :env:`KITTY_CONFIG_DIRECTORY` is specified, that directory is always used and the above searching does not happen.

    If :file:`/etc/xdg/kitty/kitty.conf` exists it is merged before (i.e. with lower priority) than any user config files. It can be used to specify system-wide defaults for all users.

.. option:: --override <OVERRIDE>, -o <OVERRIDE>

    Override individual configuration options, can be specified multiple times. Syntax: :italic:`name=value`. For example: :option:`kitty -o` font_size=20

.. option:: --directory <DIRECTORY>, -d <DIRECTORY>

    Change to the specified directory when launching
    Default: :code:`.`

.. option:: --detach

    Detach from the controlling terminal, if any

.. option:: --session <SESSION>

    Path to a file containing the startup :italic:`session` (tabs, windows, layout, programs). Use - to read from STDIN. See the README file for details and an example.

.. option:: --watcher <WATCHER>, -w <WATCHER>

    Path to a python file. Appropriately named functions in this file will be called for various events, such as when the window is resized, focused or closed. See the section on watchers in the launch command documentation :doc:`launch`. Relative paths are resolved relative to the kitty config directory. Note that this watcher will be added only to all initially created windows, not new windows created after startup.

.. option:: --hold

    Remain open after child process exits. Note that this only affects the first window. You can quit by either using the close window shortcut or :kbd:`Ctrl+d`.

.. option:: --single-instance, -1

    If specified only a single instance of :italic:`kitty` will run. New invocations will instead create a new top-level window in the existing :italic:`kitty` instance. This allows :italic:`kitty` to share a single sprite cache on the GPU and also reduces startup time. You can also have separate groups of :italic:`kitty` instances by using the :option:`kitty --instance-group` option

.. option:: --instance-group <INSTANCE_GROUP>

    Used in combination with the :option:`kitty --single-instance` option. All :italic:`kitty` invocations with the same :option:`kitty --instance-group` will result in new windows being created in the first :italic:`kitty` instance within that group

.. option:: --wait-for-single-instance-window-close

    Normally, when using :option:`--single-instance`, :italic:`kitty` will open a new window in an existing instance and quit immediately. With this option, it will not quit till the newly opened window is closed. Note that if no previous instance is found, then :italic:`kitty` will wait anyway, regardless of this option.

.. option:: --listen-on <LISTEN_ON>

    Tell kitty to listen on the specified address for control messages. For example, :option:`kitty --listen-on`:code:`=unix:/tmp/mykitty` or :option:`kitty --listen-on`:code:`=tcp:localhost:12345`. On Linux systems, you can also use abstract UNIX sockets, not associated with a file, like this: :option:`kitty --listen-on`:code:`=unix:@mykitty`. Environment variables in the setting are expanded and relative paths are resolved with respect to the temporary directory. To control kitty, you can send it commands with :italic:`kitty @` using the :option:`kitty @ --to` option to specify this address. This option will be ignored, unless you set :opt:`allow_remote_control` to yes in :file:`kitty.conf`. Note that if you run :italic:`kitty @` within a kitty window, there is no need to specify the :italic:`--to` option as it is read automatically from the environment. For UNIX sockets, this can also be specified in :file:`kitty.conf`.

.. option:: --start-as <START_AS>

    Control how the initial kitty window is created.
    Default: :code:`normal`
    Choices: :code:`fullscreen, maximized, minimized, normal`

Debugging options
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. option:: --version, -v

    The current kitty version

.. option:: --dump-commands

    Output commands received from child process to stdout

.. option:: --replay-commands <REPLAY_COMMANDS>

    Replay previously dumped commands. Specify the path to a dump file previously created by --dump-commands. You can open a new kitty window to replay the commands with::

        kitty sh -c "kitty --replay-commands /path/to/dump/file; read"

.. option:: --dump-bytes <DUMP_BYTES>

    Path to file in which to store the raw bytes received from the child process

.. option:: --debug-gl, --debug-rendering

    Debug rendering commands. This will cause all OpenGL calls to check for errors instead of ignoring them. Also prints out miscellaneous debug information. Useful when debugging rendering problems

.. option:: --debug-keyboard

    This option will cause kitty to print out key events as they are received

.. option:: --debug-font-fallback

    Print out information about the selection of fallback fonts for characters not present in the main font.

.. option:: --debug-config

    Print out information about the system and kitty configuration.
