.. highlight:: sh
.. code-block:: sh
launch [options] [program-to-run ...]
Launch an arbitrary program in a new kitty window/tab. Note that
if you specify a program-to-run you can use the special placeholder
:code:`@selection` which will be replaced by the current selection.
Options
______________________________
.. option:: --title <WINDOW_TITLE>, --window-title <WINDOW_TITLE>
The title to set for the new window. By default, title is controlled by the child process. The special value :code:`current` will copy the title from the currently active window.
.. option:: --tab-title <TAB_TITLE>
The title for the new tab if launching in a new tab. By default, the title of the active window in the tab is used as the tab title. The special value :code:`current` will copy the title from the title of the currently active tab.
.. option:: --type <TYPE>
Where to launch the child process:
:code:`window`
A new :term:`kitty window <window>` in the current tab
:code:`tab`
A new :term:`tab` in the current OS window
:code:`os-window <os_window>`
A new :term:`operating system window <os_window>`
:code:`overlay`
An :term:`overlay window <overlay>` covering the current active kitty window
:code:`overlay-main`
An :term:`overlay window <overlay>` covering the current active kitty window. Unlike a plain overlay window, this window is considered as a :italic:`main` window which means it is used as the active window for getting the current working directory, the input text for kittens, launch commands, etc. Useful if this overlay is intended to run for a long time as a primary window.
:code:`background`
The process will be run in the :italic:`background`, without a kitty window.
:code:`clipboard`, :code:`primary`
These two are meant to work with :option:`--stdin-source <launch --stdin-source>` to copy data to the :italic:`system clipboard` or :italic:`primary selection`.
Default: :code:`window`
Choices: :code:`background`, :code:`clipboard`, :code:`os-window`, :code:`overlay`, :code:`overlay-main`, :code:`primary`, :code:`tab`, :code:`window`
.. option:: --dont-take-focus, --keep-focus
Keep the focus on the currently active window instead of switching to the newly opened window.
.. option:: --cwd <CWD>
The working directory for the newly launched child. Use the special value :code:`current` to use the working directory of the currently active window. The special value :code:`last_reported` uses the last working directory reported by the shell (needs :ref:`shell_integration` to work). The special value :code:`oldest` works like :code:`current` but uses the working directory of the oldest foreground process associated with the currently active window rather than the newest foreground process.
.. option:: --env <ENV>
Environment variables to set in the child process. Can be specified multiple times to set different environment variables. Syntax: :code:`name=value`. Using :code:`name=` will set to empty string and just :code:`name` will remove the environment variable.
.. option:: --hold
Keep the window open even after the command being executed exits.
.. option:: --copy-colors
Set the colors of the newly created window to be the same as the colors in the currently active window.
.. option:: --copy-cmdline
Ignore any specified command line and instead use the command line from the currently active window.
.. option:: --copy-env
Copy the environment variables from the currently active window into the newly launched child process. Note that this only copies the environment when the window was first created, as it is not possible to get updated environment variables from arbitrary processes. To copy that environment, use either the :ref:`clone-in-kitty <clone_shell>` feature or the kitty remote control feature with :option:`kitty @ launch --copy-env`.
.. option:: --location <LOCATION>
Where to place the newly created window when it is added to a tab which already has existing windows in it. :code:`after` and :code:`before` place the new window before or after the active window. :code:`neighbor` is a synonym for :code:`after`. Also applies to creating a new tab, where the value of :code:`after` will cause the new tab to be placed next to the current tab instead of at the end. The values of :code:`vsplit`, :code:`hsplit` and :code:`split` are only used by the :code:`splits` layout and control if the new window is placed in a vertical, horizontal or automatic split with the currently active window. The default is to place the window in a layout dependent manner, typically, after the currently active window.
Default: :code:`default`
Choices: :code:`after`, :code:`before`, :code:`default`, :code:`first`, :code:`hsplit`, :code:`last`, :code:`neighbor`, :code:`split`, :code:`vsplit`
.. option:: --allow-remote-control
Programs running in this window can control kitty (even if remote control is not enabled in :file:`kitty.conf`). 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 other computers (for example, over SSH) or as other users. See :option:`--remote-control-password` for ways to restrict actions allowed by remote control.
.. option:: --remote-control-password <REMOTE_CONTROL_PASSWORD>
Restrict the actions remote control is allowed to take. This works like :opt:`remote_control_password`. You can specify a password and list of actions just as for :opt:`remote_control_password`. For example::
--remote-control-password '"my passphrase" get-* set-colors'
This password will be in effect for this window only. Note that any passwords you have defined for :opt:`remote_control_password` in :file:`kitty.conf` are also in effect. You can override them by using the same password here. You can also disable all :opt:`remote_control_password` global passwords for this window, by using::
--remote-control-password '!'
This option only takes effect if :option:`--allow-remote-control` is also specified. Can be specified multiple times to create multiple passwords. This option was added to kitty in version 0.26.0
.. option:: --stdin-source <STDIN_SOURCE>
Pass the screen contents as :file:`STDIN` to the child process.
:code:`@selection`
is the currently selected text.
:code:`@screen`
is the contents of the currently active window.
:code:`@screen_scrollback`
is the same as :code:`@screen`, but includes the scrollback buffer as well.
:code:`@alternate`
is the secondary screen of the current active window. For example if you run a full screen terminal application, the secondary screen will be the screen you return to when quitting the application.
:code:`@first_cmd_output_on_screen`
is the output from the first command run in the shell on screen.
:code:`@last_cmd_output`
is the output from the last command run in the shell.
:code:`@last_visited_cmd_output`
is the first output below the last scrolled position via :ac:`scroll_to_prompt`, this needs :ref:`shell integration <shell_integration>` to work.
Default: :code:`none`
Choices: :code:`@alternate`, :code:`@alternate_scrollback`, :code:`@first_cmd_output_on_screen`, :code:`@last_cmd_output`, :code:`@last_visited_cmd_output`, :code:`@screen`, :code:`@screen_scrollback`, :code:`@selection`, :code:`none`
.. option:: --stdin-add-formatting
When using :option:`--stdin-source <launch --stdin-source>` add formatting escape codes, without this only plain text will be sent.
.. option:: --stdin-add-line-wrap-markers
When using :option:`--stdin-source <launch --stdin-source>` add a carriage return at every line wrap location (where long lines are wrapped at screen edges). This is useful if you want to pipe to program that wants to duplicate the screen layout of the screen.
.. option:: --marker <MARKER>
Create a marker that highlights text in the newly created window. The syntax is the same as for the :ac:`toggle_marker` action (see :doc:`/marks`).
.. option:: --os-window-class <OS_WINDOW_CLASS>
Set the :italic:`WM_CLASS` property on X11 and the application id property on Wayland for the newly created OS window when using :option:`--type=os-window <launch --type>`. Defaults to whatever is used by the parent kitty process, which in turn defaults to :code:`kitty`.
.. option:: --os-window-name <OS_WINDOW_NAME>
Set the :italic:`WM_NAME` property on X11 for the newly created OS Window when using :option:`--type=os-window <launch --type>`. Defaults to :option:`--os-window-class <launch --os-window-class>`.
.. option:: --os-window-title <OS_WINDOW_TITLE>
Set the title for the newly created OS window. This title will override any titles set by programs running in kitty. The special value :code:`current` will use the title of the current OS window, if any.
.. option:: --logo <LOGO>
Path to a PNG image to use as the logo for the newly created window. See :opt:`window_logo_path`. Relative paths are resolved from the kitty configuration directory.
.. option:: --logo-position <LOGO_POSITION>
The position for the window logo. Only takes effect if :option:`--logo` is specified. See :opt:`window_logo_position`.
.. option:: --logo-alpha <LOGO_ALPHA>
The amount the window logo should be faded into the background. Only takes effect if :option:`--logo` is specified. See :opt:`window_logo_alpha`.
Default: :code:`-1`
.. option:: --color <COLOR>
Change colors in the newly launched window. You can either specify a path to a :file:`.conf` file with the same syntax as :file:`kitty.conf` to read the colors from, or specify them individually, for example::
--color background=white --color foreground=red
.. option:: --spacing <SPACING>
Set the margin and padding for the newly created window. For example: :code:`margin=20` or :code:`padding-left=10` or :code:`margin-h=30`. The shorthand form sets all values, the :code:`*-h` and :code:`*-v` variants set horizontal and vertical values. Can be specified multiple times.
.. 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: :ref:`watchers`. Relative paths are resolved relative to the :ref:`kitty config directory <confloc>`. Global watchers for all windows can be specified with :opt:`watcher` in :file:`kitty.conf`.
Generated by dwww version 1.15 on Thu May 23 05:46:27 CEST 2024.