faqvBCrD

1# vim:fileencoding=utf-8:ft=conf:foldmethod=marker
2
3#: Fonts {{{
4
5#: kitty has very powerful font management. You can configure
6#: individual font faces and even specify special fonts for particular
7#: characters.
8
9font_family      monospace
10bold_font        auto
11italic_font      auto
12bold_italic_font auto
13
14#: You can specify different fonts for the bold/italic/bold-italic
15#: variants. To get a full list of supported fonts use the `kitty
16#: list-fonts` command. By default they are derived automatically, by
17#: the OSes font system. Setting them manually is useful for font
18#: families that have many weight variants like Book, Medium, Thick,
19#: etc. For example::
20
21#:     font_family      Operator Mono Book
22#:     bold_font        Operator Mono Medium
23#:     italic_font      Operator Mono Book Italic
24#:     bold_italic_font Operator Mono Medium Italic
25
26font_size 10.0
27
28#: Font size (in pts)
29
30force_ltr no
31
32#: kitty does not support BIDI (bidirectional text), however, for RTL
33#: scripts, words are automatically displayed in RTL. That is to say,
34#: in an RTL script, the words "HELLO WORLD" display in kitty as
35#: "WORLD HELLO", and if you try to select a substring of an RTL-
36#: shaped string, you will get the character that would be there had
37#: the the string been LTR. For example, assuming the Hebrew word
38#: ירושלים, selecting the character that on the screen appears to be ם
39#: actually writes into the selection buffer the character י.
40
41#: kitty's default behavior is useful in conjunction with a filter to
42#: reverse the word order, however, if you wish to manipulate RTL
43#: glyphs, it can be very challenging to work with, so this option is
44#: provided to turn it off. Furthermore, this option can be used with
45#: the command line program GNU FriBidi
46#: <https://github.com/fribidi/fribidi#executable> to get BIDI
47#: support, because it will force kitty to always treat the text as
48#: LTR, which FriBidi expects for terminals.
49
50adjust_line_height  0
51adjust_column_width 0
52
53#: Change the size of each character cell kitty renders. You can use
54#: either numbers, which are interpreted as pixels or percentages
55#: (number followed by %), which are interpreted as percentages of the
56#: unmodified values. You can use negative pixels or percentages less
57#: than 100% to reduce sizes (but this might cause rendering
58#: artifacts).
59
60# symbol_map U+E0A0-U+E0A3,U+E0C0-U+E0C7 PowerlineSymbols
61
62#: Map the specified unicode codepoints to a particular font. Useful
63#: if you need special rendering for some symbols, such as for
64#: Powerline. Avoids the need for patched fonts. Each unicode code
65#: point is specified in the form U+<code point in hexadecimal>. You
66#: can specify multiple code points, separated by commas and ranges
67#: separated by hyphens. symbol_map itself can be specified multiple
68#: times. Syntax is::
69
70#:     symbol_map codepoints Font Family Name
71
72disable_ligatures never
73
74#: Choose how you want to handle multi-character ligatures. The
75#: default is to always render them.  You can tell kitty to not render
76#: them when the cursor is over them by using cursor to make editing
77#: easier, or have kitty never render them at all by using always, if
78#: you don't like them. The ligature strategy can be set per-window
79#: either using the kitty remote control facility or by defining
80#: shortcuts for it in kitty.conf, for example::
81
82#:     map alt+1 disable_ligatures_in active always
83#:     map alt+2 disable_ligatures_in all never
84#:     map alt+3 disable_ligatures_in tab cursor
85
86#: Note that this refers to programming ligatures, typically
87#: implemented using the calt OpenType feature. For disabling general
88#: ligatures, use the font_features setting.
89
90font_features none
91
92#: Choose exactly which OpenType features to enable or disable. This
93#: is useful as some fonts might have features worthwhile in a
94#: terminal. For example, Fira Code Retina includes a discretionary
95#: feature, zero, which in that font changes the appearance of the
96#: zero (0), to make it more easily distinguishable from Ø. Fira Code
97#: Retina also includes other discretionary features known as
98#: Stylistic Sets which have the tags ss01 through ss20.
99
100#: Note that this code is indexed by PostScript name, and not the font
101#: family. This allows you to define very precise feature settings;
102#: e.g. you can disable a feature in the italic font but not in the
103#: regular font.
104
105#: To get the PostScript name for a font, use kitty + list-fonts
106#: --psnames::
107
108#:     $ kitty + list-fonts --psnames | grep Fira
109#:     Fira Code
110#:     Fira Code Bold (FiraCode-Bold)
111#:     Fira Code Light (FiraCode-Light)
112#:     Fira Code Medium (FiraCode-Medium)
113#:     Fira Code Regular (FiraCode-Regular)
114#:     Fira Code Retina (FiraCode-Retina)
115
116#: The part in brackets is the PostScript name.
117
118#: Enable alternate zero and oldstyle numerals::
119
120#:     font_features FiraCode-Retina +zero +onum
121
122#: Enable only alternate zero::
123
124#:     font_features FiraCode-Retina +zero
125
126#: Disable the normal ligatures, but keep the calt feature which (in
127#: this font) breaks up monotony::
128
129#:     font_features TT2020StyleB-Regular -liga +calt
130
131#: In conjunction with force_ltr, you may want to disable Arabic
132#: shaping entirely, and only look at their isolated forms if they
133#: show up in a document. You can do this with e.g.::
134
135#:     font_features UnifontMedium +isol -medi -fina -init
136
137box_drawing_scale 0.001, 1, 1.5, 2
138
139#: Change the sizes of the lines used for the box drawing unicode
140#: characters These values are in pts. They will be scaled by the
141#: monitor DPI to arrive at a pixel value. There must be four values
142#: corresponding to thin, normal, thick, and very thick lines.
143
144#: }}}
145
146#: Cursor customization {{{
147
148cursor #cccccc
149
150#: Default cursor color
151
152cursor_text_color #111111
153
154#: Choose the color of text under the cursor. If you want it rendered
155#: with the background color of the cell underneath instead, use the
156#: special keyword: background
157
158cursor_shape block
159
160#: The cursor shape can be one of (block, beam, underline)
161
162cursor_beam_thickness 1.5
163
164#: Defines the thickness of the beam cursor (in pts)
165
166cursor_underline_thickness 2.0
167
168#: Defines the thickness of the underline cursor (in pts)
169
170cursor_blink_interval -1
171
172#: The interval (in seconds) at which to blink the cursor. Set to zero
173#: to disable blinking. Negative values mean use system default. Note
174#: that numbers smaller than repaint_delay will be limited to
175#: repaint_delay.
176
177cursor_stop_blinking_after 15.0
178
179#: Stop blinking cursor after the specified number of seconds of
180#: keyboard inactivity.  Set to zero to never stop blinking.
181
182#: }}}
183
184#: Scrollback {{{
185
186scrollback_lines 2000
187
188#: Number of lines of history to keep in memory for scrolling back.
189#: Memory is allocated on demand. Negative numbers are (effectively)
190#: infinite scrollback. Note that using very large scrollback is not
191#: recommended as it can slow down resizing of the terminal and also
192#: use large amounts of RAM.
193
194scrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS +INPUT_LINE_NUMBER
195
196#: Program with which to view scrollback in a new window. The
197#: scrollback buffer is passed as STDIN to this program. If you change
198#: it, make sure the program you use can handle ANSI escape sequences
199#: for colors and text formatting. INPUT_LINE_NUMBER in the command
200#: line above will be replaced by an integer representing which line
201#: should be at the top of the screen. Similarly CURSOR_LINE and
202#: CURSOR_COLUMN will be replaced by the current cursor position.
203
204scrollback_pager_history_size 0
205
206#: Separate scrollback history size, used only for browsing the
207#: scrollback buffer (in MB). This separate buffer is not available
208#: for interactive scrolling but will be piped to the pager program
209#: when viewing scrollback buffer in a separate window. The current
210#: implementation stores one character in 4 bytes, so approximatively
211#: 2500 lines per megabyte at 100 chars per line. A value of zero or
212#: less disables this feature. The maximum allowed size is 4GB.
213
214wheel_scroll_multiplier 5.0
215
216#: Modify the amount scrolled by the mouse wheel. Note this is only
217#: used for low precision scrolling devices, not for high precision
218#: scrolling on platforms such as macOS and Wayland. Use negative
219#: numbers to change scroll direction.
220
221touch_scroll_multiplier 1.0
222
223#: Modify the amount scrolled by a touchpad. Note this is only used
224#: for high precision scrolling devices on platforms such as macOS and
225#: Wayland. Use negative numbers to change scroll direction.
226
227#: }}}
228
229#: Mouse {{{
230
231mouse_hide_wait 3.0
232
233#: Hide mouse cursor after the specified number of seconds of the
234#: mouse not being used. Set to zero to disable mouse cursor hiding.
235#: Set to a negative value to hide the mouse cursor immediately when
236#: typing text. Disabled by default on macOS as getting it to work
237#: robustly with the ever-changing sea of bugs that is Cocoa is too
238#: much effort.
239
240url_color #0087bd
241url_style curly
242
243#: The color and style for highlighting URLs on mouse-over. url_style
244#: can be one of: none, single, double, curly
245
246open_url_modifiers kitty_mod
247
248#: The modifier keys to press when clicking with the mouse on URLs to
249#: open the URL
250
251open_url_with default
252
253#: The program with which to open URLs that are clicked on. The
254#: special value default means to use the operating system's default
255#: URL handler.
256
257url_prefixes http https file ftp
258
259#: The set of URL prefixes to look for when detecting a URL under the
260#: mouse cursor.
261
262copy_on_select no
263
264#: Copy to clipboard or a private buffer on select. With this set to
265#: clipboard, simply selecting text with the mouse will cause the text
266#: to be copied to clipboard. Useful on platforms such as macOS that
267#: do not have the concept of primary selections. You can instead
268#: specify a name such as a1 to copy to a private kitty buffer
269#: instead. Map a shortcut with the paste_from_buffer action to paste
270#: from this private buffer. For example::
271
272#:     map cmd+shift+v paste_from_buffer a1
273
274#: Note that copying to the clipboard is a security risk, as all
275#: programs, including websites open in your browser can read the
276#: contents of the system clipboard.
277
278strip_trailing_spaces never
279
280#: Remove spaces at the end of lines when copying to clipboard. A
281#: value of smart will do it when using normal selections, but not
282#: rectangle selections. always will always do it.
283
284rectangle_select_modifiers ctrl+alt
285
286#: The modifiers to use rectangular selection (i.e. to select text in
287#: a rectangular block with the mouse)
288
289terminal_select_modifiers shift
290
291#: The modifiers to override mouse selection even when a terminal
292#: application has grabbed the mouse
293
294select_by_word_characters @-./_~?&=%+#
295
296#: Characters considered part of a word when double clicking. In
297#: addition to these characters any character that is marked as an
298#: alphanumeric character in the unicode database will be matched.
299
300click_interval -1.0
301
302#: The interval between successive clicks to detect double/triple
303#: clicks (in seconds). Negative numbers will use the system default
304#: instead, if available, or fallback to 0.5.
305
306focus_follows_mouse no
307
308#: Set the active window to the window under the mouse when moving the
309#: mouse around
310
311pointer_shape_when_grabbed arrow
312
313#: The shape of the mouse pointer when the program running in the
314#: terminal grabs the mouse. Valid values are: arrow, beam and hand
315
316#: }}}
317
318#: Performance tuning {{{
319
320repaint_delay 10
321
322#: Delay (in milliseconds) between screen updates. Decreasing it,
323#: increases frames-per-second (FPS) at the cost of more CPU usage.
324#: The default value yields ~100 FPS which is more than sufficient for
325#: most uses. Note that to actually achieve 100 FPS you have to either
326#: set sync_to_monitor to no or use a monitor with a high refresh
327#: rate. Also, to minimize latency when there is pending input to be
328#: processed, repaint_delay is ignored.
329
330input_delay 3
331
332#: Delay (in milliseconds) before input from the program running in
333#: the terminal is processed. Note that decreasing it will increase
334#: responsiveness, but also increase CPU usage and might cause flicker
335#: in full screen programs that redraw the entire screen on each loop,
336#: because kitty is so fast that partial screen updates will be drawn.
337
338sync_to_monitor yes
339
340#: Sync screen updates to the refresh rate of the monitor. This
341#: prevents tearing (https://en.wikipedia.org/wiki/Screen_tearing)
342#: when scrolling. However, it limits the rendering speed to the
343#: refresh rate of your monitor. With a very high speed mouse/high
344#: keyboard repeat rate, you may notice some slight input latency. If
345#: so, set this to no.
346
347#: }}}
348
349#: Terminal bell {{{
350
351enable_audio_bell yes
352
353#: Enable/disable the audio bell. Useful in environments that require
354#: silence.
355
356visual_bell_duration 0.0
357
358#: Visual bell duration. Flash the screen when a bell occurs for the
359#: specified number of seconds. Set to zero to disable.
360
361window_alert_on_bell yes
362
363#: Request window attention on bell. Makes the dock icon bounce on
364#: macOS or the taskbar flash on linux.
365
366bell_on_tab yes
367
368#: Show a bell symbol on the tab if a bell occurs in one of the
369#: windows in the tab and the window is not the currently focused
370#: window
371
372command_on_bell none
373
374#: Program to run when a bell occurs.
375
376#: }}}
377
378#: Window layout {{{
379
380remember_window_size  yes
381initial_window_width  640
382initial_window_height 400
383
384#: If enabled, the window size will be remembered so that new
385#: instances of kitty will have the same size as the previous
386#: instance. If disabled, the window will initially have size
387#: configured by initial_window_width/height, in pixels. You can use a
388#: suffix of "c" on the width/height values to have them interpreted
389#: as number of cells instead of pixels.
390
391enabled_layouts *
392
393#: The enabled window layouts. A comma separated list of layout names.
394#: The special value all means all layouts. The first listed layout
395#: will be used as the startup layout. Default configuration is all
396#: layouts in alphabetical order. For a list of available layouts, see
397#: the https://sw.kovidgoyal.net/kitty/index.html#layouts.
398
399window_resize_step_cells 2
400window_resize_step_lines 2
401
402#: The step size (in units of cell width/cell height) to use when
403#: resizing windows. The cells value is used for horizontal resizing
404#: and the lines value for vertical resizing.
405
406window_border_width 1.0
407
408#: The width (in pts) of window borders. Will be rounded to the
409#: nearest number of pixels based on screen resolution. Note that
410#: borders are displayed only when more than one window is visible.
411#: They are meant to separate multiple windows.
412
413draw_minimal_borders yes
414
415#: Draw only the minimum borders needed. This means that only the
416#: minimum needed borders for inactive windows are drawn. That is only
417#: the borders that separate the inactive window from a neighbor. Note
418#: that setting a non-zero window margin overrides this and causes all
419#: borders to be drawn.
420
421window_margin_width 0
422
423#: The window margin (in pts) (blank area outside the border). A
424#: single value sets all four sides. Two values set the vertical and
425#: horizontal sides. Three values set top, horizontal and bottom. Four
426#: values set top, right, bottom and left.
427
428single_window_margin_width -1
429
430#: The window margin (in pts) to use when only a single window is
431#: visible. Negative values will cause the value of
432#: window_margin_width to be used instead. A single value sets all
433#: four sides. Two values set the vertical and horizontal sides. Three
434#: values set top, horizontal and bottom. Four values set top, right,
435#: bottom and left.
436
437window_padding_width 0
438
439#: The window padding (in pts) (blank area between the text and the
440#: window border). A single value sets all four sides. Two values set
441#: the vertical and horizontal sides. Three values set top, horizontal
442#: and bottom. Four values set top, right, bottom and left.
443
444placement_strategy center
445
446#: When the window size is not an exact multiple of the cell size, the
447#: cell area of the terminal window will have some extra padding on
448#: the sides. You can control how that padding is distributed with
449#: this option. Using a value of center means the cell area will be
450#: placed centrally. A value of top-left means the padding will be on
451#: only the bottom and right edges.
452
453active_border_color #00ff00
454
455#: The color for the border of the active window. Set this to none to
456#: not draw borders around the active window.
457
458inactive_border_color #cccccc
459
460#: The color for the border of inactive windows
461
462bell_border_color #ff5a00
463
464#: The color for the border of inactive windows in which a bell has
465#: occurred
466
467inactive_text_alpha 1.0
468
469#: Fade the text in inactive windows by the specified amount (a number
470#: between zero and one, with zero being fully faded).
471
472hide_window_decorations no
473
474#: Hide the window decorations (title-bar and window borders) with
475#: yes. On macOS, titlebar-only can be used to only hide the titlebar.
476#: Whether this works and exactly what effect it has depends on the
477#: window manager/operating system.
478
479resize_debounce_time 0.1
480
481#: The time (in seconds) to wait before redrawing the screen when a
482#: resize event is received. On platforms such as macOS, where the
483#: operating system sends events corresponding to the start and end of
484#: a resize, this number is ignored.
485
486resize_draw_strategy static
487
488#: Choose how kitty draws a window while a resize is in progress. A
489#: value of static means draw the current window contents, mostly
490#: unchanged. A value of scale means draw the current window contents
491#: scaled. A value of blank means draw a blank window. A value of size
492#: means show the window size in cells.
493
494resize_in_steps no
495
496#: Resize the OS window in steps as large as the cells, instead of
497#: with the usual pixel accuracy. Combined with an
498#: initial_window_width and initial_window_height in number of cells,
499#: this option can be used to keep the margins as small as possible
500#: when resizing the OS window. Note that this does not currently work
501#: on Wayland.
502
503confirm_os_window_close 0
504
505#: Ask for confirmation when closing an OS window or a tab that has at
506#: least this number of kitty windows in it. A value of zero disables
507#: confirmation. This confirmation also applies to requests to quit
508#: the entire application (all OS windows, via the quit action).
509
510#: }}}
511
512#: Tab bar {{{
513
514tab_bar_edge bottom
515
516#: Which edge to show the tab bar on, top or bottom
517
518tab_bar_margin_width 0.0
519
520#: The margin to the left and right of the tab bar (in pts)
521
522tab_bar_style fade
523
524#: The tab bar style, can be one of: fade, separator, powerline, or
525#: hidden. In the fade style, each tab's edges fade into the
526#: background color, in the separator style, tabs are separated by a
527#: configurable separator, and the powerline shows the tabs as a
528#: continuous line.
529
530tab_bar_min_tabs 2
531
532#: The minimum number of tabs that must exist before the tab bar is
533#: shown
534
535tab_switch_strategy previous
536
537#: The algorithm to use when switching to a tab when the current tab
538#: is closed. The default of previous will switch to the last used
539#: tab. A value of left will switch to the tab to the left of the
540#: closed tab. A value of last will switch to the right-most tab.
541
542tab_fade 0.25 0.5 0.75 1
543
544#: Control how each tab fades into the background when using fade for
545#: the tab_bar_style. Each number is an alpha (between zero and one)
546#: that controls how much the corresponding cell fades into the
547#: background, with zero being no fade and one being full fade. You
548#: can change the number of cells used by adding/removing entries to
549#: this list.
550
551tab_separator " ┇"
552
553#: The separator between tabs in the tab bar when using separator as
554#: the tab_bar_style.
555
556tab_title_template "{title}"
557
558#: A template to render the tab title. The default just renders the
559#: title. If you wish to include the tab-index as well, use something
560#: like: {index}: {title}. Useful if you have shortcuts mapped for
561#: goto_tab N. In addition you can use {layout_name} for the current
562#: layout name and {num_windows} for the number of windows in the tab.
563#: Note that formatting is done by Python's string formatting
564#: machinery, so you can use, for instance, {layout_name[:2].upper()}
565#: to show only the first two letters of the layout name, upper-cased.
566
567active_tab_title_template none
568
569#: Template to use for active tabs, if not specified falls back to
570#: tab_title_template.
571
572active_tab_foreground   #000
573active_tab_background   #eee
574active_tab_font_style   bold-italic
575inactive_tab_foreground #444
576inactive_tab_background #999
577inactive_tab_font_style normal
578
579#: Tab bar colors and styles
580
581tab_bar_background none
582
583#: Background color for the tab bar. Defaults to using the terminal
584#: background color.
585
586#: }}}
587
588#: Color scheme {{{
589
590foreground #e6e8ef
591background #1c1e22
592
593#: The foreground and background colors
594
595background_opacity 1.0
596
597#: The opacity of the background. A number between 0 and 1, where 1 is
598#: opaque and 0 is fully transparent.  This will only work if
599#: supported by the OS (for instance, when using a compositor under
600#: X11). Note that it only sets the background color's opacity in
601#: cells that have the same background color as the default terminal
602#: background. This is so that things like the status bar in vim,
603#: powerline prompts, etc. still look good.  But it means that if you
604#: use a color theme with a background color in your editor, it will
605#: not be rendered as transparent.  Instead you should change the
606#: default background color in your kitty config and not use a
607#: background color in the editor color scheme. Or use the escape
608#: codes to set the terminals default colors in a shell script to
609#: launch your editor.  Be aware that using a value less than 1.0 is a
610#: (possibly significant) performance hit.  If you want to dynamically
611#: change transparency of windows set dynamic_background_opacity to
612#: yes (this is off by default as it has a performance cost)
613
614background_image none
615
616#: Path to a background image. Must be in PNG format.
617
618background_image_layout tiled
619
620#: Whether to tile or scale the background image.
621
622background_image_linear no
623
624#: When background image is scaled, whether linear interpolation
625#: should be used.
626
627dynamic_background_opacity no
628
629#: Allow changing of the background_opacity dynamically, using either
630#: keyboard shortcuts (increase_background_opacity and
631#: decrease_background_opacity) or the remote control facility.
632
633background_tint 0.0
634
635#: How much to tint the background image by the background color. The
636#: tint is applied only under the text area, not margin/borders. Makes
637#: it easier to read the text. Tinting is done using the current
638#: background color for each window. This setting applies only if
639#: background_opacity is set and transparent windows are supported or
640#: background_image is set.
641
642dim_opacity 0.75
643
644#: How much to dim text that has the DIM/FAINT attribute set. One
645#: means no dimming and zero means fully dimmed (i.e. invisible).
646
647selection_foreground #000000
648
649#: The foreground for text selected with the mouse. A value of none
650#: means to leave the color unchanged.
651
652selection_background #fffacd
653
654#: The background for text selected with the mouse.
655
656
657#: The 16 terminal colors. There are 8 basic colors, each color has a
658#: dull and bright version. You can also set the remaining colors from
659#: the 256 color table as color16 to color255.
660
661color0 #23252b
662color8 #23252b
663
664#: black
665
666color1 #b54036
667color9 #b54036
668
669#: red
670
671color2  #5ab977
672color10 #5ab977
673
674#: green
675
676color3  #deb566
677color11 #deb566
678
679#: yellow
680
681color4  #6a7c93
682color12 #6a7c93
683
684#: blue
685
686color5  #a4799d
687color13 #a4799d
688
689#: magenta
690
691color6  #3f94a8
692color14 #3f94a8
693
694#: cyan
695
696color7  #e6e8ef
697color15 #ebedf2
698
699#: white
700
701mark1_foreground black
702
703#: Color for marks of type 1
704
705mark1_background #98d3cb
706
707#: Color for marks of type 1 (light steel blue)
708
709mark2_foreground black
710
711#: Color for marks of type 2
712
713mark2_background #f2dcd3
714
715#: Color for marks of type 1 (beige)
716
717mark3_foreground black
718
719#: Color for marks of type 3
720
721mark3_background #f274bc
722
723#: Color for marks of type 1 (violet)
724
725#: }}}
726
727#: Advanced {{{
728
729shell .
730
731#: The shell program to execute. The default value of . means to use
732#: whatever shell is set as the default shell for the current user.
733#: Note that on macOS if you change this, you might need to add
734#: --login to ensure that the shell starts in interactive mode and
735#: reads its startup rc files.
736
737editor .
738
739#: The console editor to use when editing the kitty config file or
740#: similar tasks. A value of . means to use the environment variables
741#: VISUAL and EDITOR in that order. Note that this environment
742#: variable has to be set not just in your shell startup scripts but
743#: system-wide, otherwise kitty will not see it.
744
745close_on_child_death no
746
747#: Close the window when the child process (shell) exits. If no (the
748#: default), the terminal will remain open when the child exits as
749#: long as there are still processes outputting to the terminal (for
750#: example disowned or backgrounded processes). If yes, the window
751#: will close as soon as the child process exits. Note that setting it
752#: to yes means that any background processes still using the terminal
753#: can fail silently because their stdout/stderr/stdin no longer work.
754
755allow_remote_control no
756
757#: Allow other programs to control kitty. If you turn this on other
758#: programs can control all aspects of kitty, including sending text
759#: to kitty windows, opening new windows, closing windows, reading the
760#: content of windows, etc.  Note that this even works over ssh
761#: connections. You can chose to either allow any program running
762#: within kitty to control it, with yes or only programs that connect
763#: to the socket specified with the kitty --listen-on command line
764#: option, if you use the value socket-only. The latter is useful if
765#: you want to prevent programs running on a remote computer over ssh
766#: from controlling kitty.
767
768listen_on none
769
770#: Tell kitty to listen to the specified unix/tcp socket for remote
771#: control connections. Note that this will apply to all kitty
772#: instances. It can be overridden by the kitty --listen-on command
773#: line flag. This option accepts only UNIX sockets, such as
774#: unix:${TEMP}/mykitty or (on Linux) unix:@mykitty. Environment
775#: variables are expanded. If {kitty_pid} is present then it is
776#: replaced by the PID of the kitty process, otherwise the PID of the
777#: kitty process is appended to the value, with a hyphen. This option
778#: is ignored unless you also set allow_remote_control to enable
779#: remote control. See the help for kitty --listen-on for more
780#: details.
781
782# env 
783
784#: Specify environment variables to set in all child processes. Note
785#: that environment variables are expanded recursively, so if you
786#: use::
787
788#:     env MYVAR1=a
789#:     env MYVAR2=${MYVAR1}/${HOME}/b
790
791#: The value of MYVAR2 will be a/<path to home directory>/b.
792
793update_check_interval 24
794
795#: Periodically check if an update to kitty is available. If an update
796#: is found a system notification is displayed informing you of the
797#: available update. The default is to check every 24 hrs, set to zero
798#: to disable.
799
800startup_session none
801
802#: Path to a session file to use for all kitty instances. Can be
803#: overridden by using the kitty --session command line option for
804#: individual instances. See
805#: https://sw.kovidgoyal.net/kitty/index.html#sessions in the kitty
806#: documentation for details. Note that relative paths are interpreted
807#: with respect to the kitty config directory. Environment variables
808#: in the path are expanded.
809
810clipboard_control write-clipboard write-primary
811
812#: Allow programs running in kitty to read and write from the
813#: clipboard. You can control exactly which actions are allowed. The
814#: set of possible actions is: write-clipboard read-clipboard write-
815#: primary read-primary. You can additionally specify no-append to
816#: disable kitty's protocol extension for clipboard concatenation. The
817#: default is to allow writing to the clipboard and primary selection
818#: with concatenation enabled. Note that enabling the read
819#: functionality is a security risk as it means that any program, even
820#: one running on a remote server via SSH can read your clipboard.
821
822term xterm-kitty
823
824#: The value of the TERM environment variable to set. Changing this
825#: can break many terminal programs, only change it if you know what
826#: you are doing, not because you read some advice on Stack Overflow
827#: to change it. The TERM variable is used by various programs to get
828#: information about the capabilities and behavior of the terminal. If
829#: you change it, depending on what programs you run, and how
830#: different the terminal you are changing it to is, various things
831#: from key-presses, to colors, to various advanced features may not
832#: work.
833
834#: }}}
835
836#: OS specific tweaks {{{
837
838macos_titlebar_color system
839
840#: Change the color of the kitty window's titlebar on macOS. A value
841#: of system means to use the default system color, a value of
842#: background means to use the background color of the currently
843#: active window and finally you can use an arbitrary color, such as
844#: #12af59 or red. WARNING: This option works by using a hack, as
845#: there is no proper Cocoa API for it. It sets the background color
846#: of the entire window and makes the titlebar transparent. As such it
847#: is incompatible with background_opacity. If you want to use both,
848#: you are probably better off just hiding the titlebar with
849#: hide_window_decorations.
850
851macos_option_as_alt no
852
853#: Use the option key as an alt key. With this set to no, kitty will
854#: use the macOS native Option+Key = unicode character behavior. This
855#: will break any Alt+key keyboard shortcuts in your terminal
856#: programs, but you can use the macOS unicode input technique. You
857#: can use the values: left, right, or both to use only the left,
858#: right or both Option keys as Alt, instead.
859
860macos_hide_from_tasks no
861
862#: Hide the kitty window from running tasks (Option+Tab) on macOS.
863
864macos_quit_when_last_window_closed no
865
866#: Have kitty quit when all the top-level windows are closed. By
867#: default, kitty will stay running, even with no open windows, as is
868#: the expected behavior on macOS.
869
870macos_window_resizable yes
871
872#: Disable this if you want kitty top-level (OS) windows to not be
873#: resizable on macOS.
874
875macos_thicken_font 0
876
877#: Draw an extra border around the font with the given width, to
878#: increase legibility at small font sizes. For example, a value of
879#: 0.75 will result in rendering that looks similar to sub-pixel
880#: antialiasing at common font sizes.
881
882macos_traditional_fullscreen no
883
884#: Use the traditional full-screen transition, that is faster, but
885#: less pretty.
886
887macos_show_window_title_in all
888
889#: Show or hide the window title in the macOS window or menu-bar. A
890#: value of window will show the title of the currently active window
891#: at the top of the macOS window. A value of menubar will show the
892#: title of the currently active window in the macOS menu-bar, making
893#: use of otherwise wasted space. all will show the title everywhere
894#: and none hides the title in the window and the menu-bar.
895
896macos_custom_beam_cursor no
897
898#: Enable/disable custom mouse cursor for macOS that is easier to see
899#: on both light and dark backgrounds. WARNING: this might make your
900#: mouse cursor invisible on dual GPU machines.
901
902linux_display_server auto
903
904#: Choose between Wayland and X11 backends. By default, an appropriate
905#: backend based on the system state is chosen automatically. Set it
906#: to x11 or wayland to force the choice.
907
908#: }}}
909
910#: Keyboard shortcuts {{{
911
912#: For a list of key names, see: the GLFW key macros
913#: <https://github.com/kovidgoyal/kitty/blob/master/glfw/glfw3.h#L349>.
914#: The name to use is the part after the GLFW_KEY_ prefix. For a list
915#: of modifier names, see: GLFW mods
916#: <https://www.glfw.org/docs/latest/group__mods.html>
917
918#: On Linux you can also use XKB key names to bind keys that are not
919#: supported by GLFW. See XKB keys
920#: <https://github.com/xkbcommon/libxkbcommon/blob/master/xkbcommon/xkbcommon-
921#: keysyms.h> for a list of key names. The name to use is the part
922#: after the XKB_KEY_ prefix. Note that you can only use an XKB key
923#: name for keys that are not known as GLFW keys.
924
925#: Finally, you can use raw system key codes to map keys, again only
926#: for keys that are not known as GLFW keys. To see the system key
927#: code for a key, start kitty with the kitty --debug-keyboard option.
928#: Then kitty will output some debug text for every key event. In that
929#: text look for ``native_code`` the value of that becomes the key
930#: name in the shortcut. For example:
931
932#: .. code-block:: none
933
934#:     on_key_input: glfw key: 65 native_code: 0x61 action: PRESS mods: 0x0 text: 'a'
935
936#: Here, the key name for the A key is 0x61 and you can use it with::
937
938#:     map ctrl+0x61 something
939
940#: to map ctrl+a to something.
941
942#: You can use the special action no_op to unmap a keyboard shortcut
943#: that is assigned in the default configuration::
944
945#:     map kitty_mod+space no_op
946
947#: You can combine multiple actions to be triggered by a single
948#: shortcut, using the syntax below::
949
950#:     map key combine <separator> action1 <separator> action2 <separator> action3 ...
951
952#: For example::
953
954#:     map kitty_mod+e combine : new_window : next_layout
955
956#: this will create a new window and switch to the next available
957#: layout
958
959#: You can use multi-key shortcuts using the syntax shown below::
960
961#:     map key1>key2>key3 action
962
963#: For example::
964
965#:     map ctrl+f>2 set_font_size 20
966
967kitty_mod ctrl+shift
968
969#: The value of kitty_mod is used as the modifier for all default
970#: shortcuts, you can change it in your kitty.conf to change the
971#: modifiers for all the default shortcuts.
972
973clear_all_shortcuts no
974
975#: You can have kitty remove all shortcut definition seen up to this
976#: point. Useful, for instance, to remove the default shortcuts.
977
978# kitten_alias hints hints --hints-offset=0
979
980#: You can create aliases for kitten names, this allows overriding the
981#: defaults for kitten options and can also be used to shorten
982#: repeated mappings of the same kitten with a specific group of
983#: options. For example, the above alias changes the default value of
984#: kitty +kitten hints --hints-offset to zero for all mappings,
985#: including the builtin ones.
986
987#: Clipboard {{{
988
989map kitty_mod+c copy_to_clipboard
990
991#: There is also a copy_or_interrupt action that can be optionally
992#: mapped to Ctrl+c. It will copy only if there is a selection and
993#: send an interrupt otherwise. Similarly, copy_and_clear_or_interrupt
994#: will copy and clear the selection or send an interrupt if there is
995#: no selection.
996
997map kitty_mod+v  paste_from_clipboard
998map kitty_mod+s  paste_from_selection
999map shift+insert paste_from_selection
1000map kitty_mod+o  pass_selection_to_program
1001
1002#: You can also pass the contents of the current selection to any
1003#: program using pass_selection_to_program. By default, the system's
1004#: open program is used, but you can specify your own, the selection
1005#: will be passed as a command line argument to the program, for
1006#: example::
1007
1008#:     map kitty_mod+o pass_selection_to_program firefox
1009
1010#: You can pass the current selection to a terminal program running in
1011#: a new kitty window, by using the @selection placeholder::
1012
1013#:     map kitty_mod+y new_window less @selection
1014
1015#: }}}
1016
1017#: Scrolling {{{
1018
1019map kitty_mod+up        scroll_line_up
1020map kitty_mod+k         scroll_line_up
1021map kitty_mod+down      scroll_line_down
1022map kitty_mod+j         scroll_line_down
1023map kitty_mod+page_up   scroll_page_up
1024map kitty_mod+page_down scroll_page_down
1025map kitty_mod+home      scroll_home
1026map kitty_mod+end       scroll_end
1027map kitty_mod+h         show_scrollback
1028
1029#: You can pipe the contents of the current screen + history buffer as
1030#: STDIN to an arbitrary program using the ``launch`` function. For
1031#: example, the following opens the scrollback buffer in less in an
1032#: overlay window::
1033
1034#:     map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting --type=overlay less +G -R
1035
1036#: For more details on piping screen and buffer contents to external
1037#: programs, see launch.
1038
1039#: }}}
1040
1041#: Window management {{{
1042
1043map kitty_mod+enter new_window
1044
1045#: You can open a new window running an arbitrary program, for
1046#: example::
1047
1048#:     map kitty_mod+y      launch mutt
1049
1050#: You can open a new window with the current working directory set to
1051#: the working directory of the current window using::
1052
1053#:     map ctrl+alt+enter    launch --cwd=current
1054
1055#: You can open a new window that is allowed to control kitty via the
1056#: kitty remote control facility by prefixing the command line with @.
1057#: Any programs running in that window will be allowed to control
1058#: kitty. For example::
1059
1060#:     map ctrl+enter launch --allow-remote-control some_program
1061
1062#: You can open a new window next to the currently active window or as
1063#: the first window, with::
1064
1065#:     map ctrl+n launch --location=neighbor some_program
1066#:     map ctrl+f launch --location=first some_program
1067
1068#: For more details, see launch.
1069
1070map kitty_mod+n new_os_window
1071
1072#: Works like new_window above, except that it opens a top level OS
1073#: kitty window. In particular you can use new_os_window_with_cwd to
1074#: open a window with the current working directory.
1075
1076map kitty_mod+w close_window
1077map kitty_mod+] next_window
1078map kitty_mod+[ previous_window
1079map kitty_mod+f move_window_forward
1080map kitty_mod+b move_window_backward
1081map kitty_mod+` move_window_to_top
1082map kitty_mod+r start_resizing_window
1083map kitty_mod+1 first_window
1084map kitty_mod+2 second_window
1085map kitty_mod+3 third_window
1086map kitty_mod+4 fourth_window
1087map kitty_mod+5 fifth_window
1088map kitty_mod+6 sixth_window
1089map kitty_mod+7 seventh_window
1090map kitty_mod+8 eighth_window
1091map kitty_mod+9 ninth_window
1092map kitty_mod+0 tenth_window
1093#: }}}
1094
1095#: Tab management {{{
1096
1097map kitty_mod+right next_tab
1098map kitty_mod+left  previous_tab
1099map kitty_mod+t     new_tab
1100map kitty_mod+q     close_tab
1101map kitty_mod+.     move_tab_forward
1102map kitty_mod+,     move_tab_backward
1103map kitty_mod+alt+t set_tab_title
1104
1105#: You can also create shortcuts to go to specific tabs, with 1 being
1106#: the first tab, 2 the second tab and -1 being the previously active
1107#: tab, and any number larger than the last tab being the last tab::
1108
1109#:     map ctrl+alt+1 goto_tab 1
1110#:     map ctrl+alt+2 goto_tab 2
1111
1112#: Just as with new_window above, you can also pass the name of
1113#: arbitrary commands to run when using new_tab and use
1114#: new_tab_with_cwd. Finally, if you want the new tab to open next to
1115#: the current tab rather than at the end of the tabs list, use::
1116
1117#:     map ctrl+t new_tab !neighbor [optional cmd to run]
1118#: }}}
1119
1120#: Layout management {{{
1121
1122map kitty_mod+l next_layout
1123
1124#: You can also create shortcuts to switch to specific layouts::
1125
1126#:     map ctrl+alt+t goto_layout tall
1127#:     map ctrl+alt+s goto_layout stack
1128
1129#: Similarly, to switch back to the previous layout::
1130
1131#:    map ctrl+alt+p last_used_layout
1132#: }}}
1133
1134#: Font sizes {{{
1135
1136#: You can change the font size for all top-level kitty OS windows at
1137#: a time or only the current one.
1138
1139map kitty_mod+equal     change_font_size all +2.0
1140map kitty_mod+minus     change_font_size all -2.0
1141map kitty_mod+backspace change_font_size all 0
1142
1143#: To setup shortcuts for specific font sizes::
1144
1145#:     map kitty_mod+f6 change_font_size all 10.0
1146
1147#: To setup shortcuts to change only the current OS window's font
1148#: size::
1149
1150#:     map kitty_mod+f6 change_font_size current 10.0
1151#: }}}
1152
1153#: Select and act on visible text {{{
1154
1155#: Use the hints kitten to select text and either pass it to an
1156#: external program or insert it into the terminal or copy it to the
1157#: clipboard.
1158
1159map kitty_mod+e kitten hints
1160
1161#: Open a currently visible URL using the keyboard. The program used
1162#: to open the URL is specified in open_url_with.
1163
1164map kitty_mod+p>f kitten hints --type path --program -
1165
1166#: Select a path/filename and insert it into the terminal. Useful, for
1167#: instance to run git commands on a filename output from a previous
1168#: git command.
1169
1170map kitty_mod+p>shift+f kitten hints --type path
1171
1172#: Select a path/filename and open it with the default open program.
1173
1174map kitty_mod+p>l kitten hints --type line --program -
1175
1176#: Select a line of text and insert it into the terminal. Use for the
1177#: output of things like: ls -1
1178
1179map kitty_mod+p>w kitten hints --type word --program -
1180
1181#: Select words and insert into terminal.
1182
1183map kitty_mod+p>h kitten hints --type hash --program -
1184
1185#: Select something that looks like a hash and insert it into the
1186#: terminal. Useful with git, which uses sha1 hashes to identify
1187#: commits
1188
1189map kitty_mod+p>n kitten hints --type linenum
1190
1191#: Select something that looks like filename:linenum and open it in
1192#: vim at the specified line number.
1193
1194
1195#: The hints kitten has many more modes of operation that you can map
1196#: to different shortcuts. For a full description see kittens/hints.
1197#: }}}
1198
1199#: Miscellaneous {{{
1200
1201map kitty_mod+f11    toggle_fullscreen
1202map kitty_mod+f10    toggle_maximized
1203map kitty_mod+u      kitten unicode_input
1204map kitty_mod+f2     edit_config_file
1205map kitty_mod+escape kitty_shell window
1206
1207#: Open the kitty shell in a new window/tab/overlay/os_window to
1208#: control kitty using commands.
1209
1210map kitty_mod+a>m    set_background_opacity +0.1
1211map kitty_mod+a>l    set_background_opacity -0.1
1212map kitty_mod+a>1    set_background_opacity 1
1213map kitty_mod+a>d    set_background_opacity default
1214map kitty_mod+delete clear_terminal reset active
1215
1216#: You can create shortcuts to clear/reset the terminal. For example::
1217
1218#:     # Reset the terminal
1219#:     map kitty_mod+f9 clear_terminal reset active
1220#:     # Clear the terminal screen by erasing all contents
1221#:     map kitty_mod+f10 clear_terminal clear active
1222#:     # Clear the terminal scrollback by erasing it
1223#:     map kitty_mod+f11 clear_terminal scrollback active
1224#:     # Scroll the contents of the screen into the scrollback
1225#:     map kitty_mod+f12 clear_terminal scroll active
1226
1227#: If you want to operate on all windows instead of just the current
1228#: one, use all instead of active.
1229
1230#: It is also possible to remap Ctrl+L to both scroll the current
1231#: screen contents into the scrollback buffer and clear the screen,
1232#: instead of just clearing the screen::
1233
1234#:     map ctrl+l combine : clear_terminal scroll active : send_text normal,application \x0c
1235
1236
1237#: You can tell kitty to send arbitrary (UTF-8) encoded text to the
1238#: client program when pressing specified shortcut keys. For example::
1239
1240#:     map ctrl+alt+a send_text all Special text
1241
1242#: This will send "Special text" when you press the ctrl+alt+a key
1243#: combination.  The text to be sent is a python string literal so you
1244#: can use escapes like \x1b to send control codes or \u21fb to send
1245#: unicode characters (or you can just input the unicode characters
1246#: directly as UTF-8 text). The first argument to send_text is the
1247#: keyboard modes in which to activate the shortcut. The possible
1248#: values are normal or application or kitty or a comma separated
1249#: combination of them.  The special keyword all means all modes. The
1250#: modes normal and application refer to the DECCKM cursor key mode
1251#: for terminals, and kitty refers to the special kitty extended
1252#: keyboard protocol.
1253
1254#: Another example, that outputs a word and then moves the cursor to
1255#: the start of the line (same as pressing the Home key)::
1256
1257#:     map ctrl+alt+a send_text normal Word\x1b[H
1258#:     map ctrl+alt+a send_text application Word\x1bOH
1259
1260#: }}}
1261
1262# }}}