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
@selection
which will be replaced by the current selection.
Options¶
- --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
current
will copy the title from the currently active window.
- --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
current
will copy the title from the title of the currently active tab.
- --type <TYPE>¶
Where to launch the child process:
window
A new kitty window in the current tab
tab
A new tab in the current OS window
os-window
A new operating system window
overlay
An overlay window covering the current active kitty window
overlay-main
An overlay window covering the current active kitty window. Unlike a plain overlay window, this window is considered as a 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.
background
The process will be run in the background, without a kitty window. Note that if
kitten @ launch --allow-remote-control
is specified theKITTY_LISTEN_ON
environment variable will be set to a dedicated socket pair file descriptor that the process can use for remote control.clipboard
,primary
These two are meant to work with
--stdin-source
to copy data to the system clipboard or primary selection.
Default:
window
Choices:background
,clipboard
,os-window
,overlay
,overlay-main
,primary
,tab
,window
- --dont-take-focus, --keep-focus¶
Keep the focus on the currently active window instead of switching to the newly opened window.
- --cwd <CWD>¶
The working directory for the newly launched child. Use the special value
current
to use the working directory of the currently active window. The special valuelast_reported
uses the last working directory reported by the shell (needs Shell integration to work). The special valueoldest
works likecurrent
but uses the working directory of the oldest foreground process associated with the currently active window rather than the newest foreground process. Finally, the special valueroot
refers to the process that was originally started when the window was created.
- --env <ENV>¶
Environment variables to set in the child process. Can be specified multiple times to set different environment variables. Syntax:
name=value
. Usingname=
will set to empty string and justname
will remove the environment variable.
- --var <VAR>¶
User variables to set in the created window. Can be specified multiple times to set different user variables. Syntax:
name=value
. Usingname=
will set to empty string.
- --hold¶
Keep the window open even after the command being executed exits, at a shell prompt.
- --copy-colors¶
Set the colors of the newly created window to be the same as the colors in the currently active window.
- --copy-cmdline¶
Ignore any specified command line and instead use the command line from the currently active window.
- --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 clone-in-kitty feature or the kitty remote control feature with
kitten @ launch --copy-env
.
- --location <LOCATION>¶
Where to place the newly created window when it is added to a tab which already has existing windows in it.
after
andbefore
place the new window before or after the active window.neighbor
is a synonym forafter
. Also applies to creating a new tab, where the value ofafter
will cause the new tab to be placed next to the current tab instead of at the end. The values ofvsplit
,hsplit
andsplit
are only used by thesplits
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:default
Choices:after
,before
,default
,first
,hsplit
,last
,neighbor
,split
,vsplit
- --bias <BIAS>¶
The bias used to alter the size of the window. It controls what fraction of available space the window takes. The exact meaning of bias depends on the current layout.
Splits layout: The bias is interpreted as a percentage between 0 and 100. When splitting a window into two, the new window will take up the specified fraction of the space alloted to the original window and the original window will take up the remainder of the space.
Vertical/horizontal layout: The bias is interpreted as adding/subtracting from the normal size of the window. It should be a number between -90 and 90. This number is the percentage of the OS Window size that should be added to the window size. So for example, if a window would normally have been size 50 in the layout inside an OS Window that is size 80 high and --bias -10 is used it will become approximately size 42 high. Note that sizes are approximations, you cannot use this method to create windows of fixed sizes.
Tall layout: If the window being created is the first window in a column, then the bias is interpreted as a percentage, as for the splits layout, splitting the OS Window width between columns. If the window is a second or subsequent window in a column the bias is interpreted as adding/subtracting from the window size as for the vertical layout above.
Fat layout: Same as tall layout except it goes by rows instead of columns.
Grid layout: The bias is interpreted the same way as for the Vertical and Horizontal layouts, as something to be added/subtracted to the normal size. However, the since in a grid layout there are rows and columns, the bias on the first window in a column operates on the columns. Any later windows in that column operate on the row. So, for example, if you bias the first window in a grid layout it will change the width of the first column, the second window, the width of the second column, the third window, the height of the second row and so on.
The bias option was introduced in kitty version 0.36.0. Default:
0
- --allow-remote-control¶
Programs running in this window can control kitty (even if remote control is not enabled in
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--remote-control-password
for ways to restrict actions allowed by remote control.
- --remote-control-password <REMOTE_CONTROL_PASSWORD>¶
Restrict the actions remote control is allowed to take. This works like
remote_control_password
. You can specify a password and list of actions just as forremote_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
remote_control_password
inkitty.conf
are also in effect. You can override them by using the same password here. You can also disable allremote_control_password
global passwords for this window, by using:--remote-control-password '!'
This option only takes effect if
--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
- --stdin-source <STDIN_SOURCE>¶
Pass the screen contents as
STDIN
to the child process.@selection
is the currently selected text.
@screen
is the contents of the currently active window.
@screen_scrollback
is the same as
@screen
, but includes the scrollback buffer as well.@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.
@first_cmd_output_on_screen
is the output from the first command run in the shell on screen.
@last_cmd_output
is the output from the last command run in the shell.
@last_visited_cmd_output
is the first output below the last scrolled position via
scroll_to_prompt
, this needs shell integration to work.
Default:
none
Choices:@alternate
,@alternate_scrollback
,@first_cmd_output_on_screen
,@last_cmd_output
,@last_visited_cmd_output
,@screen
,@screen_scrollback
,@selection
,none
- --stdin-add-formatting¶
When using
--stdin-source
add formatting escape codes, without this only plain text will be sent.
- --stdin-add-line-wrap-markers¶
When using
--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.
- --marker <MARKER>¶
Create a marker that highlights text in the newly created window. The syntax is the same as for the
toggle_marker
action (see Mark text on screen).
- --os-window-class <OS_WINDOW_CLASS>¶
Set the WM_CLASS property on X11 and the application id property on Wayland for the newly created OS window when using
--type=os-window
. Defaults to whatever is used by the parent kitty process, which in turn defaults tokitty
.
- --os-window-name <OS_WINDOW_NAME>¶
Set the WM_NAME property on X11 for the newly created OS Window when using
--type=os-window
. Defaults to--os-window-class
.
- --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
current
will use the title of the current OS window, if any.
- --os-window-state <OS_WINDOW_STATE>¶
The initial state for the newly created OS Window. Default:
normal
Choices:fullscreen
,maximized
,minimized
,normal
- --logo <LOGO>¶
Path to a PNG image to use as the logo for the newly created window. See
window_logo_path
. Relative paths are resolved from the kitty configuration directory.
- --logo-position <LOGO_POSITION>¶
The position for the window logo. Only takes effect if
--logo
is specified. Seewindow_logo_position
.
- --logo-alpha <LOGO_ALPHA>¶
The amount the window logo should be faded into the background. Only takes effect if
--logo
is specified. Seewindow_logo_alpha
. Default:-1
- --color <COLOR>¶
Change colors in the newly launched window. You can either specify a path to a
.conf
file with the same syntax askitty.conf
to read the colors from, or specify them individually, for example:--color background=white --color foreground=red
- --spacing <SPACING>¶
Set the margin and padding for the newly created window. For example:
margin=20
orpadding-left=10
ormargin-h=30
. The shorthand form sets all values, the*-h
and*-v
variants set horizontal and vertical values. Can be specified multiple times. Note that this is ignored for overlay windows as these use the settings from the base window.
- --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: Watching launched windows. Relative paths are resolved relative to the kitty config directory. Global watchers for all windows can be specified with
watcher
inkitty.conf
.