1KHAL(1) khal KHAL(1)
2
6 khal - khal Documentation
7 Khal is a calendar program for the terminal for viewing, adding and
9 editing events and calendars. Khal is build on the iCalendar and vdir
10 (allowing the use of vdirsyncer(1) for CalDAV compatibility) standards.
11
13 Khal offers a set of commands, most importantly list, calendar, inter‐
14 active, new, printcalendars, printformats, and search. See below for a
15 description of what every command does. khal does currently not support
16 any default command, i.e., run a command, even though none has been
17 specified. This is intentional.
18 Options
20 khal (without any commands) has some options to print some information
21 about khal:
22 --version
24 Prints khal's version number and exits
25 -h, --help
27 Prints a summary of khal's options and commands and then exits
28 Several options are common to almost all of khal's commands (exceptions
30 are described below):
31 -v, --verbosity LVL
33 Configure verbosity (e.g. print debugging information), LVL
34 needs to be one of CRITICAL, ERROR, WARNING, INFO, or DEBUG.
35 -l, --logfile LOFILE
37 Use logfile LOGFILE for logging, default is logging to stdout.
38 -c CONFIGFILE
40 Use an alternate configuration file.
41 -a CALENDAR
43 Specify a calendar to use (which must be configured in the con‐
44 figuration file), can be used several times. Calendars not spec‐
45 ified will be disregarded for this run.
46 -d CALENDAR
48 Specify a calendar which will be disregarded for this run, can
49 be used several times.
50 --color/--no-color
52 khal will detect if standard output is not a tty, e.g., you re‐
53 direct khal's output into a file, and if so remove all high‐
54 lighting/coloring from its output. Use --color if you want to
55 force highlighting/coloring and --no-color if you want coloring
56 always removed.
57 --format FORMAT
59 For all of khal's commands that print events, the formatting of
60 that event can be specified with this option. FORMAT is a tem‐
61 plate string, in which identifiers delimited by curly braces
62 ({}) will be expanded to an event's properties. FORMAT supports
63 all formatting options offered by python's str.format()
64 <https://docs.python.org/3/library/string.html#formatstrings>
65 (as it is used internally). The available template options are:
66 title The title of the event.
68 description
70 The description of the event.
71 description-separator
73 A separator: " :: " that appears when there is a descrip‐
74 tion.
75 uid The UID of the event.
77 start The start datetime in datetimeformat.
79 start-long
81 The start datetime in longdatetimeformat.
82 start-date
84 The start date in dateformat.
85 start-date-long
87 The start date in longdateformat.
88 start-time
90 The start time in timeformat.
91 end The end datetime in datetimeformat.
93 end-long
95 The end datetime in longdatetimeformat.
96 end-date
98 The end date in dateformat.
99 end-date-long
101 The end date in longdateformat.
102 end-time
104 The end time in timeformat.
105 repeat-symbol
107 A repeating symbol (loop arrow) if the event is repeat‐
108 ing.
109 alarm-symbol
111 An alarm symbol (alarm clock) if the event has at least
112 one alarm.
113 location
115 The event location.
116 calendar
118 The calendar name.
119 calendar-color
121 Changes the output color to the calendar's color.
122 start-style
124 The start time in timeformat OR an appropriate symbol.
125 to-style
127 A hyphen "-" or nothing such that it appropriately fits
128 between start-style and end-style.
129 end-style
131 The end time in timeformat OR an appropriate symbol.
132 start-end-time-style
134 A concatenation of start-style, to-style, and end-style
135 OR an appropriate symbol.
136 end-necessary
138 For an allday event this is an empty string unless the
139 end date and start date are different. For a non-allday
140 event this will show the time or the datetime if the
141 event start and end date are different.
142 end-necessary-long
144 Same as end-necessary but uses datelong and datetimelong.
145 status The status of the event (if this event has one), some‐
147 thing like CONFIRMED or CANCELLED.
148 cancelled
150 The string CANCELLED (plus one blank) if the event's sta‐
151 tus is cancelled, otherwise nothing.
152 organizer
154 The organizer of the event. If the format has CN then it
155 returns "CN (email)" if CN does not exist it returns just
156 the email string. Example: ORGANIZER;CN=Name Sur‐
157 name:mailto:name@mail.com returns Name Surname
158 (name@mail.com) and if it has no CN attribute it returns
159 the last element after the colon: ORGA‐
160 NIZER;SENT-BY="mailto:toe‐
161 mail@mail.com":mailto:name@mail.com returns name@mail.com
162 url The URL embedded in the event, otherwise nothing.
164 By default, all-day events have no times. To see a start and end
166 time anyway simply add -full to the end of any template with
167 start/end, for instance start-time becomes start-time-full and
168 will always show start and end times (instead of being empty for
169 all-day events).
170 In addition, there are colors: black, red, green, yellow, blue,
172 magenta, cyan, white (and their bold versions: red-bold, etc.).
173 There is also reset, which clears the styling, and bold, which
174 is the normal bold.
175 A few control codes are exposed. You can access newline (nl),
177 'tab', and 'bell'. Control codes, such as nl, are best used
178 with --list mode.
179 Below is an example command which prints the title and descrip‐
181 tion of all events today.
182 khal list --format "{title} {description}"
184 --day-format DAYFORMAT
186 works similar to --format, but for day headings. It only has a
187 few options (in addition to all the color options):
188 date The date in dateformat.
190 date-long
192 The date in longdateformat.
193 name The date's name (Monday, Tuesday,…) or today or tomorrow.
195 If the --day-format is passed an empty string then it will not
197 print the day headers (for an empty line pass in a whitespace
198 character).
199 dates
201 Almost everywhere khal accepts dates, khal should recognize relative
202 date names like today, tomorrow and the names of the days of the week
203 (also in three letters abbreviated form). Week day names get inter‐
204 preted as the date of the next occurrence of a day with that name. The
205 name of the current day gets interpreted as that date next week (i.e.
206 seven days from now).
207 If a short datetime format is used (no year is given), khal will inter‐
209 pret the date to be in the future. The inferred it might be in the next
210 year if the given date has already passed in the current year.
211 Commands
213 list
214 shows all events scheduled for a given date (or datetime) range, with
215 custom formatting:
216 khal list [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
218 [--day-format DAYFORMAT] [--once] [--notstarted] [START [END | DELTA] ]
219 START and END can both be given as dates, datetimes or times (it is as‐
221 sumed today is meant in the case of only a given time) in the formats
222 configured in the configuration file. If END is not given, midnight of
223 the start date is assumed. Today is used for START if it is not explic‐
224 itly given. If DELTA, a (date)time range in the format I{m,h,d}, where
225 I is an integer and m means minutes, h means hours, and d means days,
226 is given, END is assumed to be START + DELTA. A value of eod is also
227 accepted as DELTA and means the end of day of the start date. In addi‐
228 tion, the DELTA week may be used to specify that the daterange should
229 actually be the week containing the START.
230 The --once option only allows events to appear once even if they are on
232 multiple days. With the --notstarted option only events are shown that
233 start after START.
234 at
236 shows all events scheduled for a given datetime. khal at should be sup‐
237 plied with a date and time, a time (the date is then assumed to be to‐
238 day) or the string now. at defaults to now. The at command works just
239 like the list command, except it has an implicit end time of zero min‐
240 utes after the start.
241 khal at [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
243 [--notstarted] [[START DATE] TIME | now]
244 calendar
246 shows a calendar (similar to cal(1)) and list. khal calendar should un‐
247 derstand the following syntax:
248 khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME]
250 [END DATETIME]
251 Date selection works exactly as for khal list. The displayed calendar
253 contains three consecutive months, where the first month is the month
254 containing the first given date. If today is included, it is high‐
255 lighted. Have a look at khal list for a description of the options.
256 configure
258 will help users creating an initial configuration file. configure will
259 refuse to run if there already is a configuration file.
260 import
262 lets the user import .ics files with the following syntax:
263 khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE
265 If an event with the same UID is already present in the (implicitly)
267 selected calendar khal import will ask before updating (i.e. overwrit‐
268 ing) that old event with the imported one, unless --batch is given,
269 than it will always update. If this behaviour is not desired, use the
270 --random-uid flag to generate a new, random UID. If no calendar is
271 specified (and not --batch), you will be asked to choose a calendar.
272 You can either enter the number printed behind each calendar's name or
273 any unique prefix of a calendar's name.
274 interactive
276 invokes the interactive version of khal, can also be invoked by calling
277 ikhal. While ikhal can be used entirely with the keyboard, some ele‐
278 ments respond if clicked on with a mouse (mostly by being selected).
279 When the calendar on the left is in focus, you can
281 • move through the calendar (default keybindings are the arrow keys,
283 space and backspace, those keybindings are configurable in the
284 config file)
285 • focus on the right column by pressing tab or enter
287 • re-focus on the current date, default keybinding t as in today
289 • marking a date range, default keybinding v, as in visual, think
291 visual mode in Vim, pressing esc escapes this visual mode
292 • if in visual mode, you can select the other end of the currently
294 marked range, default keybinding o as in other (again as in Vim)
295 • create a new event on the currently focused day (or date range if
297 a range is selected), default keybinding n as in new
298 • search for events, default keybinding /, a pop-up will ask for
300 your search term
301 When an event list is in focus, you can
303 • view an event's details with pressing enter (or tab) and edit it
305 with pressing enter (or tab) again (if [default] event_view_al‐
306 ways_visible is set to True, the event in focus will always be
307 shown in detail)
308 • toggle an event's deletion status, default keybinding d as in
310 delete, events marked for deletion will appear with a D in front
311 and will be deleted when khal exits.
312 • duplicate the selected event, default keybinding p as in duplicate
314 (d was already taken)
315 • export the selected event, default keybinding e
317 In the event editor, you can
319 • jump to the next (previous) selectable element with pressing tab
321 (shift+tab)
322 • quick save, default keybinding meta+enter (meta will probably be alt)
324 • use some common editing short cuts in most text fields (ctrl+w
326 deletes word before cursor, ctrl+u (ctrl+k) deletes till the begin‐
327 ning (end) of the line, ctrl+a (ctrl+e) will jump to the beginning
328 (end) of the line
329 • in the date and time fields you can increment and decrement the num‐
331 ber under the cursor with ctrl+a and ctrl+x (time in 15 minute steps)
332 • in the date fields you can access a miniature calendar by pressing
334 enter
335 • activate actions by pressing enter on text enclosed by angled brack‐
337 ets, e.g. < Save > (sometimes this might open a pop up)
338 Pressing esc will cancel the current action and/or take you back to the
340 previously shown pane (i.e. what you see when you open ikhal), if you
341 are at the start pane, ikhal will quit on pressing esc again.
342 new
344 allows for adding new events. khal new should understand the following
345 syntax:
346 khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
348 [:: DESCRIPTION]]
349 where start- and enddatetime are either datetimes, times, or keywords
351 and times in the formats defined in the config file. If no calendar is
352 given via -a, the default calendar is used. new does not support -d and
353 also -a may only be used once.
354 new accepts these combinations for start and endtimes (specifying the
356 end is always optional):
357 • datetime [datetime|time] [timezone]
359 • time [time] [timezone]
361 • date [date]
363 where the formats for datetime and time are as follows:
365 • datetime = (longdatetimeformat|datetimeformat|keyword-date time‐
367 format)
368 • time = timeformat
370 • date = (longdateformat|dateformat)
372 and timezone, which describes the timezone the events start and end
374 time are in, should be a valid Olson DB identifier (like Europe/Berlin
375 or America/New_York. If no timezone is given, the defaulttimezone as
376 configured in the configuration file is used instead.
377 The exact format of longdatetimeformat, datetimeformat, timeformat,
379 longdateformat and dateformat can be configured in the configuration
380 file. Valid keywords for dates are today, tomorrow, the English name
381 of all seven weekdays and their three letter abbreviations (their next
382 occurrence is used).
383 If no end is given, the default length of one hour or one day (for
385 all-day events) is used. If only a start time is given the new event is
386 assumed to be starting today. If only a time is given for the event to
387 end on, the event ends on the same day it starts on, unless that would
388 make the event end before it has started, then the next day is used as
389 end date
390 If a 24:00 time is configured (timeformat = %H:%M) an end time of 24:00
392 is accepted as the end of a given date.
393 If the summary contains the string ::, everything after :: is taken as
395 the description of the new event, i.e., the "body" of the event (and ::
396 will be removed).
397 Passing the option --interactive (-i) makes all arguments optional and
399 interactively prompts for required fields, then the event may be
400 edited, the same way as in the edit command.
401 Options
403 • -l, --location=LOCATION specify where this event will be held.
404 • -g, --categories=CATEGORIES specify which categories this event be‐
406 longs to. Comma separated list of categories. Beware: some servers
407 (e.g. SOGo) do not support multiple categories.
408 • -r, --repeat=RRULE specify if and how this event should be recurring.
410 Valid values for RRULE are daily, weekly, monthly and yearly
411 • -u, --until=UNTIL specify until when a recurring event should run
413 • --url specify the URL element of the event
415 • --alarms DURATION,... will add alarm times as DELTAs comma separated
417 for this event, DURATION should look like 1day 10minutes or 1d3H10m,
418 negative DURATIONs will set alarm after the start of the event.
419 Examples
421 These may need to be adapted for your configuration and/or locale
422 (START and END need to match the format configured). See printformats.
423 khal new 18:00 Awesome Event
425 adds a new event starting today at 18:00 with summary 'awesome event'
427 (lasting for the default time of one hour) to the default calendar
428 khal new tomorrow 16:30 Coffee Break
430 adds a new event tomorrow at 16:30
432 khal new 25.10. 18:00 24:00 Another Event :: with Alice and Bob
434 adds a new event on 25th of October lasting from 18:00 to 24:00 with an
436 additional description
437 khal new -a work 26.07. Great Event -g meeting -r weekly
439 adds a new all day event on 26th of July to the calendar work in the
441 meeting category, which recurs every week.
442 edit
444 an interactive command for editing and deleting events using a search
445 string
446 khal edit [--show-past] event_search_string
448 the command will loop through all events that match the search string,
450 prompting the user to delete, or change attributes.
451 printcalendars
453 prints a list of all configured calendars.
454 printformats
456 prints a fixed date (2013-12-21 21:45) in all configured date(time)
457 formats. This is supposed to help check if those formats are config‐
458 ured as intended.
459 search
461 search for events matching a search string and print them. Currently,
462 search will print one line for every different event in a recurrence
463 set, that is one line for the master event, and one line for every dif‐
464 ferent overwritten event. No advanced search features are currently
465 supported.
466 The command
468 khal search party
470 prints all events matching party.
472
474 khal reads configuration files in the ini syntax, meaning it under‐
475 stands keys separated from values by a =, while section and subsection
476 names are enclosed by single or double square brackets (like [section‐
477 name] and [[subsectionname]]). Any line beginning with a # will be
478 treated as a comment.
479 Help with initial configuration
481 If you do not have a configuration file yet, running khal configure
482 will launch a small, interactive tool that should help you with initial
483 configuration of khal.
484 Location of configuration file
486 khal is looking for configuration files in the following places and or‐
487 der: $XDG_CONFIG_HOME/khal/config (on most systems this is ~/.con‐
488 fig/khal/config), ~/.khal/khal.conf (deprecated) and a file called
489 khal.conf in the current directory (deprecated). Alternatively you can
490 specify which configuration file to use with -c path/to/config at run‐
491 time.
492 The [calendars] section
494 The [calendars] section is mandatory and must contain at least one sub‐
495 section. Every subsection must have a unique name (enclosed by two
496 square brackets). Each subsection needs exactly one path setting, ev‐
497 erything else is optional. Here is a small example:
498 [calendars]
500 [[home]]
502 path = ~/.calendars/home/
503 color = dark green
504 priority = 20
505 [[work]]
507 path = ~/.calendars/work/
508 readonly = True
509 color khal will use this color for coloring this calendar's event.
512 The following color names are supported: black, white, brown,
513 yellow, dark gray, dark green, dark blue, light gray, light
514 green, light blue, dark magenta, dark cyan, dark red, light ma‐
515 genta, light cyan, light red. Depending on your terminal emula‐
516 tor's settings, they might look different than what their name
517 implies. In addition to the 16 named colors an index from the
518 256-color palette or a 24-bit color code can be used, if your
519 terminal supports this. The 256-color palette index is simply a
520 number between 0 and 255. The 24-bit color must be given as
521 #RRGGBB, where RR, GG, BB is the hexadecimal value of the red,
522 green and blue component, respectively. When using a 24-bit
523 color, make sure to enclose the color value in ' or "! If color
524 is set to auto (the default), khal looks for a color value in a
525 color file in this calendar's vdir. If the color file does not
526 exist, the default_color (see below) is used. If color is set to
527 '', the default_color is always used. Note that you can use
528 vdirsyncer metasync to synchronize colors with your caldav
529 server.
530 type color
532 default
534 auto
535 path The path to an existing directory where this calendar is saved
537 as a vdir. The directory is searched for events or birthdays
538 (see type). The path also accepts glob expansion via * or ? when
539 type is set to discover. ** means arbitrary depths of directo‐
540 ries. This allows for paths such as ~/accounts/*/calendars/*,
541 where the calendars directory contains vdir directories. In ad‐
542 dition, ~/calendars/* and ~/calendars/default are valid paths if
543 there exists a vdir in the default directory. (The previous be‐
544 havior of recursively searching directories has been replaced
545 with globbing).
546 type string
548 default
550 None
551 priority
553 When coloring days, the color will be determined based on the
554 calendar with the highest priority. If the priorities are equal,
555 then the "multiple" color will be used.
556 type integer
558 default
560 10
561 readonly
563 setting this to True, will keep khal from making any changes to
564 this calendar
565 type boolean
567 default
569 False
570 type Setting the type of this collection (default calendar).
572 If set to calendar (the default), this collection will be used
574 as a standard calendar, that is, only files with the .ics exten‐
575 sion will be considered, all other files are ignored (except for
576 a possible color file).
577 If set to birthdays khal will expect a VCARD collection and ex‐
579 tract birthdays from those VCARDS, that is only files with .vcf
580 extension will be considered, all other files will be ignored.
581 birthdays also implies readonly=True.
582 If set to discover, khal will use globbing
584 <https://en.wikipedia.org/wiki/Glob_(programming)> to expand
585 this calendar's path to (possibly) several paths and use those
586 as individual calendars (this cannot be used with birthday col‐
587 lections`). See Exemplary discover usage for an example.
588 If an individual calendar vdir has a color file, the calendar's
590 color will be set to the one specified in the color file, other‐
591 wise the color from the calendars subsection will be used.
592 type option, allowed values are calendar, birthdays and
594 discover
595 default
597 calendar
598 The [default] section
600 Some default values and behaviors are set here.
601 default_calendar
603 The calendar to use if none is specified for some operation
604 (e.g. if adding a new event). If this is not set, such opera‐
605 tions require an explicit value.
606 type string
608 default
610 None
611 default_dayevent_duration
613 Define the default duration for an event ('khal new' only)
614 type timedelta
616 default
618 1h
619 default_event_duration
621 Define the defaut duration for a day-long event ('khal new'
622 only)
623 type timedelta
625 default
627 1d
628 highlight_event_days
630 If true, khal will highlight days with events. Options for high‐
631 lighting are in [highlight_days] section.
632 type boolean
634 default
636 False
637 print_new
639 After adding a new event, what should be printed to standard
640 out? The whole event in text form, the path to where the event
641 is now saved or nothing?
642 type option, allowed values are event, path and False
644 default
646 False
647 show_all_days
649 By default, khal displays only dates with events in list or cal‐
650 endar view. Setting this to True will show all days, even when
651 there is no event scheduled on that day.
652 type boolean
654 default
656 False
657 timedelta
659 Controls for how many days into the future we show events (for
660 example, in khal list) by default.
661 type timedelta
663 default
665 2d
666 The [highlight_days] section
668 When highlight_event_days is enabled, this section specifies how the
669 highlighting/coloring of days is handled.
670 color What color to use when highlighting -- explicit color or use
672 calendar color when set to ''
673 type color
675 default
677 default_color
679 Default color for calendars without color -- when set to '' it
680 actually disables highlighting for events that should use the
681 default color.
682 type color
684 default
686 method Highlighting method to use -- foreground or background
688 type option, allowed values are foreground, fg, background
690 and bg
691 default
693 fg
694 multiple
696 How to color days with events from multiple calendars -- either
697 explicit color or use calendars' colors when set to ''
698 type color
700 default
702 multiple_on_overflow
704 When multiple is set to a specific color, setting this to True
705 will cause khal to use that color only for days with events from
706 3 or more calendars (hence preserving the two-color-highlight
707 for days where all calendar colors can be displayed)
708 type boolean
710 default
712 False
713 The [keybindings] section
715 Keybindings for ikhal are set here. You can bind more than one key
716 (combination) to a command by supplying a comma-separated list of keys.
717 For binding key combinations concatenate them keys (with a space in be‐
718 tween), e.g. ctrl n.
719 delete delete the currently selected event
721 type list
723 default
725 d
726 down move the cursor down (in the calendar browser)
728 type list
730 default
732 down, j
733 duplicate
735 duplicate the currently selected event
736 type list
738 default
740 p
741 export export event as a .ics file
743 type list
745 default
747 e
748 external_edit
750 edit the currently selected events' raw .ics file with $EDITOR
751 Only use this, if you know what you are doing, the icalendar li‐
752 brary we use doesn't do a lot of validation, it silently disre‐
753 gards most invalid data.
754 type list
756 default
758 meta E
759 left move the cursor left (in the calendar browser)
761 type list
763 default
765 left, h, backspace
766 log show logged messages
768 type list
770 default
772 L
773 mark go into highlight (visual) mode to choose a date range
775 type list
777 default
779 v
780 new create a new event on the selected date
782 type list
784 default
786 n
787 other in highlight mode go to the other end of the highlighted date
789 range
790 type list
792 default
794 o
795 quit quit
797 type list
799 default
801 q, Q
802 right move the cursor right (in the calendar browser)
804 type list
806 default
808 right, l, space
809 save save the currently edited event and leave the event editor
811 type list
813 default
815 meta enter
816 search open a text field to start a search for events
818 type list
820 default
822 /
823 today focus the calendar browser on today
825 type list
827 default
829 t
830 up move the cursor up (in the calendar browser)
832 type list
834 default
836 up, k
837 view show details or edit (if details are already shown) the cur‐
839 rently selected event
840 type list
842 default
844 enter
845 The [locale] section
847 It is mandatory to set (long)date-, time-, and datetimeformat options,
848 all others options in the [locale] section are optional and have (sen‐
849 sible) defaults.
850 dateformat
852 khal will display and understand all dates in this format, see
853 timeformat for the format
854 type string
856 default
858 %x
859 datetimeformat
861 khal will display and understand all datetimes in this format,
862 see timeformat for the format.
863 type string
865 default
867 %c
868 default_timezone
870 this timezone will be used for new events (when no timezone is
871 specified) and when khal does not understand the timezone speci‐
872 fied in the icalendar file. If no timezone is set, the timezone
873 your computer is set to will be used.
874 type timezone
876 default
878 None
879 firstweekday
881 the first day of the week, where Monday is 0 and Sunday is 6
882 type integer, allowed values are between 0 and 6
884 default
886 0
887 local_timezone
889 khal will show all times in this timezone If no timezone is set,
890 the timezone your computer is set to will be used.
891 type timezone
893 default
895 None
896 longdateformat
898 khal will display and understand all dates in this format, it
899 should contain a year (e.g. %Y) see timeformat for the format.
900 type string
902 default
904 %x
905 longdatetimeformat
907 khal will display and understand all datetimes in this format,
908 it should contain a year (e.g. %Y) see timeformat for the for‐
909 mat.
910 type string
912 default
914 %c
915 timeformat
917 khal will display and understand all times in this format.
918 The formatting string is interpreted as defined by Python's
920 strftime <https://docs.python.org/3/library/time.html#time.strf‐
921 time>, which is similar to the format specified in man strftime.
922 In the configuration file it may be necessary to enclose the
924 format in quotation marks to force it to be loaded as a string.
925 type string
927 default
929 %X
930 unicode_symbols
932 by default khal uses some unicode symbols (as in 'non-ascii') as
933 indicators for things like repeating events, if your font, en‐
934 coding etc. does not support those symbols, set this to False
935 (this will enable ascii based replacements).
936 type boolean
938 default
940 True
941 weeknumbers
943 Enable weeknumbers in calendar and interactive (ikhal) mode by
944 specifying whether they should be displayed on the 'left' or
945 'right'. These are iso weeknumbers, so will only work properly
946 if firstweekday is set to 0
947 type weeknumbers
949 default
951 off
952 The [sqlite] section
954 path khal stores its internal caching database here, by default this
955 will be in the $XDG_DATA_HOME/khal/khal.db (this will most
956 likely be ~/.local/share/khal/khal.db).
957 type string
959 default
961 None
962 The [view] section
964 The view section contains configuration options that effect the visual
965 appearance when using khal and ikhal.
966 agenda_day_format
968 Specifies how each day header is formatted.
969 type string
971 default
973 {bold}{name}, {date-long}{reset}
974 agenda_event_format
976 Default formatting for events used when the user asks for all
977 events in a given time range, used for list, calendar and in in‐
978 teractive (ikhal). Please note, that any color styling will be
979 ignored in ikhal, where events will always be shown in the color
980 of the calendar they belong to. The syntax is the same as for
981 --format.
982 type string
984 default
986 {calendar-color}{cancelled}{start-end-time-style} {ti‐
987 tle}{repeat-symbol}{alarm-symbol}{description-separa‐
988 tor}{description}{reset}
989 blank_line_before_day
991 Add a blank line before the name of the day (khal only)
992 type boolean
994 default
996 False
997 bold_for_light_color
999 Whether to use bold text for light colors or not. Non-bold light
1000 colors may not work on all terminals but allow using light back‐
1001 ground colors.
1002 type boolean
1004 default
1006 True
1007 dynamic_days
1009 Defines the behaviour of ikhal's right column. If True, the
1010 right column will show events for as many days as fit, moving
1011 the cursor through the list will also select the appropriate day
1012 in the calendar column on the left. If False, only a fixed ([de‐
1013 fault] timedelta) amount of days' events will be shown, moving
1014 through events will not change the focus in the left column.
1015 type boolean
1017 default
1019 True
1020 event_format
1022 Default formatting for events used when the start- and end-date
1023 are not clear through context, e.g. for search, used almost ev‐
1024 erywhere but list and calendar. It is therefore probably a sen‐
1025 sible choice to include the start- and end-date. The syntax is
1026 the same as for --format.
1027 type string
1029 default
1031 {calendar-color}{cancelled}{start}-{end} {title}{re‐
1032 peat-symbol}{alarm-symbol}{description-separator}{de‐
1033 scription}{reset}
1034 event_view_always_visible
1036 Set to true to always show the event view window when looking at
1037 the event list
1038 type boolean
1040 default
1042 False
1043 event_view_weighting
1045 weighting that is applied to the event view window
1046 type integer
1048 default
1050 1
1051 frame Whether to show a visible frame (with box drawing characters)
1053 around some (groups of) elements or not. There are currently
1054 several different frame options available, that should visually
1055 differentiate whether an element is in focus or not. Some of
1056 them will probably be removed in future releases of khal, so
1057 please try them out and give feedback on which style you prefer
1058 (the color of all variants can be defined in the color themes).
1059 type option, allowed values are False, width, color and top
1061 default
1063 False
1064 min_calendar_display
1066 Minimum number of months displayed by calendar command default
1067 is 3 months
1068 type integer
1070 default
1072 3
1073 monthdisplay
1075 Display month name on row when the week contains the first day
1076 of the month ('firstday') or when the first day of the week is
1077 in the month ('firstfullweek')
1078 type monthdisplay
1080 default
1082 firstday
1083 theme Choose a color theme for khal.
1085 This is very much work in progress. Help is really welcome! The
1087 two currently available color schemes (dark and light) are de‐
1088 fined in khal/ui/colors.py, you can either help improve those or
1089 create a new one (see below). As ikhal uses urwid, have a look
1090 at urwid's documentation <http://urwid.org/manual/displayat‐
1091 tributes.html> for how to set colors and/or at the existing
1092 schemes. If you cannot change the color of an element (or have
1093 any other problems) please open an issue on github.
1094 If you want to create your own color scheme, copy the structure
1096 of the existing ones, give it a new and unique name and also add
1097 it as an option in khal/settings/khal.spec in the section [de‐
1098 fault] of the property theme.
1099 type option, allowed values are dark and light
1101 default
1103 dark
1104 A minimal sample configuration could look like this:
1106 Example
1108 [calendars]
1109 [[home]]
1110 path = ~/.calendars/home/
1111 [[work]]
1113 path = ~/.calendars/work/
1114 [locale]
1116 local_timezone= Europe/Berlin
1117 default_timezone= Europe/Berlin
1118 timeformat= %H:%M
1119 dateformat= %d.%m.
1120 longdateformat= %d.%m.%Y
1121 datetimeformat= %d.%m. %H:%M
1122 longdatetimeformat= %d.%m.%Y %H:%M
1123 Exemplary discover usage
1126 If you have the following directory layout:
1127 ~/calendars
1129 ├- work/
1130 ├- home/
1131 └─ family/
1132 where work, home and family are all different vdirs, each containing
1134 one calendar, a matching calendar section could look like this:
1135 [[calendars]]
1137 path = ~/calendars/*
1138 type = discover
1139 color = dark green
1140 Syncing
1142 To get khal working with CalDAV you will first need to setup vdirsyncer
1143 <https://github.com/pimutils/vdirsyncer>. After each start khal will
1144 automatically check if anything has changed and automatically update
1145 its caching db (this may take some time after the initial sync, espe‐
1146 cially for large calendar collections). Therefore, you might want to
1147 execute khal automatically after syncing with vdirsyncer (e.g. via
1148 cron).
1149
1151 khal tries to follow standards and RFCs (most importantly RFC 5545
1152 <https://datatracker.ietf.org/doc/html/rfc5545.html> iCalendar) wher‐
1153 ever possible. Known intentional and unintentional deviations are
1154 listed below.
1155 RDATE;VALUE=PERIOD
1157 RDATE s with PERIOD values are currently not supported, as icalendar
1158 <https://github.com/collective/icalendar> does not support it yet.
1159 Please submit any real world examples of events with RDATE;VALUE=PERIOD
1160 you might encounter (khal will print warnings if you have any in your
1161 calendars).
1162 RANGE=THISANDPRIOR
1164 Recurrent events with the RANGE=THISANDPRIOR are and will not be [1]
1165 supported by khal, as applications supporting the latest standard
1166 <http://tools.ietf.org/html/rfc5546> MUST NOT create those. khal will
1167 print a warning if it encounters an event containing RANGE=THISAND‐
1168 PRIOR.
1169 [1] unless a lot of users request this feature
1171 Events with neither END nor DURATION
1173 While the RFC states:
1174 A calendar entry with a "DTSTART" property but no "DTEND"
1176 property does not take up any time. It is intended to represent
1177 an event that is associated with a given calendar date and time
1178 of day, such as an anniversary. Since the event does not take up
1179 any time, it MUST NOT be used to record busy time no matter what
1180 the value for the "TRANSP" property.
1181 khal transforms those events into all-day events lasting for one day
1183 (the start date). As long a those events do not get edited, these
1184 changes will not be written to the vdir (and with that to the CalDAV
1185 server). Any timezone information that was associated with the start
1186 date gets discarded.
1187 NOTE:
1189 While the main rationale for this behaviour was laziness on part of
1190 khal's main author, other calendar software shows the same behaviour
1191 (e.g. Google Calendar and Evolution).
1192 Timezones
1194 Getting localized time right, seems to be the most difficult part about
1195 calendaring (and messing it up ends in missing the one important meet‐
1196 ing of the week). So I'll briefly describe here, how khal tries to han‐
1197 dle timezone information, which information it can handle and which it
1198 can't.
1199 In general, there are two different type of events. Localized events
1201 (with localized start and end datetimes) which have timezone informa‐
1202 tion attached to their start and end datetimes, and floating events
1203 (with floating start and end datetimes), which have no timezone infor‐
1204 mation attached (all-day events, events that last for complete days are
1205 floating as well). Localized events are always observed at the same UTC
1206 <https://en.wikipedia.org/wiki/Coordinated_Universal_Time> (no matter
1207 what time zone the observer is in), but different local times. On the
1208 other hand, floating events are always observed at the same local time,
1209 which might be different in UTC.
1210 In khal all localized datetimes are saved to the local database as UTC.
1212 Datetimes that are already UTC, e.g. 19980119T070000Z, are saved as
1213 such, others are converted to UTC (but don't worry, the timezone infor‐
1214 mation does not get lost). Floating events get saved in floating time,
1215 independently of the localized events.
1216 If you want to look up which events take place at a specified datetime,
1218 khal always expects that you want to know what events take place at
1219 that local datetime. Therefore, the (local) datetime you asked for gets
1220 converted to UTC, the appropriate localized events get selected and
1221 presented with their start and end datetimes converted to your local
1222 datetime. For floating events no conversion is necessary.
1223 Khal (i.e. icalendar <https://github.com/collective/icalendar>) can un‐
1225 derstand all timezone identifiers as used in the Olson DB
1226 <https://en.wikipedia.org/wiki/Tz_database> and custom timezone defini‐
1227 tions, if those VTIMEZONE components are placed before the VEVENTS that
1228 make use of them (as most calendar programs seem to do). In case an un‐
1229 known (or unsupported) timezone is found, khal will assume you want
1230 that event to be placed in the default timezone (which can be config‐
1231 ured in the configuration file as well).
1232 khal expects you always want all start and end datetimes displayed in
1234 local time (which can be set in the configuration file as well, other‐
1235 wise your computer's timezone is used).
1236
1238 Frequently asked questions:
1239 •
1241 Installation stops with an error: source/str_util.c:25:20: fatal er‐
1243 ror: Python.h: No such file or directory
1244 You do not have the Python development headers installed, on
1245 Debian based Distributions you can install them via aptitude
1246 install python-dev.
1247 •
1249 unknown key "default_command"
1251 This key was deprecated by f8d9135. See
1252 https://github.com/pimutils/khal/issues/648 for the rationale
1253 behind this removal.
1254
1256 khal is released under the Expat/MIT License:
1257 Copyright (c) 2013-2022 khal contributors
1259 Permission is hereby granted, free of charge, to any person obtaining a copy of
1261 this software and associated documentation files (the "Software"), to deal in
1262 the Software without restriction, including without limitation the rights to
1263 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
1264 the Software, and to permit persons to whom the Software is furnished to do so,
1265 subject to the following conditions:
1266 The above copyright notice and this permission notice shall be included in all
1268 copies or substantial portions of the Software.
1269 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1271 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
1272 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
1273 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
1274 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
1275 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1276
1278 Christan Geier et al.
1279
1281 Copyright (c) 2013-2022 khal contributors
12820.11.2 Aug 02, 2023 KHAL(1)