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 sh -c "echo hello, world. Press ENTER to quit; read"
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 window title. This will override any title set by the
28 program running inside kitty. So only use this if you are run‐
29 ning a program that does not set titles. If combined with kitty
30 --session the title will be used for all windows created by the
31 session, that do not set their own titles.
32 --config <CONFIG>, -c <CONFIG>
34 Specify a path to the configuration file(s) to use. All configu‐
35 ration files are merged onto the builtin kitty.conf, overriding
36 the builtin values. This option can be specified multiple times
37 to read multiple configuration files in sequence, which are
38 merged. Use the special value NONE to not load a config file.
39 If this option is not specified, config files are searched for
41 in the order: $XDG_CONFIG_HOME/kitty/kitty.conf, ~/.con‐
42 fig/kitty/kitty.conf, $XDG_CONFIG_DIRS/kitty/kitty.conf. The
43 first one that exists is used as the config file.
44 If the environment variable KITTY_CONFIG_DIRECTORY is specified,
46 that directory is always used and the above searching does not
47 happen.
48 If /etc/xdg/kitty/kitty.conf exists it is merged before (i.e.
50 with lower priority) than any user config files. It can be used
51 to specify system-wide defaults for all users.
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 --watcher <WATCHER>, -w <WATCHER>
71 Path to a python file. Appropriately named functions in this
72 file will be called for various events, such as when the window
73 is resized, focused or closed. See the section on watchers in
74 the launch command documentation launch. Relative paths are re‐
75 solved relative to the kitty config directory. Note that this
76 watcher will be added only to all initially created windows, not
77 new windows created after startup.
78 --hold Remain open after child process exits. Note that this only af‐
80 fects the first window. You can quit by either using the close
81 window shortcut or pressing any key.
82 --single-instance, -1
84 If specified only a single instance of kitty will run. New invo‐
85 cations will instead create a new top-level window in the exist‐
86 ing kitty instance. This allows kitty to share a single sprite
87 cache on the GPU and also reduces startup time. You can also
88 have separate groups of kitty instances by using the kitty --in‐
89 stance-group option
90 --instance-group <INSTANCE_GROUP>
92 Used in combination with the kitty --single-instance option. All
93 kitty invocations with the same kitty --instance-group will re‐
94 sult in new windows being created in the first kitty instance
95 within that group
96 --wait-for-single-instance-window-close
98 Normally, when using --single-instance, kitty will open a new
99 window in an existing instance and quit immediately. With this
100 option, it will not quit till the newly opened window is closed.
101 Note that if no previous instance is found, then kitty will wait
102 anyway, regardless of this option.
103 --listen-on <LISTEN_ON>
105 Tell kitty to listen on the specified address for control mes‐
106 sages. For example, kitty --listen-on=unix:/tmp/mykitty or kitty
107 --listen-on=tcp:localhost:12345. On Linux systems, you can also
108 use abstract UNIX sockets, not associated with a file, like
109 this: kitty --listen-on=unix:@mykitty. Environment variables in
110 the setting are expanded and relative paths are resolved with
111 respect to the temporary directory. To control kitty, you can
112 send it commands with kitty @ using the kitty @ --to option to
113 specify this address. This option will be ignored, unless you
114 set allow_remote_control to yes in kitty.conf. Note that if you
115 run kitty @ within a kitty window, there is no need to specify
116 the --to option as it is read automatically from the environ‐
117 ment. For UNIX sockets, this can also be specified in
118 kitty.conf.
119 --start-as <START_AS>
121 Control how the initial kitty window is created. Default: nor‐
122 mal Choices: fullscreen, maximized, minimized, normal
123 Debugging options
125 --version, -v
126 The current kitty version
127 --dump-commands
129 Output commands received from child process to stdout
130 --replay-commands <REPLAY_COMMANDS>
132 Replay previously dumped commands. Specify the path to a dump
133 file previously created by --dump-commands. You can open a new
134 kitty window to replay the commands with:
135 kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
137 --dump-bytes <DUMP_BYTES>
139 Path to file in which to store the raw bytes received from the
140 child process
141 --debug-gl, --debug-rendering
143 Debug rendering commands. This will cause all OpenGL calls to
144 check for errors instead of ignoring them. Also prints out mis‐
145 cellaneous debug information. Useful when debugging rendering
146 problems
147 --debug-input, --debug-keyboard
149 This option will cause kitty to print out key and mouse events
150 as they are received
151 --debug-font-fallback
153 Print out information about the selection of fallback fonts for
154 characters not present in the main font.
155
157 kitty is capable of running multiple programs organized into tabs and
158 windows. The top level of organization is the Tab. Each tab consists of
159 one or more windows. The 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 │Scroll line up │ ctrl+shift+up (also ⌥+⌘+⇞ │
169 │ │ and ⌘+↑ on macOS) │
170 ├─────────────────┼────────────────────────────┤
171 │Scroll line down │ ctrl+shift+down (also │
172 │ │ ⌥+⌘+⇟ and ⌘+↓ on macOS) │
173 ├─────────────────┼────────────────────────────┤
174 │Scroll page up │ ctrl+shift+page_up (also │
175 │ │ ⌘+⇞ on macOS) │
176 ├─────────────────┼────────────────────────────┤
177 │Scroll page down │ ctrl+shift+page_down (also │
178 │ │ ⌘+⇟ on macOS) │
179 ├─────────────────┼────────────────────────────┤
180 │Scroll to top │ ctrl+shift+home (also ⌘+↖ │
181 │ │ on macOS) │
182 ├─────────────────┼────────────────────────────┤
183 │Scroll to bottom │ ctrl+shift+end (also ⌘+↘ │
184 │ │ on macOS) │
185 └─────────────────┴────────────────────────────┘
186 Tabs
188 ┌──────────────────┬────────────────────────────┐
189 │Action │ Shortcut │
190 ├──────────────────┼────────────────────────────┤
191 │New tab │ ctrl+shift+t (also ⌘+t on │
192 │ │ macOS) │
193 ├──────────────────┼────────────────────────────┤
194 │Close tab │ ctrl+shift+q (also ⌘+w on │
195 │ │ macOS) │
196 ├──────────────────┼────────────────────────────┤
197 │Next tab │ ctrl+shift+right (also ^+⇥ │
198 │ │ and ⇧+⌘+] on macOS) │
199 └──────────────────┴────────────────────────────┘
200 │Previous tab │ ctrl+shift+left (also │
203 │ │ ⇧+^+⇥ and ⇧+⌘+[ on macOS) │
204 ├──────────────────┼────────────────────────────┤
205 │Next layout │ ctrl+shift+l │
206 ├──────────────────┼────────────────────────────┤
207 │Move tab forward │ ctrl+shift+. │
208 ├──────────────────┼────────────────────────────┤
209 │Move tab backward │ ctrl+shift+, │
210 ├──────────────────┼────────────────────────────┤
211 │Set tab title │ ctrl+shift+alt+t (also │
212 │ │ ⇧+⌘+i on macOS) │
213 └──────────────────┴────────────────────────────┘
214 Windows
216 ┌──────────────────────┬────────────────────────────┐
217 │Action │ Shortcut │
218 ├──────────────────────┼────────────────────────────┤
219 │New window │ ctrl+shift+enter (also ⌘+↩ │
220 │ │ on macOS) │
221 ├──────────────────────┼────────────────────────────┤
222 │New OS window │ ctrl+shift+n (also ⌘+n on │
223 │ │ macOS) │
224 ├──────────────────────┼────────────────────────────┤
225 │Close window │ ctrl+shift+w (also ⇧+⌘+d │
226 │ │ on macOS) │
227 ├──────────────────────┼────────────────────────────┤
228 │Next window │ ctrl+shift+] │
229 ├──────────────────────┼────────────────────────────┤
230 │Previous window │ ctrl+shift+[ │
231 ├──────────────────────┼────────────────────────────┤
232 │Move window forward │ ctrl+shift+f │
233 ├──────────────────────┼────────────────────────────┤
234 │Move window backward │ ctrl+shift+b │
235 ├──────────────────────┼────────────────────────────┤
236 │Move window to top │ ctrl+shift+` │
237 ├──────────────────────┼────────────────────────────┤
238 │Focus specific window │ ctrl+shift+1, ctrl+shift+2 │
239 │ │ ... ctrl+shift+0 (also │
240 │ │ ⌘+1, ⌘+2 ... ⌘+9 on macOS) │
241 │ │ (clockwise from the │
242 │ │ top-left) │
243 └──────────────────────┴────────────────────────────┘
244 Additionally, you can define shortcuts in kitty.conf to focus neighbor‐
246 ing windows and move windows around (similar to window movement in
247 vim):
248 map ctrl+left neighboring_window left
250 map shift+left move_window right
251 map ctrl+down neighboring_window down
252 map shift+down move_window up
253 ...
254 You can also define a shortcut to switch to the previously active win‐
256 dow:
257 map ctrl+p nth_window -1
259 nth_window will focus the nth window for positive numbers and the pre‐
261 viously active windows for negative numbers.
262 You can define shortcuts to detach the current window and move it to
264 another tab or another OS window:
265 # moves the window into a new OS window
267 map ctrl+f2 detach_window
268 # moves the window into a new Tab
269 map ctrl+f3 detach_window new-tab
270 # asks which tab to move the window into
271 map ctrl+f4 detach_window ask
272 Similarly, you can detach the current tab, with:
274 # moves the tab into a new OS window
276 map ctrl+f2 detach_tab
277 # asks which OS Window to move the tab into
278 map ctrl+f4 detach_tab ask
279 Finally, you can define a shortcut to close all windows in a tab other
281 than the currently active window:
282 map f9 close_other_windows_in_tab
284
286 ┌───────────────────────────┬────────────────────────────┐
287 │Action │ Shortcut │
288 ├───────────────────────────┼────────────────────────────┤
289 │Copy to clipboard │ ctrl+shift+c (also ⌘+c on │
290 │ │ macOS) │
291 ├───────────────────────────┼────────────────────────────┤
292 │Paste from clipboard │ ctrl+shift+v (also ⌘+v on │
293 │ │ macOS) │
294 ├───────────────────────────┼────────────────────────────┤
295 │Paste from selection │ ctrl+shift+s │
296 ├───────────────────────────┼────────────────────────────┤
297 │Increase font size │ ctrl+shift+equal (also ⌘++ │
298 │ │ on macOS) │
299 ├───────────────────────────┼────────────────────────────┤
300 │Decrease font size │ ctrl+shift+minus (also ⌘+- │
301 │ │ on macOS) │
302 ├───────────────────────────┼────────────────────────────┤
303 │Restore font size │ ctrl+shift+backspace (also │
304 │ │ ⌘+0 on macOS) │
305 ├───────────────────────────┼────────────────────────────┤
306 │Toggle fullscreen │ ctrl+shift+f11 (also ^+⌘+f │
307 │ │ on macOS) │
308 ├───────────────────────────┼────────────────────────────┤
309 │Toggle maximized │ ctrl+shift+f10 │
310 ├───────────────────────────┼────────────────────────────┤
311 │Input unicode character │ ctrl+shift+u (also │
312 │ │ ^+⌘+space on macOS) │
313 ├───────────────────────────┼────────────────────────────┤
314 │Click URL using the key‐ │ ctrl+shift+e │
315 │board │ │
316 ├───────────────────────────┼────────────────────────────┤
317 │Reset the terminal │ ctrl+shift+delete │
318 ├───────────────────────────┼────────────────────────────┤
319 │Reload kitty.conf │ ctrl+shift+f5 (also ^+⌘+f5 │
320 │ │ on macOS) │
321 ├───────────────────────────┼────────────────────────────┤
322 │Debug kitty.conf │ ctrl+shift+f6 (also ⌘+op‐ │
323 │ │ tion+f6 on macOS) │
324 ├───────────────────────────┼────────────────────────────┤
325 │Pass current selection to │ ctrl+shift+o │
326 │program │ │
327 ├───────────────────────────┼────────────────────────────┤
328 │Edit kitty config file │ ctrl+shift+f2 │
329 ├───────────────────────────┼────────────────────────────┤
330 │Open a kitty shell │ ctrl+shift+escape │
331 ├───────────────────────────┼────────────────────────────┤
332 │Increase background opac‐ │ ctrl+shift+a>m │
333 │ity │ │
334 └───────────────────────────┴────────────────────────────┘
335 │Decrease background opac‐ │ ctrl+shift+a>l │
337 │ity │ │
338 ├───────────────────────────┼────────────────────────────┤
339 │Full background opacity │ ctrl+shift+a>1 │
340 ├───────────────────────────┼────────────────────────────┤
341 │Reset background opacity │ ctrl+shift+a>d │
342 └───────────────────────────┴────────────────────────────┘
343
345 See kitty.conf(5)
346
348 Kovid Goyal
349
351 2021, Kovid Goyal
3520.21.2 Jul 22, 2021 KITTY(1)