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. Calling khal without any com‐
16 mand will invoke the default command, which can be specified in the
17 configuration file.
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 Be more verbose (e.g. print debugging information)
33 -c CONFIGFILE
35 Use an alternate configuration file
36 -a CALENDAR
38 Specify a calendar to use (which must be configured in the con‐
39 figuration file), can be used several times. Calendars not spec‐
40 ified will be disregarded for this run.
41 -d CALENDAR
43 Specify a calendar which will be disregarded for this run, can
44 be used several times.
45 --color/--no-color
47 khal will detect if standard output is not a tty, e.g., you re‐
48 direct khal's output into a file, and if so remove all high‐
49 lighting/coloring from its output. Use --color if you want to
50 force highlighting/coloring and --no-color if you want coloring
51 always removed.
52 --format FORMAT
54 For all of khal's commands that print events, the formatting of
55 that event can be specified with this option. FORMAT is a tem‐
56 plate string, in which identifiers delimited by curly braces
57 ({}) will be expanded to an event's properties. FORMAT supports
58 all formatting options offered by python's str.format()
59 <https://docs.python.org/3/library/string.html#formatstrings>
60 (as it is used internally). The available template options are:
61 title The title of the event.
63 description
65 The description of the event.
66 start The start datetime in datetimeformat.
68 start-long
70 The start datetime in longdatetimeformat.
71 start-date
73 The start date in dateformat.
74 start-date-long
76 The start date in longdateformat.
77 start-time
79 The start time in timeformat.
80 end The end datetime in datetimeformat.
82 end-long
84 The end datetime in longdatetimeformat.
85 end-date
87 The end date in dateformat.
88 end-date-long
90 The end date in longdateformat.
91 end-time
93 The end time in timeformat.
94 repeat-symbol
96 A repeating symbol (loop arrow) if the event is repeat‐
97 ing.
98 description
100 The event description.
101 description-separator
103 A separator: " :: " that appears when there is a descrip‐
104 tion.
105 location
107 The event location.
108 calendar
110 The calendar name.
111 calendar-color
113 Changes the output color to the calendar's color.
114 start-style
116 The start time in timeformat OR an appropriate symbol.
117 to-style
119 A hyphen "-" or nothing such that it appropriately fits
120 between start-style and end-style.
121 end-style
123 The end time in timeformat OR an appropriate symbol.
124 start-end-time-style
126 A concatenation of start-style, to-style, and end-style
127 OR an appropriate symbol.
128 end-necessary
130 For an allday event this is an empty string unless the
131 end date and start date are different. For a non-allday
132 event this will show the time or the datetime if the
133 event start and end date are different.
134 end-necessary-long
136 Same as end-necessary but uses datelong and datetimelong.
137 status The status of the event (if this event has one), some‐
139 thing like CONFIRMED or CANCELLED.
140 cancelled
142 The string CANCELLED (plus one blank) if the event's sta‐
143 tus is cancelled, otherwise nothing.
144 By default, all-day events have no times. To see a start and end
146 time anyway simply add -full to the end of any template with
147 start/end, for instance start-time becomes start-time-full and
148 will always show start and end times (instead of being empty for
149 all-day events).
150 In addition, there are colors: black, red, green, yellow, blue,
152 magenta, cyan, white (and their bold versions: red-bold, etc.).
153 There is also reset, which clears the styling, and bold, which
154 is the normal bold.
155 For example the below command with print the title and descrip‐
157 tion of all events today.
158 khal list --format "{title} {description}"
160 --day-format DAYFORMAT
162 works similar to --format, but for day headings. It only has a
163 few options (in addition to all the color options):
164 date The date in dateformat.
166 date-long
168 The date in longdateformat.
169 name The date's name (Monday, Tuesday,…) or today or tomorrow.
171 If the --day-format is passed an empty string then it will not
173 print the day headers (for an empty line pass in a whitespace
174 character).
175 dates
177 Almost everywhere khal accepts dates, khal should recognize relative
178 date names like today, tomorrow and the names of the days of the week
179 (also in three letters abbreviated form). Week day names get inter‐
180 preted as the date of the next occurrence of a day with that name. The
181 name of the current day gets interpreted as that date next week (i.e.
182 seven days from now).
183 Commands
185 list
186 shows all events scheduled for a given date (or datetime) range, with
187 custom formatting:
188 khal list [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
190 [--day-format DAYFORMAT] [--once] [--notstarted] [START [END | DELTA] ]
191 START and END can both be given as dates, datetimes or times (it is as‐
193 sumed today is meant in the case of only a given time) in the formats
194 configured in the configuration file. If END is not given, midnight of
195 the start date is assumed. Today is used for START if it is not explic‐
196 itly given. If DELTA, a (date)time range in the format I{m,h,d}, where
197 I is an integer and m means minutes, h means hours, and d means days,
198 is given, END is assumed to be START + DELTA. A value of eod is also
199 accepted as DELTA and means the end of day of the start date. In addi‐
200 tion, the DELTA week may be used to specify that the daterange should
201 actually be the week containing the START.
202 The --once option only allows events to appear once even if they are on
204 multiple days. With the --notstarted option only events are shown that
205 start after START.
206 at
208 shows all events scheduled for a given datetime. khal at should be sup‐
209 plied with a date and time, a time (the date is then assumed to be to‐
210 day) or the string now. at defaults to now. The at command works just
211 like the list command, except it has an implicit end time of zero min‐
212 utes after the start.
213 khal at [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
215 [--notstarted] [[START DATE] TIME | now]
216 calendar
218 shows a calendar (similar to cal(1)) and list. khal calendar should un‐
219 derstand the following syntax:
220 khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME]
222 [END DATETIME]
223 Date selection works exactly as for khal list. The displayed calendar
225 contains three consecutive months, where the first month is the month
226 containing the first given date. If today is included, it is high‐
227 lighted. Have a look at khal list for a description of the options.
228 configure
230 will help users creating an initial configuration file. configure will
231 refuse to run if there already is a configuration file.
232 import
234 lets the user import .ics files with the following syntax:
235 khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE
237 If an event with the same UID is already present in the (implicitly)
239 selected calendar khal import will ask before updating (i.e. overwrit‐
240 ing) that old event with the imported one, unless --batch is given,
241 than it will always update. If this behaviour is not desired, use the
242 --random-uid flag to generate a new, random UID. If no calendar is
243 specified (and not --batch), you will be asked to choose a calendar.
244 You can either enter the number printed behind each calendar's name or
245 any unique prefix of a calendar's name.
246 interactive
248 invokes the interactive version of khal, can also be invoked by calling
249 ikhal. While ikhal can be used entirely with the keyboard, some ele‐
250 ments respond if clicked on with a mouse (mostly by being selected).
251 When the calendar on the left is in focus, you can
253 • move through the calendar (default keybindings are the arrow keys,
255 space and backspace, those keybindings are configurable in the
256 config file)
257 • focus on the right column by pressing tab or enter
259 • re-focus on the current date, default keybinding t as in today
261 • marking a date range, default keybinding v, as in visual, think
263 visual mode in Vim, pressing esc escape this visual mode
264 • if in visual mode, you can select the other end of the currently
266 marked range, default keybinding o as in other (again as in Vim)
267 • create a new event on the currently focused day (or date range if
269 a range is selected), default keybinding n as in new
270 • search for events, default keybinding /, a pop-up will ask for
272 your search term
273 When an event list is in focus, you can
275 • view an event's details with pressing enter (or tab) and edit it
277 with pressing enter (or tab) again (if [default] event_view_al‐
278 ways_visible is set to True, the event in focus will always be
279 shown in detail)
280 • toggle an event's deletion status, default keybinding d as in
282 delete, events marked for deletion will appear with a D in front
283 and will be deleted when khal exits.
284 • duplicate the selected event, default keybinding p as in duplicate
286 (d was already taken)
287 • export the selected event, default keybinding e
289 In the event editor, you can
291 • jump to the next (previous) selectable element with pressing tab
293 (shift+tab)
294 • quick save, default keybinding meta+enter (meta will probably be alt)
296 • use some common editing short cuts in most text fields (ctrl+w
298 deletes word before cursor, ctrl+u (ctrl+k) deletes till the begin‐
299 ning (end) of the line, ctrl+a (ctrl+e) will jump to the beginning
300 (end) of the line
301 • in the date and time field you can increment and decrement the number
303 under the cursor with ctrl+a and ctrl+x (time in 15 minute steps)
304 • activate actions by pressing enter on text enclosed by angled brack‐
306 ets, e.g. < Save > (sometimes this might open a pop up)
307 Pressing esc will cancel the current action and/or take you back to the
309 previously shown pane (i.e. what you see when you open ikhal), if you
310 are at the start pane, ikhal will quit on pressing esc again.
311 new
313 allows for adding new events. khal new should understand the following
314 syntax:
315 khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
317 [:: DESCRIPTION]]
318 where start- and enddatetime are either datetimes, times, or keywords
320 and times in the formats defined in the config file. If no calendar is
321 given via -a, the default calendar is used. new does not support -d and
322 also -a may only be used once.
323 new accepts these combinations for start and endtimes (specifying the
325 end is always optional):
326 • datetime [datetime|time] [timezone]
328 • time [time] [timezone]
330 • date [date]
332 where the formats for datetime and time are as follows:
334 • datetime = (longdatetimeformat|datetimeformat|keyword-date time‐
336 format)
337 • time = timeformat
339 • date = (longdateformat|dateformat)
341 and timezone, which describes the timezone the events start and end
343 time are in, should be a valid Olson DB identifier (like Europe/Berlin
344 or America/New_York. If no timezone is given, the defaulttimezone as
345 configured in the configuration file is used instead.
346 The exact format of longdatetimeformat, datetimeformat, timeformat,
348 longdateformat and dateformat can be configured in the configuration
349 file. Valid keywords for dates are today, tomorrow, the English name
350 of all seven weekdays and their three letter abbreviations (their next
351 occurrence is used).
352 If no end is given, the default length of one hour or one day (for
354 all-day events) is used. If only a start time is given the new event is
355 assumed to be starting today. If only a time is given for the event to
356 end on, the event ends on the same day it starts on, unless that would
357 make the event end before it has started, then the next day is used as
358 end date
359 If a 24:00 time is configured (timeformat = %H:%M) an end time of 24:00
361 is accepted as the end of a given date.
362 If the summary contains the string ::, everything after :: is taken as
364 the description of the new event, i.e., the "body" of the event (and ::
365 will be removed).
366 Passing the option --interactive (-i) makes all arguments optional and
368 interactively prompts for required fields, then the event may be
369 edited, the same way as in the edit command.
370 Options
372 • -l, --location=LOCATION specify where this event will be held.
373 • -g, --categories=CATEGORIES specify which categories this event be‐
375 longs to. Comma separated list of categories. Beware: some servers
376 (e.g. SOGo) do not support multiple categories.
377 • -r, --repeat=RRULE specify if and how this event should be recurring.
379 Valid values for RRULE are daily, weekly, monthly and yearly
380 • -u, --until=UNTIL specify until when a recurring event should run
382 • --alarm DURATION will add an alarm DURATION before the start of the
384 event, DURATION should look like 1day 10minutes or 1d3H10m, negative
385 DURATIONs will set alarm after the start of the event.
386 Examples
388 khal new 18:00 Awesome Event
389 adds a new event starting today at 18:00 with summary 'awesome event'
391 (lasting for the default time of one hour) to the default calendar
392 khal new tomorrow 16:30 Coffee Break
394 adds a new event tomorrow at 16:30
396 khal new 25.10. 18:00 24:00 Another Event :: with Alice and Bob
398 adds a new event on 25th of October lasting from 18:00 to 24:00 with an
400 additional description
401 khal new -a work 26.07. Great Event -g meeting -r weekly
403 adds a new all day event on 26th of July to the calendar work which re‐
405 curs every week.
406 edit
408 an interactive command for editing and deleting events using a search
409 string
410 khal edit [--show-past] event_search_string
412 the command will loop through all events that match the search string,
414 prompting the user to delete, or change attributes.
415 printcalendars
417 prints a list of all configured calendars.
418 printformats
420 prints a fixed date (2013-12-21 10:09) in all configured date(time)
421 formats. This is supposed to help check if those formats are config‐
422 ured as intended.
423 search
425 search for events matching a search string and print them. Currently,
426 search will print one line for every different event in a recurrence
427 set, that is one line for the master event, and one line for every dif‐
428 ferent overwritten event. No advanced search features are currently
429 supported.
430 The command
432 khal search party
434 prints all events matching party.
436
438 khal reads configuration files in the ini syntax, meaning it under‐
439 stands keys separated from values by a =, while section and subsection
440 names are enclosed by single or double square brackets (like [section‐
441 name] and [[subsectionname]]).
442 Help with initial configuration
444 If you do not have a configuration file yet, running khal configure
445 will launch a small, interactive tool that should help you with initial
446 configuration of khal.
447 Location of configuration file
449 khal is looking for configuration files in the following places and or‐
450 der: $XDG_CONFIG_HOME/khal/config (on most systems this is ~/.con‐
451 fig/khal/config), ~/.khal/khal.conf (deprecated) and a file called
452 khal.conf in the current directory (deprecated). Alternatively you can
453 specify which configuration file to use with -c path/to/config at run‐
454 time.
455 The [calendars] section
457 The [calendars] section is mandatory and must contain at least one sub‐
458 section. Every subsection must have a unique name (enclosed by two
459 square brackets). Each subsection needs exactly one path setting, ev‐
460 erything else is optional. Here is a small example:
461 [calendars]
463 [[home]]
465 path = ~/.calendars/home/
466 color = dark green
467 [[work]]
469 path = ~/.calendars/work/
470 readonly = True
471 color khal will use this color for coloring this calendar's event.
474 The following color names are supported: black, white, brown,
475 yellow, dark gray, dark green, dark blue, light gray, light
476 green, light blue, dark magenta, dark cyan, dark red, light ma‐
477 genta, light cyan, light red. Depending on your terminal emula‐
478 tor's settings, they might look different than what their name
479 implies. In addition to the 16 named colors an index from the
480 256-color palette or a 24-bit color code can be used, if your
481 terminal supports this. The 256-color palette index is simply a
482 number between 0 and 255. The 24-bit color must be given as
483 #RRGGBB, where RR, GG, BB is the hexadecimal value of the red,
484 green and blue component, respectively. When using a 24-bit
485 color, make sure to enclose the color value in ' or "! If the
486 color is set to auto (the default), khal tries to read the file
487 color from this calendar's vdir, if this fails the default_color
488 (see below) is used. If color is set to '', the default_color is
489 always used.
490 type color
492 default
494 auto
495 path The path to an existing directory where this calendar is saved
497 as a vdir. The directory is searched for events or birthdays
498 (see type). The path also accepts glob expansion via * or ? when
499 type is set to discover. This allows for paths such as ~/ac‐
500 counts/*/calendars/*, where the calendars directory contains
501 vdir directories. In addition, ~/calendars/* and ~/calendars/de‐
502 fault are valid paths if there exists a vdir in the default di‐
503 rectory. (The previous behavior of recursively searching direc‐
504 tories has been replaced with globbing).
505 type string
507 default
509 None
510 readonly
512 setting this to True, will keep khal from making any changes to
513 this calendar
514 type boolean
516 default
518 False
519 type Setting the type of this collection (default calendar).
521 If set to calendar (the default), this collection will be used
523 as a standard calendar, that is, only files with the .ics exten‐
524 sion will be considered, all other files are ignored (except for
525 a possible color file).
526 If set to birthdays khal will expect a VCARD collection and ex‐
528 tract birthdays from those VCARDS, that is only files with .ics
529 extension will be considered, all other files will be ignored.
530 birthdays also implies readonly=True.
531 If set to discover, khal will use globbing
533 <https://en.wikipedia.org/wiki/Glob_(programming)> to expand
534 this calendar's path to (possibly) several paths and use those
535 as individual calendars (this cannot be used with birthday col‐
536 lections`). See Exemplary discover usage for an example.
537 If an individual calendar vdir has a color file, the calendar's
539 color will be set to the one specified in the color file, other‐
540 wise the color from the calendars subsection will be used.
541 type option, allowed values are calendar, birthdays and
543 discover
544 default
546 calendar
547 The [default] section
549 Some default values and behaviors are set here.
550 default_calendar
552 The calendar to use if none is specified for some operation
553 (e.g. if adding a new event). If this is not set, such opera‐
554 tions require an explicit value.
555 type string
557 default
559 None
560 default_command
562 Command to be executed if no command is given when executing
563 khal.
564 type option, allowed values are calendar, list, interac‐
566 tive, printformats, printcalendars, printics and **
567 default
569 calendar
570 highlight_event_days
572 If true, khal will highlight days with events. Options for high‐
573 lighting are in [highlight_days] section.
574 type boolean
576 default
578 False
579 print_new
581 After adding a new event, what should be printed to standard
582 out? The whole event in text form, the path to where the event
583 is now saved or nothing?
584 type option, allowed values are event, path and False
586 default
588 False
589 show_all_days
591 By default, khal displays only dates with events in list or cal‐
592 endar view. Setting this to True will show all days, even when
593 there is no event scheduled on that day.
594 type boolean
596 default
598 False
599 timedelta
601 Controls for how many days into the future we show events (for
602 example, in khal list) by default.
603 type timedelta
605 default
607 2d
608 The [highlight_days] section
610 When highlight_event_days is enabled, this section specifies how the
611 highlighting/coloring of days is handled.
612 color What color to use when highlighting -- explicit color or use
614 calendar color when set to ''
615 type color
617 default
619 default_color
621 Default color for calendars without color -- when set to '' it
622 actually disables highlighting for events that should use the
623 default color.
624 type color
626 default
628 method Highlighting method to use -- foreground or background
630 type option, allowed values are foreground, fg, background
632 and bg
633 default
635 fg
636 multiple
638 How to color days with events from multiple calendars -- either
639 explicit color or use calendars' colors when set to ''
640 type color
642 default
644 The [keybindings] section
646 Keybindings for ikhal are set here. You can bind more then one key
647 (combination) to a command by supplying a comma-separated list of keys.
648 For binding key combinations concatenate them keys (with a space in be‐
649 tween), e.g. ctrl n.
650 delete delete the currently selected event
652 type list
654 default
656 d
657 down move the cursor down (in the calendar browser)
659 type list
661 default
663 down, j
664 duplicate
666 duplicate the currently selected event
667 type list
669 default
671 p
672 export export event as a .ics file
674 type list
676 default
678 e
679 external_edit
681 edit the currently selected events' raw .ics file with $EDITOR
682 Only use this, if you know what you are doing, the icalendar li‐
683 brary we use doesn't do a lot of validation, it silently disre‐
684 gards most invalid data.
685 type list
687 default
689 meta E
690 left move the cursor left (in the calendar browser)
692 type list
694 default
696 left, h, backspace
697 mark go into highlight (visual) mode to choose a date range
699 type list
701 default
703 v
704 new create a new event on the selected date
706 type list
708 default
710 n
711 other in highlight mode go to the other end of the highlighted date
713 range
714 type list
716 default
718 o
719 quit quit
721 type list
723 default
725 q, Q
726 right move the cursor right (in the calendar browser)
728 type list
730 default
732 right, l, space
733 save save the currently edited event and leave the event editor
735 type list
737 default
739 meta enter
740 search open a text field to start a search for events
742 type list
744 default
746 /
747 today focus the calendar browser on today
749 type list
751 default
753 t
754 up move the cursor up (in the calendar browser)
756 type list
758 default
760 up, k
761 view show details or edit (if details are already shown) the cur‐
763 rently selected event
764 type list
766 default
768 enter
769 The [locale] section
771 It is mandatory to set (long)date-, time-, and datetimeformat options,
772 all others options in the [locale] section are optional and have (sen‐
773 sible) defaults.
774 dateformat
776 khal will display and understand all dates in this format, see
777 timeformat for the format
778 type string
780 default
782 %d.%m.
783 datetimeformat
785 khal will display and understand all datetimes in this format,
786 see timeformat for the format.
787 type string
789 default
791 %d.%m. %H:%M
792 default_timezone
794 this timezone will be used for new events (when no timezone is
795 specified) and when khal does not understand the timezone speci‐
796 fied in the icalendar file. If no timezone is set, the timezone
797 your computer is set to will be used.
798 type timezone
800 default
802 None
803 firstweekday
805 the first day of the week, were Monday is 0 and Sunday is 6
806 type integer, allowed values are between 0 and 6
808 default
810 0
811 local_timezone
813 khal will show all times in this timezone If no timezone is set,
814 the timezone your computer is set to will be used.
815 type timezone
817 default
819 None
820 longdateformat
822 khal will display and understand all dates in this format, it
823 should contain a year (e.g. %Y) see timeformat for the format.
824 type string
826 default
828 %d.%m.%Y
829 longdatetimeformat
831 khal will display and understand all datetimes in this format,
832 it should contain a year (e.g. %Y) see timeformat for the for‐
833 mat.
834 type string
836 default
838 %d.%m.%Y %H:%M
839 timeformat
841 khal will display and understand all times in this format.
842 The formatting string is interpreted as defined by Python's
844 strftime <https://docs.python.org/2/library/time.html#time.strf‐
845 time>, which is similar to the format specified in man strftime.
846 type string
848 default
850 %H:%M
851 unicode_symbols
853 by default khal uses some unicode symbols (as in 'non-ascii') as
854 indicators for things like repeating events, if your font, en‐
855 coding etc. does not support those symbols, set this to False
856 (this will enable ascii based replacements).
857 type boolean
859 default
861 True
862 weeknumbers
864 Enable weeknumbers in calendar and interactive (ikhal) mode. As
865 those are iso weeknumbers, they only work properly if firstweek‐
866 day is set to 0
867 type weeknumbers
869 default
871 off
872 The [sqlite] section
874 path khal stores its internal caching database here, by default this
875 will be in the $XDG_DATA_HOME/khal/khal.db (this will most
876 likely be ~/.local/share/khal/khal.db).
877 type string
879 default
881 None
882 The [view] section
884 The view section contains configuration options that effect the visual
885 appearance when using khal and ikhal.
886 agenda_day_format
888 Specifies how each day header is formatted.
889 type string
891 default
893 {bold}{name}, {date-long}{reset}
894 agenda_event_format
896 Default formatting for events used when the user asks for all
897 events in a given time range, used for list, calendar and in in‐
898 teractive (ikhal). Please note, that any color styling will be
899 ignored in ikhal, where events will always be shown in the color
900 of the calendar they belong to. The syntax is the same as for
901 --format.
902 type string
904 default
906 {calendar-color}{cancelled}{start-end-time-style} {ti‐
907 tle}{repeat-symbol}{description-separator}{descrip‐
908 tion}{reset}
909 bold_for_light_color
911 Whether to use bold text for light colors or not. Non-bold light
912 colors may not work on all terminals but allow using light back‐
913 ground colors.
914 type boolean
916 default
918 True
919 dynamic_days
921 Defines the behaviour of ikhal's right column. If True, the
922 right column will show events for as many days as fit, moving
923 the cursor through the list will also select the appropriate day
924 in the calendar column on the left. If False, only a fixed ([de‐
925 fault] timedelta) amount of days' events will be shown, moving
926 through events will not change the focus in the left column.
927 type boolean
929 default
931 True
932 event_format
934 Default formatting for events used when the start- and end-date
935 are not clear through context, e.g. for search, used almost ev‐
936 erywhere but list and calendar. It is therefore probably a sen‐
937 sible choice to include the start- and end-date. The syntax is
938 the same as for --format.
939 type string
941 default
943 {calendar-color}{cancelled}{start}-{end} {title}{re‐
944 peat-symbol}{description-separator}{description}{re‐
945 set}
946 event_view_always_visible
948 Set to true to always show the event view window when looking at
949 the event list
950 type boolean
952 default
954 False
955 event_view_weighting
957 weighting that is applied to the event view window
958 type integer
960 default
962 1
963 frame Whether to show a visible frame (with box drawing characters)
965 around some (groups of) elements or not. There are currently
966 several different frame options available, that should visually
967 differentiate whether an element is in focus or not. Some of
968 them will probably be removed in future releases of khal, so
969 please try them out and give feedback on which style you prefer
970 (the color of all variants can be defined in the color themes).
971 type option, allowed values are False, width, color and top
973 default
975 False
976 theme Choose a color theme for khal.
978 This is very much work in progress. Help is really welcome! The
980 two currently available color schemes (dark and light) are de‐
981 fined in khal/ui/colors.py, you can either help improve those or
982 create a new one (see below). As ikhal uses urwid, have a look
983 at urwid's documentation <http://urwid.org/manual/displayat‐
984 tributes.html> for how to set colors and/or at the existing
985 schemes. If you cannot change the color of an element (or have
986 any other problems) please open an issue on github.
987 If you want to create your own color scheme, copy the structure
989 of the existing ones, give it a new and unique name and also add
990 it as an option in khal/settings/khal.spec in the section [de‐
991 fault] of the property theme.
992 type option, allowed values are dark and light
994 default
996 dark
997 A minimal sample configuration could look like this:
999 Example
1001 [calendars]
1002 [[home]]
1003 path = ~/.calendars/home/
1004 [[work]]
1006 path = ~/.calendars/work/
1007 [locale]
1009 local_timezone= Europe/Berlin
1010 default_timezone= Europe/Berlin
1011 timeformat= %H:%M
1012 dateformat= %d.%m.
1013 longdateformat= %d.%m.%Y
1014 datetimeformat= %d.%m. %H:%M
1015 longdatetimeformat= %d.%m.%Y %H:%M
1016 Exemplary discover usage
1019 If you have the following directory layout:
1020 ~/calendars
1022 ├- work/
1023 ├- home/
1024 └─ family/
1025 where work, home and family are all different vdirs, each containing
1027 one calendar, a matching calendar section could look like this:
1028 [[calendars]]
1030 path = ~/calendars/*
1031 type = discover
1032 color = dark green
1033 Syncing
1035 To get khal working with CalDAV you will first need to setup vdirsyncer
1036 <https://github.com/untitaker/vdirsyncer>. After each start khal will
1037 automatically check if anything has changed and automatically update
1038 its caching db (this may take some time after the initial sync, espe‐
1039 cially for large calendar collections). Therefore, you might want to
1040 execute khal automatically after syncing with vdirsyncer (e.g. via
1041 cron).
1042
1044 khal tries to follow standards and RFCs (most importantly RFC 5545
1045 <https://datatracker.ietf.org/doc/html/rfc5545.html> iCalendar) wher‐
1046 ever possible. Known intentional and unintentional deviations are
1047 listed below.
1048 RDATE;VALUE=PERIOD
1050 RDATE s with PERIOD values are currently not supported, as icalendar
1051 <https://github.com/collective/icalendar> does not support it yet.
1052 Please submit any real world examples of events with RDATE;VALUE=PERIOD
1053 you might encounter (khal will print warnings if you have any in your
1054 calendars).
1055 RANGE=THISANDPRIOR
1057 Recurrent events with the RANGE=THISANDPRIOR are and will not be [1]
1058 supported by khal, as applications supporting the latest standard
1059 <http://tools.ietf.org/html/rfc5546> MUST NOT create those. khal will
1060 print a warning if it encounters an event containing RANGE=THISAND‐
1061 PRIOR.
1062 [1] unless a lot of users request this feature
1064 Events with neither END nor DURATION
1066 While the RFC states:
1067 A calendar entry with a "DTSTART" property but no "DTEND"
1069 property does not take up any time. It is intended to represent
1070 an event that is associated with a given calendar date and time
1071 of day, such as an anniversary. Since the event does not take up
1072 any time, it MUST NOT be used to record busy time no matter what
1073 the value for the "TRANSP" property.
1074 khal transforms those events into all-day events lasting for one day
1076 (the start date). As long a those events do not get edited, these
1077 changes will not be written to the vdir (and with that to the CalDAV
1078 server). Any timezone information that was associated with the start
1079 date gets discarded.
1080 NOTE:
1082 While the main rationale for this behaviour was laziness on part of
1083 khal's main author, other calendar software shows the same behaviour
1084 (e.g. Google Calendar and Evolution).
1085 Timezones
1087 Getting localized time right, seems to be the most difficult part about
1088 calendaring (and messing it up ends in missing the one important meet‐
1089 ing of the week). So I'll briefly describe here, how khal tries to han‐
1090 dle timezone information, which information it can handle and which it
1091 can't.
1092 In general, there are two different type of events. Localized events
1094 (with localized start and end datetimes) which have timezone informa‐
1095 tion attached to their start and end datetimes, and floating events
1096 (with floating start and end datetimes), which have no timezone infor‐
1097 mation attached (all-day events, events that last for complete days are
1098 floating as well). Localized events are always observed at the same UTC
1099 <https://en.wikipedia.org/wiki/Coordinated_Universal_Time> (no matter
1100 what time zone the observer is in), but different local times. On the
1101 other hand, floating events are always observed at the same local time,
1102 which might be different in UTC.
1103 In khal all localized datetimes are saved to the local database as UTC.
1105 Datetimes that are already UTC, e.g. 19980119T070000Z, are saved as
1106 such, others are converted to UTC (but don't worry, the timezone infor‐
1107 mation does not get lost). Floating events get saved in floating time,
1108 independently of the localized events.
1109 If you want to look up which events take place at a specified datetime,
1111 khal always expects that you want to know what events take place at
1112 that local datetime. Therefore, the (local) datetime you asked for gets
1113 converted to UTC, the appropriate localized events get selected and
1114 presented with their start and end datetimes converted to your local
1115 datetime. For floating events no conversion is necessary.
1116 Khal (i.e. icalendar <https://github.com/collective/icalendar>) can un‐
1118 derstand all timezone identifiers as used in the Olson DB
1119 <https://en.wikipedia.org/wiki/Tz_database> and custom timezone defini‐
1120 tions, if those VTIMEZONE components are placed before the VEVENTS that
1121 make use of them (as most calendar programs seem to do). In case an un‐
1122 known (or unsupported) timezone is found, khal will assume you want
1123 that event to be placed in the default timezone (which can be config‐
1124 ured in the configuration file as well).
1125 khal expects you always want all start and end datetimes displayed in
1127 local time (which can be set in the configuration file as well, other‐
1128 wise your computer's timezone is used).
1129
1131 Frequently asked questions:
1132 •
1134 start up of khal and ikhal is very slow
1136 In some case the pytz (python timezone) is only available as a
1137 zip file, as pytz accesses several parts during initialization
1138 this takes some time. If time python -c "import pytz;
1139 pytz.timezone('Europe/Berlin')" takes nearly as much time as
1140 running khal, uncompressing that file via pytz via (sudo) pip
1141 unzip pytz might help.
1142 •
1144 ikhal raises an Exception: AttributeError: 'module' object has no at‐
1146 tribute 'SimpleFocusListWalker'
1147 You probably need to upgrade urwid to version 1.1.0, if your
1148 OS does come with an older version of urwid you can install
1149 the latest version to userspace (without messing up your de‐
1150 fault installation) with pip install --upgrade urwid --user.
1151 •
1153 Installation stops with an error: source/str_util.c:25:20: fatal er‐
1155 ror: Python.h: No such file or directory
1156 You do not have the Python development headers installed, on
1157 Debian based Distributions you can install them via aptitude
1158 install python-dev.
1159
1161 khal is released under the Expat/MIT License:
1162 Copyright (c) 2013-2017 Christian Geier et al.
1164 Permission is hereby granted, free of charge, to any person obtaining a copy of
1166 this software and associated documentation files (the "Software"), to deal in
1167 the Software without restriction, including without limitation the rights to
1168 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
1169 the Software, and to permit persons to whom the Software is furnished to do so,
1170 subject to the following conditions:
1171 The above copyright notice and this permission notice shall be included in all
1173 copies or substantial portions of the Software.
1174 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1176 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
1177 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
1178 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
1179 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
1180 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1181
1183 Christan Geier et al.
1184
1186 2014-2022, Christan Geier et al.
11870.9.10 Jul 21, 2022 KHAL(1)