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.
64 --session <SESSION>
66 Path to a file containing the startup session (tabs, windows,
67 layout, programs). Use - to read from STDIN. See the README file
68 for details and an example.
69 --hold Remain open after child process exits. Note that this only af‐
71 fects the first window. You can quit by either using the close
72 window shortcut or pressing any key.
73 --single-instance, -1
75 If specified only a single instance of kitty will run. New invo‐
76 cations will instead create a new top-level window in the exist‐
77 ing kitty instance. This allows kitty to share a single sprite
78 cache on the GPU and also reduces startup time. You can also
79 have separate groups of kitty instances by using the kitty --in‐
80 stance-group option.
81 --instance-group <INSTANCE_GROUP>
83 Used in combination with the kitty --single-instance option. All
84 kitty invocations with the same kitty --instance-group will re‐
85 sult in new windows being created in the first kitty instance
86 within that group.
87 --wait-for-single-instance-window-close
89 Normally, when using kitty --single-instance, kitty will open a
90 new window in an existing instance and quit immediately. With
91 this option, it will not quit till the newly opened window is
92 closed. Note that if no previous instance is found, then kitty
93 will wait anyway, regardless of this option.
94 --listen-on <LISTEN_ON>
96 Listen on the specified socket address for control messages. For
97 example, kitty --listen-on=unix:/tmp/mykitty or kitty --lis‐
98 ten-on=tcp:localhost:12345. On Linux systems, you can also use
99 abstract UNIX sockets, not associated with a file, like this:
100 kitty --listen-on=unix:@mykitty. Environment variables are ex‐
101 panded and relative paths are resolved with respect to the tem‐
102 porary directory. To control kitty, you can send commands to it
103 with kitty @ using the kitty @ --to option to specify this ad‐
104 dress. Unless you enabled allow_remote_control in kitty.conf,
105 this option will be ignored. Note that if you run kitty @ within
106 a kitty window, there is no need to specify the kitty @ --to op‐
107 tion as it will automatically read from the environment. For
108 UNIX sockets, this can also be specified in kitty.conf.
109 --start-as <START_AS>
111 Control how the initial kitty window is created. Default: nor‐
112 mal Choices: fullscreen, maximized, minimized, normal
113 Debugging options
115 --version, -v
116 The current kitty version.
117 --dump-commands
119 Output commands received from child process to STDOUT.
120 --replay-commands <REPLAY_COMMANDS>
122 Replay previously dumped commands. Specify the path to a dump
123 file previously created by kitty --dump-commands. You can open a
124 new kitty window to replay the commands with:
125 kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
127 --dump-bytes <DUMP_BYTES>
129 Path to file in which to store the raw bytes received from the
130 child process.
131 --debug-gl, --debug-rendering
133 Debug rendering commands. This will cause all OpenGL calls to
134 check for errors instead of ignoring them. Also prints out mis‐
135 cellaneous debug information. Useful when debugging rendering
136 problems.
137 --debug-input, --debug-keyboard
139 Print out key and mouse events as they are received.
140 --debug-font-fallback
142 Print out information about the selection of fallback fonts for
143 characters not present in the main font.
144 --watcher <WATCHER>
146 This option is deprecated in favor of the watcher option in
147 kitty.conf and should not be used.
148
150 kitty is capable of running multiple programs organized into tabs and
151 windows. The top level of organization is the OS window. Each OS win‐
152 dow consists of one or more tabs. Each tab consists of one or more
153 kitty windows. The kitty windows can be arranged in multiple different
154 layouts, like windows are organized in a tiling window manager. The
155 keyboard controls (which are all customizable) for tabs and windows
156 are:
157 Scrolling
159 ┌──────────────────────────┬────────────────────────────┐
160 │Action │ Shortcut │
161 ├──────────────────────────┼────────────────────────────┤
162 │Line up │ ctrl+shift+up (also ⌥+⌘+⇞ │
163 │ │ and ⌘+↑ on macOS) │
164 ├──────────────────────────┼────────────────────────────┤
165 │Line down │ ctrl+shift+down (also │
166 │ │ ⌥+⌘+⇟ and ⌘+↓ on macOS) │
167 ├──────────────────────────┼────────────────────────────┤
168 │Page up │ ctrl+shift+page_up (also │
169 │ │ ⌘+⇞ on macOS) │
170 ├──────────────────────────┼────────────────────────────┤
171 │Page down │ ctrl+shift+page_down (also │
172 │ │ ⌘+⇟ on macOS) │
173 ├──────────────────────────┼────────────────────────────┤
174 │Top │ ctrl+shift+home (also ⌘+↖ │
175 │ │ on macOS) │
176 ├──────────────────────────┼────────────────────────────┤
177 │Bottom │ ctrl+shift+end (also ⌘+↘ │
178 │ │ on macOS) │
179 ├──────────────────────────┼────────────────────────────┤
180 │Previous shell prompt │ ctrl+shift+z (see Shell │
181 │ │ integration) │
182 ├──────────────────────────┼────────────────────────────┤
183 │Next shell prompt │ ctrl+shift+x (see Shell │
184 │ │ integration) │
185 ├──────────────────────────┼────────────────────────────┤
186 │Browse scrollback in less │ ctrl+shift+h │
187 ├──────────────────────────┼────────────────────────────┤
188 │Browse last cmd output │ ctrl+shift+g (see Shell │
189 │ │ integration) │
190 └──────────────────────────┴────────────────────────────┘
191 Tabs
193 ┌──────────────────┬────────────────────────────┐
194 │Action │ Shortcut │
195 ├──────────────────┼────────────────────────────┤
196 │New tab │ ctrl+shift+t (also ⌘+t on │
197 │ │ macOS) │
198 └──────────────────┴────────────────────────────┘
199 │Close tab │ ctrl+shift+q (also ⌘+w on │
203 │ │ macOS) │
204 ├──────────────────┼────────────────────────────┤
205 │Next tab │ ctrl+shift+right (also ⌃+⇥ │
206 │ │ and ⇧+⌘+] on macOS) │
207 ├──────────────────┼────────────────────────────┤
208 │Previous tab │ ctrl+shift+left (also │
209 │ │ ⇧+⌃+⇥ and ⇧+⌘+[ on macOS) │
210 ├──────────────────┼────────────────────────────┤
211 │Next layout │ ctrl+shift+l │
212 ├──────────────────┼────────────────────────────┤
213 │Move tab forward │ ctrl+shift+. │
214 ├──────────────────┼────────────────────────────┤
215 │Move tab backward │ ctrl+shift+, │
216 ├──────────────────┼────────────────────────────┤
217 │Set tab title │ ctrl+shift+alt+t (also │
218 │ │ ⇧+⌘+i on macOS) │
219 └──────────────────┴────────────────────────────┘
220 Windows
222 ┌──────────────────────┬────────────────────────────┐
223 │Action │ Shortcut │
224 ├──────────────────────┼────────────────────────────┤
225 │New window │ ctrl+shift+enter (also ⌘+↩ │
226 │ │ on macOS) │
227 ├──────────────────────┼────────────────────────────┤
228 │New OS window │ ctrl+shift+n (also ⌘+n on │
229 │ │ macOS) │
230 ├──────────────────────┼────────────────────────────┤
231 │Close window │ ctrl+shift+w (also ⇧+⌘+d │
232 │ │ on macOS) │
233 ├──────────────────────┼────────────────────────────┤
234 │Next window │ ctrl+shift+] │
235 ├──────────────────────┼────────────────────────────┤
236 │Previous window │ ctrl+shift+[ │
237 ├──────────────────────┼────────────────────────────┤
238 │Move window forward │ ctrl+shift+f │
239 ├──────────────────────┼────────────────────────────┤
240 │Move window backward │ ctrl+shift+b │
241 ├──────────────────────┼────────────────────────────┤
242 │Move window to top │ ctrl+shift+` │
243 ├──────────────────────┼────────────────────────────┤
244 │Visually focus window │ ctrl+shift+f7 │
245 ├──────────────────────┼────────────────────────────┤
246 │Visually swap window │ ctrl+shift+f8 │
247 ├──────────────────────┼────────────────────────────┤
248 │Focus specific window │ ctrl+shift+1, ctrl+shift+2 │
249 │ │ ... ctrl+shift+0 (also │
250 │ │ ⌘+1, ⌘+2 ... ⌘+9 on macOS) │
251 │ │ (clockwise from the │
252 │ │ top-left) │
253 └──────────────────────┴────────────────────────────┘
254 Additionally, you can define shortcuts in kitty.conf to focus neighbor‐
256 ing windows and move windows around (similar to window movement in
257 vim):
258 map ctrl+left neighboring_window left
260 map shift+left move_window right
261 map ctrl+down neighboring_window down
262 map shift+down move_window up
263 ...
264 You can also define a shortcut to switch to the previously active win‐
266 dow:
267 map ctrl+p nth_window -1
269 nth_window will focus the nth window for positive numbers (starting
271 from zero) and the previously active windows for negative numbers.
272 To switch to the nth OS window, you can define nth_os_window. Only pos‐
274 itive numbers are accepted, starting from one.
275 You can define shortcuts to detach the current window and move it to
277 another tab or another OS window:
278 # moves the window into a new OS window
280 map ctrl+f2 detach_window
281 # moves the window into a new tab
282 map ctrl+f3 detach_window new-tab
283 # moves the window into the previously active tab
284 map ctrl+f3 detach_window tab-prev
285 # moves the window into the tab at the left of the active tab
286 map ctrl+f3 detach_window tab-left
287 # asks which tab to move the window into
288 map ctrl+f4 detach_window ask
289 Similarly, you can detach the current tab, with:
291 # moves the tab into a new OS window
293 map ctrl+f2 detach_tab
294 # asks which OS Window to move the tab into
295 map ctrl+f4 detach_tab ask
296 Finally, you can define a shortcut to close all windows in a tab other
298 than the currently active window:
299 map f9 close_other_windows_in_tab
301
303 The full list of actions that can be mapped to key presses is available
304 here.
305 ┌───────────────────────────┬────────────────────────────┐
307 │Action │ Shortcut │
308 ├───────────────────────────┼────────────────────────────┤
309 │Copy to clipboard │ ctrl+shift+c (also ⌘+c on │
310 │ │ macOS) │
311 ├───────────────────────────┼────────────────────────────┤
312 │Paste from clipboard │ ctrl+shift+v (also ⌘+v on │
313 │ │ macOS) │
314 ├───────────────────────────┼────────────────────────────┤
315 │Paste from selection │ ctrl+shift+s │
316 ├───────────────────────────┼────────────────────────────┤
317 │Pass selection to program │ ctrl+shift+o │
318 ├───────────────────────────┼────────────────────────────┤
319 │Increase font size │ ctrl+shift+equal (also ⌘++ │
320 │ │ on macOS) │
321 ├───────────────────────────┼────────────────────────────┤
322 │Decrease font size │ ctrl+shift+minus (also ⌘+- │
323 │ │ on macOS) │
324 ├───────────────────────────┼────────────────────────────┤
325 │Restore font size │ ctrl+shift+backspace (also │
326 │ │ ⌘+0 on macOS) │
327 ├───────────────────────────┼────────────────────────────┤
328 │Toggle fullscreen │ ctrl+shift+f11 (also ⌃+⌘+f │
329 │ │ on macOS) │
330 ├───────────────────────────┼────────────────────────────┤
331 │Toggle maximized │ ctrl+shift+f10 │
332 └───────────────────────────┴────────────────────────────┘
333 │Input Unicode character │ ctrl+shift+u (also │
337 │ │ ⌃+⌘+space on macOS) │
338 ├───────────────────────────┼────────────────────────────┤
339 │Open URL in web browser │ ctrl+shift+e │
340 ├───────────────────────────┼────────────────────────────┤
341 │Reset the terminal │ ctrl+shift+delete (also │
342 │ │ ⌥+⌘+r on macOS) │
343 ├───────────────────────────┼────────────────────────────┤
344 │Edit kitty.conf │ ctrl+shift+f2 (also ⌘+, on │
345 │ │ macOS) │
346 ├───────────────────────────┼────────────────────────────┤
347 │Reload kitty.conf │ ctrl+shift+f5 (also ⌃+⌘+, │
348 │ │ on macOS) │
349 ├───────────────────────────┼────────────────────────────┤
350 │Debug kitty.conf │ ctrl+shift+f6 (also ⌥+⌘+, │
351 │ │ on macOS) │
352 ├───────────────────────────┼────────────────────────────┤
353 │Open a kitty shell │ ctrl+shift+escape │
354 ├───────────────────────────┼────────────────────────────┤
355 │Increase background opac‐ │ ctrl+shift+a>m │
356 │ity │ │
357 ├───────────────────────────┼────────────────────────────┤
358 │Decrease background opac‐ │ ctrl+shift+a>l │
359 │ity │ │
360 ├───────────────────────────┼────────────────────────────┤
361 │Full background opacity │ ctrl+shift+a>1 │
362 ├───────────────────────────┼────────────────────────────┤
363 │Reset background opacity │ ctrl+shift+a>d │
364 └───────────────────────────┴────────────────────────────┘
365
367 See kitty.conf(5)
368
370 Kovid Goyal
371
373 2022, Kovid Goyal
3740.25.2 Jun 07, 2022 KITTY(1)