- --match,
-m
- The tab to match. Match specifications are of the form: field:query. Where
field can be one of: id, index, title, window_id, window_title, pid, cwd,
cmdline env, var, state and recent. query is the expression to match.
Expressions can be either a number or a regular expression, and can be
combined using Boolean operators.
The special value all matches all tabs.
For numeric fields: id, index, window_id, pid and recent, the
expression is interpreted as a number, not a regular expression.
Negative values for id/window_id match from the highest id number down,
in particular, -1 is the most recently created tab/window.
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.
You can also use window_id and window_title to match the tab
that contains the window with the specified id or title.
The index number is used to match the nth tab in the currently
active OS window. The recent number matches recently active tabs in the
currently active OS window, with zero being the currently active tab,
one the previously active tab and so on.
When using the env field to match on environment variables,
you can specify only the environment variable name or a name and value,
for example, env:MY_ENV_VAR=2. Tabs containing any window with the
specified environment variables are matched. Similarly, var matches tabs
containing any window with the specified user variable.
The field state matches on the state of the tab. Supported
states are: active, focused, needs_attention, parent_active and
parent_focused. Active tabs are the tabs that are active in their parent
OS window. There is only one focused tab and it is the tab to which
keyboard events are delivered. If no tab is focused, the last focused
tab is matched.
Note that you can use the kitten @ ls command to get a list of
tabs.
- --no-response
- Do not print out the id of the newly created window.
- --self
- If specified the tab containing the window this command is run in is used
instead of the active tab
- --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
- 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
[=window]
- 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 --allow-remote-control is specified the
KITTY_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.
Choices: window, background, clipboard, os-window, overlay,
overlay-main, primary, tab
- --dont-take-focus,
--keep-focus
- Keep the focus on the currently active window instead of switching to the
newly opened window.
- --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 value last_reported uses the last working directory reported by
the shell (needs shell_integration to work). The special value oldest
works like current 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 value root refers to the process
that was originally started when the window was created.
- --env
- Environment variables to set in the child process. Can be specified
multiple times to set different environment variables. Syntax: name=value.
Using name= will set to empty string and just name will remove the
environment variable.
- --var
- User variables to set in the created window. Can be specified multiple
times to set different user variables. Syntax: name=value. Using name=
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 --copy-env.
- --location
[=default]
- Where to place the newly created window when it is added to a tab which
already has existing windows in it. after and before place the new window
before or after the active window. neighbor is a synonym for after. Also
applies to creating a new tab, where the value of after will cause the new
tab to be placed next to the current tab instead of at the end. The values
of vsplit, hsplit and split are only used by the 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.
Choices: default, after, before, first, hsplit, last,
neighbor, split, vsplit
- --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
- 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 for 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 remote_control_password
in kitty.conf are also in effect. You can override them by using
the same password here. You can also disable all
remote_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
[=none]
- 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.
Choices: none, @alternate, @alternate_scrollback,
@first_cmd_output_on_screen, @last_cmd_output, @last_visited_cmd_output,
@screen, @screen_scrollback, @selection
- --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
- Create a marker that highlights text in the newly created window. The
syntax is the same as for the toggle_marker action (see /marks).
- --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. Defaults to
whatever is used by the parent kitty process, which in turn defaults to
kitty.
- --os-window-name
- Set the WM_NAME property on X11 for the newly created OS Window when using
--type. Defaults to --os-window-class.
- --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
[=normal]
- The initial state for the newly created OS Window.
Choices: normal, fullscreen, maximized, minimized
- --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
- The position for the window logo. Only takes effect if --logo is
specified. See window_logo_position.
- --logo-alpha
[=-1]
- The amount the window logo should be faded into the background. Only takes
effect if --logo is specified. See window_logo_alpha.
- --color
- Change colors in the newly launched window. You can either specify a path
to a .conf file with the same syntax as kitty.conf to read the
colors from, or specify them individually, for example::
--color background=white --color foreground=red
- --spacing
- Set the margin and padding for the newly created window. For example:
margin=20 or padding-left=10 or margin-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,
-w
- 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:
watchers. Relative paths are resolved relative to the kitty config
directory. Global watchers for all windows can be specified with
watcher in kitty.conf.
- --help, -h
- Show help for this command