1KITTY(1) kitty KITTY(1)
2
6 kitty - kitty Documentation
7 kitty [options] [program-to-run ...]
9 Run the kitty terminal emulator. You can also specify the program to
11 run inside kitty as normal arguments following the options. For exam‐
12 ple: kitty --hold sh -c "echo hello, world"
13 For comprehensive documentation for kitty, please see:
15 https://sw.kovidgoyal.net/kitty/
16
18 --class <CLS>
19 Set the class part of the WM_CLASS window property. On Wayland,
20 it sets the app id. Default: kitty
21 --name <NAME>
23 Set the name part of the WM_CLASS property. Defaults to using
24 the value from kitty --class.
25 --title <TITLE>, -T <TITLE>
27 Set the OS window title. This will override any title set by the
28 program running inside kitty, permanently fixing the OS window's
29 title. So only use this if you are running a program that does
30 not set titles.
31 --config <CONFIG>, -c <CONFIG>
33 Specify a path to the configuration file(s) to use. All configu‐
34 ration files are merged onto the builtin kitty.conf, overriding
35 the builtin values. This option can be specified multiple times
36 to read multiple configuration files in sequence, which are
37 merged. Use the special value NONE to not load any config file.
38 If this option is not specified, config files are searched for
40 in the order: $XDG_CONFIG_HOME/kitty/kitty.conf, ~/.con‐
41 fig/kitty/kitty.conf, $XDG_CONFIG_DIRS/kitty/kitty.conf. The
42 first one that exists is used as the config file.
43 If the environment variable KITTY_CONFIG_DIRECTORY is specified,
45 that directory is always used and the above searching does not
46 happen.
47 If /etc/xdg/kitty/kitty.conf exists, it is merged before (i.e.
49 with lower priority) than any user config files. It can be used
50 to specify system-wide defaults for all users. You can use ei‐
51 ther - or /dev/stdin to read the config from STDIN.
52 --override <OVERRIDE>, -o <OVERRIDE>
54 Override individual configuration options, can be specified mul‐
55 tiple times. Syntax: name=value. For example: kitty -o
56 font_size=20
57 --directory <DIRECTORY>, --working-directory <DIRECTORY>, -d <DIREC‐
59 TORY>
60 Change to the specified directory when launching. Default: .
61 --detach
63 Detach from the controlling terminal, if any. Not available on
64 macOS.
65 --session <SESSION>
67 Path to a file containing the startup session (tabs, windows,
68 layout, programs). Use - to read from STDIN. See the README file
69 for details and an example. Environment variables in the file
70 name are expanded, relative paths are resolved relative to the
71 kitty configuration directory. The special value none means no
72 session will be used, even if the startup_session option has
73 been specified in kitty.conf.
74 --hold Remain open, at a shell prompt, after child process exits. Note
76 that this only affects the first window. You can quit by either
77 using the close window shortcut or running the exit command.
78 --single-instance, -1
80 If specified only a single instance of kitty will run. New invo‐
81 cations will instead create a new top-level window in the exist‐
82 ing kitty instance. This allows kitty to share a single sprite
83 cache on the GPU and also reduces startup time. You can also
84 have separate groups of kitty instances by using the kitty --in‐
85 stance-group option.
86 --instance-group <INSTANCE_GROUP>
88 Used in combination with the kitty --single-instance option. All
89 kitty invocations with the same kitty --instance-group will re‐
90 sult in new windows being created in the first kitty instance
91 within that group.
92 --wait-for-single-instance-window-close
94 Normally, when using kitty --single-instance, kitty will open a
95 new window in an existing instance and quit immediately. With
96 this option, it will not quit till the newly opened window is
97 closed. Note that if no previous instance is found, then kitty
98 will wait anyway, regardless of this option.
99 --listen-on <LISTEN_ON>
101 Listen on the specified socket address for control messages. For
102 example, kitty --listen-on=unix:/tmp/mykitty or kitty --lis‐
103 ten-on=tcp:localhost:12345. On Linux systems, you can also use
104 abstract UNIX sockets, not associated with a file, like this:
105 kitty --listen-on=unix:@mykitty. Environment variables are ex‐
106 panded and relative paths are resolved with respect to the tem‐
107 porary directory. To control kitty, you can send commands to it
108 with kitty @ using the kitty @ --to option to specify this ad‐
109 dress. Note that if you run kitty @ within a kitty window, there
110 is no need to specify the kitty @ --to option as it will auto‐
111 matically read from the environment. Note that this will be ig‐
112 nored unless allow_remote_control is set to either: yes, socket
113 or socket-only. For UNIX sockets, this can also be specified in
114 kitty.conf.
115 --start-as <START_AS>
117 Control how the initial kitty window is created. Default: nor‐
118 mal Choices: fullscreen, maximized, minimized, normal
119 Debugging options
121 --version, -v
122 The current kitty version.
123 --dump-commands
125 Output commands received from child process to STDOUT.
126 --replay-commands <REPLAY_COMMANDS>
128 Replay previously dumped commands. Specify the path to a dump
129 file previously created by kitty --dump-commands. You can open a
130 new kitty window to replay the commands with:
131 kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
133 --dump-bytes <DUMP_BYTES>
135 Path to file in which to store the raw bytes received from the
136 child process.
137 --debug-gl, --debug-rendering
139 Debug rendering commands. This will cause all OpenGL calls to
140 check for errors instead of ignoring them. Also prints out mis‐
141 cellaneous debug information. Useful when debugging rendering
142 problems.
143 --debug-input, --debug-keyboard
145 Print out key and mouse events as they are received.
146 --debug-font-fallback
148 Print out information about the selection of fallback fonts for
149 characters not present in the main font.
150 --watcher <WATCHER>
152 This option is deprecated in favor of the watcher option in
153 kitty.conf and should not be used.
154
156 kitty is capable of running multiple programs organized into tabs and
157 windows. The top level of organization is the OS window. Each OS win‐
158 dow consists of one or more tabs. Each tab consists of one or more
159 kitty windows. The kitty windows can be arranged in multiple different
160 layouts, like windows are organized in a tiling window manager. The
161 keyboard controls (which are all customizable) for tabs and windows
162 are:
163 Scrolling
165 ┌──────────────────────────┬────────────────────────────┐
166 │Action │ Shortcut │
167 ├──────────────────────────┼────────────────────────────┤
168 │Line up │ ctrl+shift+up (also ⌥+⌘+⇞ │
169 │ │ and ⌘+↑ on macOS) │
170 ├──────────────────────────┼────────────────────────────┤
171 │Line down │ ctrl+shift+down (also │
172 │ │ ⌥+⌘+⇟ and ⌘+↓ on macOS) │
173 ├──────────────────────────┼────────────────────────────┤
174 │Page up │ ctrl+shift+page_up (also │
175 │ │ ⌘+⇞ on macOS) │
176 ├──────────────────────────┼────────────────────────────┤
177 │Page down │ ctrl+shift+page_down (also │
178 │ │ ⌘+⇟ on macOS) │
179 ├──────────────────────────┼────────────────────────────┤
180 │Top │ ctrl+shift+home (also ⌘+↖ │
181 │ │ on macOS) │
182 ├──────────────────────────┼────────────────────────────┤
183 │Bottom │ ctrl+shift+end (also ⌘+↘ │
184 │ │ on macOS) │
185 ├──────────────────────────┼────────────────────────────┤
186 │Previous shell prompt │ ctrl+shift+z (see Shell │
187 │ │ integration) │
188 ├──────────────────────────┼────────────────────────────┤
189 │Next shell prompt │ ctrl+shift+x (see Shell │
190 │ │ integration) │
191 ├──────────────────────────┼────────────────────────────┤
192 │Browse scrollback in less │ ctrl+shift+h │
193 ├──────────────────────────┼────────────────────────────┤
194 │Browse last cmd output │ ctrl+shift+g (see Shell │
195 │ │ integration) │
196 └──────────────────────────┴────────────────────────────┘
197 The scroll actions only take effect when the terminal is in the main
199 screen. When the alternate screen is active (for example when using a
200 full screen program like an editor) the key events are instead passed
201 to program running in the terminal.
202 Tabs
204 ─────────────────────────────────────────────────
205 Action Shortcut
206 ─────────────────────────────────────────────────
207 New tab ctrl+shift+t (also ⌘+t on
208 macOS)
209 ─────────────────────────────────────────────────
210 Close tab ctrl+shift+q (also ⌘+w on
211 macOS)
212 ─────────────────────────────────────────────────
213 Next tab ctrl+shift+right (also ⌃+⇥
214 and ⇧+⌘+] on macOS)
215 ─────────────────────────────────────────────────
216 Previous tab ctrl+shift+left (also
217 ⇧+⌃+⇥ and ⇧+⌘+[ on macOS)
218 ─────────────────────────────────────────────────
219 Next layout ctrl+shift+l
220 ─────────────────────────────────────────────────
221 Move tab forward ctrl+shift+.
222 ─────────────────────────────────────────────────
223 Move tab backward ctrl+shift+,
224 ─────────────────────────────────────────────────
225 Set tab title ctrl+shift+alt+t (also
226 ⇧+⌘+i on macOS)
227 ┌──────────────────┬────────────────────────────┐
228 │ │ │
229 Windows │ │ │
230 ┌─┼──────────────────┼─┬──────────────────────────┼─┐
231 │A│ction │ │ Shortcut │ │
232 ├─┼──────────────────┼─┼──────────────────────────┼─┤
233 │N│ew window │ │ ctrl+shift+enter (also ⌘+│↩ │
234 │ │ │ │ on macOS) │ │
235 ├─┼──────────────────┼─┼──────────────────────────┼─┤
236 │N│ew OS window │ │ ctrl+shift+n (also ⌘+n o│n │
237 │ │ │ │ macOS) │ │
238 ├─┼──────────────────┼─┼──────────────────────────┼─┤
239 │C│lose window │ │ ctrl+shift+w (also ⇧+⌘+│d │
240 │ │ │ │ on macOS) │ │
241 ├─┼──────────────────┼─┼──────────────────────────┼─┤
242 │R│esize window │ │ ctrl+shift+r (also ⌘+r o│n │
243 │ │ │ │ macOS) │ │
244 ├─┼──────────────────┼─┼──────────────────────────┼─┤
245 │N│ext window │ │ ctrl+shift+] │ │
246 ├─┼──────────────────┼─┼──────────────────────────┼─┤
247 │P│revious window │ │ ctrl+shift+[ │ │
248 ├─┼──────────────────┼─┼──────────────────────────┼─┤
249 │M│ove window forward │ │ ctrl+shift+f │ │
250 ├─┼──────────────────┼─┼──────────────────────────┼─┤
251 │M│ove window backward│ │ ctrl+shift+b │ │
252 ├─┼──────────────────┼─┼──────────────────────────┼─┤
253 │M│ove window to top │ │ ctrl+shift+` │ │
254 ├─┼──────────────────┼─┼──────────────────────────┼─┤
255 │V│isually focus windo│w │ ctrl+shift+f7 │ │
256 ├─┼──────────────────┼─┼──────────────────────────┼─┤
257 │V│isually swap window│ │ ctrl+shift+f8 │ │
258 ├─┼──────────────────┼─┼──────────────────────────┼─┤
259 │F│ocus specific windo│w │ ctrl+shift+1, ctrl+shift+│2 │
260 │ │ │ │ ... ctrl+shift+0 (als│o │
261 │ │ │ │ ⌘+1, ⌘+2 ... ⌘+9 on macOS│) │
262 │ │ │ │ (clockwise from th│e │
263 │ │ │ │ top-left) │ │
264 └─┼──────────────────┼─┴──────────────────────────┼─┘
265 │ │ │
266 Additionall│y, you can define s│hortcuts in kitty.conf to foc│us neighbor‐
267 ing window│s and move windo│ws around (similar to window│movement in
268 vim): │ │ │
269 │ │ │
270 map ctrl│+left neighboring_w│indow left │
271 map shif│t+left move_window │right │
272 map ctrl│+down neighboring_w│indow down │
273 map shif│t+down move_window │up │
274 ...
275 You can also define a shortcut to switch to the previously active win‐
277 dow:
278 map ctrl+p nth_window -1
280 nth_window will focus the nth window for positive numbers (starting
282 from zero) and the previously active windows for negative numbers.
283 To switch to the nth OS window, you can define nth_os_window. Only pos‐
285 itive numbers are accepted, starting from one.
286 You can define shortcuts to detach the current window and move it to
288 another tab or another OS window:
289 # moves the window into a new OS window
291 map ctrl+f2 detach_window
292 # moves the window into a new tab
293 map ctrl+f3 detach_window new-tab
294 # moves the window into the previously active tab
295 map ctrl+f3 detach_window tab-prev
296 # moves the window into the tab at the left of the active tab
297 map ctrl+f3 detach_window tab-left
298 # asks which tab to move the window into
299 map ctrl+f4 detach_window ask
300 Similarly, you can detach the current tab, with:
302 # moves the tab into a new OS window
304 map ctrl+f2 detach_tab
305 # asks which OS Window to move the tab into
306 map ctrl+f4 detach_tab ask
307 Finally, you can define a shortcut to close all windows in a tab other
309 than the currently active window:
310 map f9 close_other_windows_in_tab
312
314 The full list of actions that can be mapped to key presses is available
315 here.
316 ┌───────────────────────────┬────────────────────────────┐
318 │Action │ Shortcut │
319 ├───────────────────────────┼────────────────────────────┤
320 │Show this help │ ctrl+shift+f1 │
321 ├───────────────────────────┼────────────────────────────┤
322 │Copy to clipboard │ ctrl+shift+c (also ⌘+c on │
323 │ │ macOS) │
324 ├───────────────────────────┼────────────────────────────┤
325 │Paste from clipboard │ ctrl+shift+v (also ⌘+v on │
326 │ │ macOS) │
327 ├───────────────────────────┼────────────────────────────┤
328 │Paste from selection │ ctrl+shift+s │
329 ├───────────────────────────┼────────────────────────────┤
330 │Pass selection to program │ ctrl+shift+o │
331 ├───────────────────────────┼────────────────────────────┤
332 │Increase font size │ ctrl+shift+equal (also ⌘++ │
333 │ │ on macOS) │
334 ├───────────────────────────┼────────────────────────────┤
335 │Decrease font size │ ctrl+shift+minus (also ⌘+- │
336 │ │ on macOS) │
337 ├───────────────────────────┼────────────────────────────┤
338 │Restore font size │ ctrl+shift+backspace (also │
339 │ │ ⌘+0 on macOS) │
340 └───────────────────────────┴────────────────────────────┘
341 │Toggle fullscreen │ ctrl+shift+f11 (also ⌃+⌘+f │
345 │ │ on macOS) │
346 ├───────────────────────────┼────────────────────────────┤
347 │Toggle maximized │ ctrl+shift+f10 │
348 ├───────────────────────────┼────────────────────────────┤
349 │Input Unicode character │ ctrl+shift+u (also │
350 │ │ ⌃+⌘+space on macOS) │
351 ├───────────────────────────┼────────────────────────────┤
352 │Open URL in web browser │ ctrl+shift+e │
353 ├───────────────────────────┼────────────────────────────┤
354 │Reset the terminal │ ctrl+shift+delete (also │
355 │ │ ⌥+⌘+r on macOS) │
356 ├───────────────────────────┼────────────────────────────┤
357 │Edit kitty.conf │ ctrl+shift+f2 (also ⌘+, on │
358 │ │ macOS) │
359 ├───────────────────────────┼────────────────────────────┤
360 │Reload kitty.conf │ ctrl+shift+f5 (also ⌃+⌘+, │
361 │ │ on macOS) │
362 ├───────────────────────────┼────────────────────────────┤
363 │Debug kitty.conf │ ctrl+shift+f6 (also ⌥+⌘+, │
364 │ │ on macOS) │
365 ├───────────────────────────┼────────────────────────────┤
366 │Open a kitty shell │ ctrl+shift+escape │
367 ├───────────────────────────┼────────────────────────────┤
368 │Increase background opac‐ │ ctrl+shift+a>m │
369 │ity │ │
370 ├───────────────────────────┼────────────────────────────┤
371 │Decrease background opac‐ │ ctrl+shift+a>l │
372 │ity │ │
373 ├───────────────────────────┼────────────────────────────┤
374 │Full background opacity │ ctrl+shift+a>1 │
375 ├───────────────────────────┼────────────────────────────┤
376 │Reset background opacity │ ctrl+shift+a>d │
377 └───────────────────────────┴────────────────────────────┘
378
380 See kitty.conf(5)
381
383 Kovid Goyal
384
386 2023, Kovid Goyal
3870.29.2 Jul 27, 2023 KITTY(1)