kitten-@-launch(1)

💖 kitten-@-launch(1) — kitten Manual 💖

Okay bestie, this is the kitten-@-launch(1) page from the kitten Manual. We're launching processes in new windows/tabs and it's giving very useful. ✨

✨ Name ✨

kitten-@-launch — Run an arbitrary process in a new window/tab

🛠️ Usage 🛠️

kitten @ launch  [CMD ...]

💅 Description 💅

So this prints out the id of the newly opened window. 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:

kitten @ launch --title=Email mutt

Lowkey iconic. 🦋 Periodt. 💅

---

🎀 Options 🎀

• --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, session 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.
  • The field session matches tabs that were created in the specified session. Use the expression ^$ to match windows that were not created in a session and . to match the currently active session and ~ to match either the currently active session or the last active session when no session is active.
  • 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, parent_focused and focused_os_window. 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. The value focused_os_window matches all tabs in the currently focused OS window.
  • Note that you can use the kitten @ ls command to get a list of tabs.
• --wait-for-child-to-exit [=no] — Wait until the launched program exits and print out its exit code. The exit code is printed out instead of the window id. If the program exited normally its exit code is printed, which is always greater than or equal to zero. If the program was killed by a signal, the symbolic name of the SIGNAL is printed, if available, otherwise the signal number with a leading minus sign is printed.
• --response-timeout [=86400] — The time in seconds to wait for the started process to exit, when using the --wait-for-child-to-exit option. Defaults to one day.
• --no-response [=no] — Do not print out the id of the newly created window.
• --self [=no] — If specified the tab containing the window this command is run in is used instead of the active tab.
• --source-window — A match expression to select the window from which data such as title, colors, env vars, screen contents, etc. are copied. When not specified the currently active window is used. See search_syntax for the syntax used for specifying windows.
• --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 --source-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 tab containing the --source-window.
• --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. Not available when the launch <launch> command is used in startup sessions.
  • os-window — A new operating system window. Not available when the launch <launch> command is used in startup sessions.
  • 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.
  • os-panel — Similar to os-window, except that it creates the new OS Window as a desktop panel. Only works on platforms that support this, such as Wayland compositors that support the layer shell protocol. Use the --os-panel option to configure the panel.
  • Choices: window, background, clipboard, os-panel, os-window, overlay, overlay-main, primary, tab.
• --dont-take-focus, --keep-focus [=no] — 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 --source-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.
  • When opening in the same working directory as the current window causes the new window to connect to a remote host, you can use the --hold-after-ssh flag to prevent the new window from closing when the connection is terminated.
• --add-to-session — Add the newly created window/tab to the specified session. Use . to add to the session of the --source-window, if any. See sessions for what a session is and how to use one. By default, the window is added to the session of the --source-window when --cwd is set to use the working directory from that window, otherwise the newly created window does not belong to any session. To force adding to no session, use the value !. Adding a newly created window to a session is purely temporary, it does not change the actual session file, for that you have to resave the session. Note that using this flag in a launch command within a session file has no effect as the window is always added to the session belonging to that file.
• --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 [=no] — Keep the window open even after the command being executed exits, at a shell prompt. The shell will be run after the launched command exits.
• --copy-colors [=no] — Set the colors of the newly created window to be the same as the colors in the --source-window.
• --copy-cmdline [=no] — Ignore any specified command line and instead use the command line from the --source-window.
• --copy-env [=no] — Copy the environment variables from the --source-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. In particular, this means, if you are running a shell in the window and the shell has set env vars in its rc files, these will not be copied. 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. See --next-to to use a window other than the currently active window.

…and the choices for that one are default, after, before, first, hsplit, last, neighbor, split, vsplit — iconic lineup, no notes 💅

• --next-to — a match expression that picks which window the new window gets created next to 🫶 the syntax for specifying windows lives in search_syntax. If you don't specify anything it just defaults to the active window, obviously. Two little gotchas tho: when you use it via remote control it gets ignored unless the matched window is in the target tab (which defaults to the active tab), and when you're using --type of tab, the tab gets created in the OS Window that contains the matched window. k.
• --bias [=0] — the bias that alters the size of the window 🔥 it controls what fraction of the available space the window takes. What bias actually means depends on your current layout, so buckle up bestie:
  • Splits layout: bias is read as a percentage between 0 and 100. When you split a window into two, the new window takes the specified fraction of the space that was allotted to the original window, and the original window takes the remainder.
  • Vertical/horizontal layout: bias is read as adding to / subtracting from the normal size of the window. Should be a number between -90 and 90 — that number is the percentage of the OS Window size that gets added to the window size. So like, if a window would normally have been size 50 in the layout inside an OS Window that's size 80 high, and --bias -10 is used, it becomes approximately size 42 high. Note that sizes are approximations — you literally cannot use this method to create windows of fixed sizes, sorry 😭
  • Tall layout: if the window being created is the first window in a column, the bias is interpreted as a percentage, same 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, same as for the vertical layout above.
  • Fat layout: same as tall layout except it goes by rows instead of columns.
  • Grid layout: bias is interpreted the same way as for the Vertical and Horizontal layouts — as something added/subtracted to the normal size. But since a grid layout has rows and columns, the bias on the first window in a column operates on the columns, and any later windows in that column operate on the row. So for example, if you bias the first window in a grid layout it changes the width of the first column, the second window changes the width of the second column, the third window changes the height of the second row, and so on.
  • tiny lore drop: the bias option was introduced in kitty version 0.36.0 ✨
• --allow-remote-control [=no] — programs running in this window can control kitty, even if remote control is not enabled in kitty.conf 👑 that said, 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 — so this isn't some magic shield, fr fr. It can 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 which actions remote control is allowed to take 🔒 works just like remote_control_password — you specify a password and a list of actions, exactly as for remote_control_password. For example:

--remote-control-password '"my passphrase" get-* set-colors'

This password is in effect for this window only. Note that any passwords you've defined for remote_control_password in kitty.conf are also in effect, and you can override them by using the same password here. You can also disable all the 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. Added to kitty in version 0.26.0 🧚

• --stdin-source [=none] — pass the screen contents as STDIN to the child process 📥 here's the menu of what you can feed it:
  • @selection — the currently selected text in the --source-window.
  • @screen — the contents of the --source-window.
  • @screen_scrollback — same as @screen, but it includes the scrollback buffer as well.
  • @alternate — the secondary screen of the --source-window. For example, if you run a full screen terminal application, the secondary screen is the screen you return to when you quit the application.
  • @first_cmd_output_on_screen — the output from the first command run in the shell on screen.
  • @last_cmd_output — the output from the last command run in the shell.
  • @last_visited_cmd_output — 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 [=no] — when you're using --stdin-source, this adds formatting escape codes 💖 without it, only plain text gets sent.
• --stdin-add-line-wrap-markers [=no] — when you're using --stdin-source, this adds a carriage return at every line wrap location (i.e. where long lines get wrapped at the screen edges) 🎀 super useful if you want to pipe to a program that wants to duplicate the screen layout of the screen.
• --marker — creates a marker that highlights text in the newly created window ✨ syntax is the same as for the toggle_marker action (see /marks).
• --os-window-class — sets the WM_CLASS property on X11 and the application id property on Wayland for the newly created OS window when you're using --type 🪟 defaults to whatever the parent kitty process uses, which in turn defaults to kitty.
• --os-window-name — sets the WM_NAME property on X11 for the newly created OS Window when you're using --type. Defaults to --os-window-class.
• --os-window-title — sets the title for the newly created OS window 👑 this title overrides any titles set by programs running in kitty. The special value current copies the title from the OS Window containing the --source-window.
• --os-window-state [=normal] — the initial state for the newly created OS Window.
  • Choices: normal, fullscreen, maximized, minimized
• --os-window-position — the position, for example 10x20, on screen at which to place the newly created OS Window 🌈 this may or may not work depending on the policies of the desktop environment / window manager. It never works on Wayland. 💀
• --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] — how much 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 give it a path to a .conf file with the same syntax as kitty.conf to read the colors from, or specify them individually, like:

--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, and the *-h and *-v variants set horizontal and vertical values respectively. Can be specified multiple times. Note that this is ignored for overlay windows, since those use the settings from the base window.
• --watcher, -w — path to a Python file 🐍 appropriately named functions in this file get called for various events, like 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.
• --os-panel — options to control the creation of desktop panels 🖥️ takes the same settings as the panel kitten, except for --override and --config. Can be specified multiple times. For example, to create a desktop panel at the bottom of the screen that's two lines high:

launch --type os-panel --os-panel lines=2 --os-panel
edge=bottom sh -c "echo; echo; echo hello; sleep 5s"

• --hold-after-ssh [=no] — when you're using --cwd=current or similar from a window that's running the ssh kitten, the new window runs a local shell after disconnecting from the remote host, if this option is specified 🌸
• --help, -h [=no] — show help for this command 💅

---

okay that's a whole lotta options but you're literally doing so good, bestie — keep going, there's more 💖

✨ Global options ✨

okay so before we get into the launch-y stuff, there's a whole lil' set of global options that handle talking to kitty itself — the address, the password, the whole vibe check 💅 these apply no matter what you're launching, so pay attention bestie 🫶

• --to — the address of the kitty instance you wanna control, periodt. This is the same address you handed to kitty via the --listen-on option or the listen_on setting in kitty.conf. If you don't specify it, the env var KITTY_LISTEN_ON gets checked instead 👀 and if that's also missing? The messages just go to the controlling terminal for this process — which means it only works if this process is being run inside a kitty window, iykyk.
• --password — a password to use when contacting kitty 🔐 this makes kitty ask the user for permission to perform the specified action, unless the password has already been accepted before or is pre-configured in kitty.conf. Wanna use a blank password? Specify --use-password as always. iconic.
• --password-file [=rc-pass] — a file to read the password from 📄 trailing whitespace gets ignored (we don't care about your messy edges, bestie). Relative paths are resolved from the kitty configuration directory. Use - to read from STDIN. Use fd:num to read from the file descriptor num. This one gets used if no --password is supplied, and it defaults to checking for the rc-pass file in the kitty configuration directory 🎀
• --password-env [=KITTY_RC_PASSWORD] — the name of an environment variable to read the password from 🌸 used if no --password-file is supplied. Defaults to checking the env var KITTY_RC_PASSWORD. slay.
• --use-password [=if-available] — okay so if no password is available, kitty will usually just send the remote control command without one, no drama. This option lets you force it to always or never use the supplied password. If you set it to always and no password is provided, the blank password gets used 🫶
  • Choices: if-available, always, never

---

and that's the whole page, bestie 😭💖 you made it to the end — go forth and remote-control your kitty with main character energy 👑✨ this lil' icon is version 0.49.2, dated Oct 01, 2026, and honestly? she ate. 🍓🌷