1KHAL(1)                              khal                              KHAL(1)
2
3
4

NAME

6       khal - khal Documentation
7
8       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

USAGE

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
19   Options
20       khal  (without any commands) has some options to print some information
21       about khal:
22
23       --version
24              Prints khal's version number and exits
25
26       -h, --help
27              Prints a summary of khal's options and commands and then exits
28
29       Several options are common to almost all of khal's commands (exceptions
30       are described below):
31
32       -v     Be more verbose (e.g. print debugging information)
33
34       -c CONFIGFILE
35              Use an alternate configuration file
36
37       -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
42       -d CALENDAR
43              Specify  a  calendar which will be disregarded for this run, can
44              be used several times.
45
46       --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
53       --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
62              title  The title of the event.
63
64              description
65                     The description of the event.
66
67              start  The start datetime in datetimeformat.
68
69              start-long
70                     The start datetime in longdatetimeformat.
71
72              start-date
73                     The start date in dateformat.
74
75              start-date-long
76                     The start date in longdateformat.
77
78              start-time
79                     The start time in timeformat.
80
81              end    The end datetime in datetimeformat.
82
83              end-long
84                     The end datetime in longdatetimeformat.
85
86              end-date
87                     The end date in dateformat.
88
89              end-date-long
90                     The end date in longdateformat.
91
92              end-time
93                     The end time in timeformat.
94
95              repeat-symbol
96                     A repeating symbol (loop arrow) if the event  is  repeat‐
97                     ing.
98
99              description
100                     The event description.
101
102              description-separator
103                     A separator: " :: " that appears when there is a descrip‐
104                     tion.
105
106              location
107                     The event location.
108
109              calendar
110                     The calendar name.
111
112              calendar-color
113                     Changes the output color to the calendar's color.
114
115              start-style
116                     The start time in timeformat OR an appropriate symbol.
117
118              to-style
119                     A hyphen "-" or nothing such that it  appropriately  fits
120                     between start-style and end-style.
121
122              end-style
123                     The end time in timeformat OR an appropriate symbol.
124
125              start-end-time-style
126                     A  concatenation  of start-style, to-style, and end-style
127                     OR an appropriate symbol.
128
129              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
135              end-necessary-long
136                     Same as end-necessary but uses datelong and datetimelong.
137
138              status The  status  of  the event (if this event has one), some‐
139                     thing like CONFIRMED or CANCELLED.
140
141              cancelled
142                     The string CANCELLED (plus one blank) if the event's sta‐
143                     tus is cancelled, otherwise nothing.
144
145              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
151              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
156              For example the below command with print the title and  descrip‐
157              tion of all events today.
158
159                 khal list --format "{title} {description}"
160
161       --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
165              date   The date in dateformat.
166
167              date-long
168                     The date in longdateformat.
169
170              name   The date's name (Monday, Tuesday,…) or today or tomorrow.
171
172              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
176   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
184   Commands
185   list
186       shows  all  events scheduled for a given date (or datetime) range, with
187       custom formatting:
188
189          khal list [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
190          [--day-format DAYFORMAT] [--once] [--notstarted] [START [END | DELTA] ]
191
192       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
203       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
207   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
214          khal at [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
215          [--notstarted] [[START DATE] TIME | now]
216
217   calendar
218       shows a calendar (similar to cal(1)) and list. khal calendar should un‐
219       derstand the following syntax:
220
221          khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME]
222          [END DATETIME]
223
224       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
229   configure
230       will  help users creating an initial configuration file. configure will
231       refuse to run if there already is a configuration file.
232
233   import
234       lets the user import .ics files with the following syntax:
235
236          khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE
237
238       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
247   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
252       When the calendar on the left is in focus, you can
253
254          • move through the calendar (default keybindings are the arrow keys,
255            space and backspace, those keybindings  are  configurable  in  the
256            config file)
257
258          • focus on the right column by pressing tab or enter
259
260          • re-focus on the current date, default keybinding t as in today
261
262          • marking  a  date  range, default keybinding v, as in visual, think
263            visual mode in Vim, pressing esc escape this visual mode
264
265          • 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
268          • 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
271          • search for events, default keybinding /, a  pop-up  will  ask  for
272            your search term
273
274       When an event list is in focus, you can
275
276          • 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
281          • 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
285          • duplicate the selected event, default keybinding p as in duplicate
286            (d was already taken)
287
288          • export the selected event, default keybinding e
289
290       In the event editor, you can
291
292       • jump  to  the  next  (previous)  selectable element with pressing tab
293         (shift+tab)
294
295       • quick save, default keybinding meta+enter (meta will probably be alt)
296
297       • 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
302       • 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
305       • activate actions by pressing enter on text enclosed by angled  brack‐
306         ets, e.g.  < Save > (sometimes this might open a pop up)
307
308       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
312   new
313       allows  for adding new events. khal new should understand the following
314       syntax:
315
316          khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
317          [:: DESCRIPTION]]
318
319       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
324       new  accepts  these combinations for start and endtimes (specifying the
325       end is always optional):
326
327datetime [datetime|time] [timezone]
328
329time [time] [timezone]
330
331date [date]
332
333       where the formats for datetime and time are as follows:
334
335datetime =  (longdatetimeformat|datetimeformat|keyword-date  time‐
336            format)
337
338time = timeformat
339
340date = (longdateformat|dateformat)
341
342       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
347       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
353       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
360       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
363       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
367       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
371   Options
372-l, --location=LOCATION specify where this event will be held.
373
374-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
378-r, --repeat=RRULE specify if and how this event should be recurring.
379         Valid values for RRULE are daily, weekly, monthly and yearly
380
381-u, --until=UNTIL specify until when a recurring event should run
382
383--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
387   Examples
388          khal new 18:00 Awesome Event
389
390       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
393          khal new tomorrow 16:30 Coffee Break
394
395       adds a new event tomorrow at 16:30
396
397          khal new 25.10. 18:00 24:00 Another Event :: with Alice and Bob
398
399       adds a new event on 25th of October lasting from 18:00 to 24:00 with an
400       additional description
401
402          khal new -a work 26.07. Great Event -g meeting -r weekly
403
404       adds a new all day event on 26th of July to the calendar work which re‐
405       curs every week.
406
407   edit
408       an interactive command for editing and deleting events using  a  search
409       string
410
411          khal edit [--show-past] event_search_string
412
413       the  command will loop through all events that match the search string,
414       prompting the user to delete, or change attributes.
415
416   printcalendars
417       prints a list of all configured calendars.
418
419   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
424   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
431       The command
432
433          khal search party
434
435       prints all events matching party.
436

CONFIGURATION

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
443   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
448   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
456   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
462          [calendars]
463
464            [[home]]
465              path = ~/.calendars/home/
466              color = dark green
467
468            [[work]]
469              path = ~/.calendars/work/
470              readonly = True
471
472
473       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
491                 type   color
492
493                 default
494                        auto
495
496       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
506                 type   string
507
508                 default
509                        None
510
511       readonly
512              setting  this to True, will keep khal from making any changes to
513              this calendar
514
515                 type   boolean
516
517                 default
518                        False
519
520       type   Setting the type of this collection (default calendar).
521
522              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
527              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
532              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
538              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
542                 type   option, allowed values  are  calendar,  birthdays  and
543                        discover
544
545                 default
546                        calendar
547
548   The [default] section
549       Some default values and behaviors are set here.
550
551       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
556                 type   string
557
558                 default
559                        None
560
561       default_command
562              Command  to  be  executed  if no command is given when executing
563              khal.
564
565                 type   option, allowed values are  calendar,  list,  interac‐
566                        tive, printformats, printcalendars, printics and **
567
568                 default
569                        calendar
570
571       highlight_event_days
572              If true, khal will highlight days with events. Options for high‐
573              lighting are in [highlight_days] section.
574
575                 type   boolean
576
577                 default
578                        False
579
580       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
585                 type   option, allowed values are event, path and False
586
587                 default
588                        False
589
590       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
595                 type   boolean
596
597                 default
598                        False
599
600       timedelta
601              Controls for how many days into the future we show  events  (for
602              example, in khal list) by default.
603
604                 type   timedelta
605
606                 default
607                        2d
608
609   The [highlight_days] section
610       When  highlight_event_days  is  enabled, this section specifies how the
611       highlighting/coloring of days is handled.
612
613       color  What color to use when highlighting --  explicit  color  or  use
614              calendar color when set to ''
615
616                 type   color
617
618                 default
619
620       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
625                 type   color
626
627                 default
628
629       method Highlighting method to use -- foreground or background
630
631                 type   option,  allowed values are foreground, fg, background
632                        and bg
633
634                 default
635                        fg
636
637       multiple
638              How to color days with events from multiple calendars --  either
639              explicit color or use calendars' colors when set to ''
640
641                 type   color
642
643                 default
644
645   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
651       delete delete the currently selected event
652
653                 type   list
654
655                 default
656                        d
657
658       down   move the cursor down (in the calendar browser)
659
660                 type   list
661
662                 default
663                        down, j
664
665       duplicate
666              duplicate the currently selected event
667
668                 type   list
669
670                 default
671                        p
672
673       export export event as a .ics file
674
675                 type   list
676
677                 default
678                        e
679
680       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
686                 type   list
687
688                 default
689                        meta E
690
691       left   move the cursor left (in the calendar browser)
692
693                 type   list
694
695                 default
696                        left, h, backspace
697
698       mark   go into highlight (visual) mode to choose a date range
699
700                 type   list
701
702                 default
703                        v
704
705       new    create a new event on the selected date
706
707                 type   list
708
709                 default
710                        n
711
712       other  in  highlight  mode  go to the other end of the highlighted date
713              range
714
715                 type   list
716
717                 default
718                        o
719
720       quit   quit
721
722                 type   list
723
724                 default
725                        q, Q
726
727       right  move the cursor right (in the calendar browser)
728
729                 type   list
730
731                 default
732                        right, l, space
733
734       save   save the currently edited event and leave the event editor
735
736                 type   list
737
738                 default
739                        meta enter
740
741       search open a text field to start a search for events
742
743                 type   list
744
745                 default
746                        /
747
748       today  focus the calendar browser on today
749
750                 type   list
751
752                 default
753                        t
754
755       up     move the cursor up (in the calendar browser)
756
757                 type   list
758
759                 default
760                        up, k
761
762       view   show details or edit (if details are  already  shown)  the  cur‐
763              rently selected event
764
765                 type   list
766
767                 default
768                        enter
769
770   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
775       dateformat
776              khal  will  display and understand all dates in this format, see
777              timeformat for the format
778
779                 type   string
780
781                 default
782                        %d.%m.
783
784       datetimeformat
785              khal will display and understand all datetimes in  this  format,
786              see timeformat for the format.
787
788                 type   string
789
790                 default
791                        %d.%m. %H:%M
792
793       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
799                 type   timezone
800
801                 default
802                        None
803
804       firstweekday
805              the first day of the week, were Monday is 0 and Sunday is 6
806
807                 type   integer, allowed values are between 0 and 6
808
809                 default
810                        0
811
812       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
816                 type   timezone
817
818                 default
819                        None
820
821       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
825                 type   string
826
827                 default
828                        %d.%m.%Y
829
830       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
835                 type   string
836
837                 default
838                        %d.%m.%Y %H:%M
839
840       timeformat
841              khal will display and understand all times in this format.
842
843              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
847                 type   string
848
849                 default
850                        %H:%M
851
852       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
858                 type   boolean
859
860                 default
861                        True
862
863       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
868                 type   weeknumbers
869
870                 default
871                        off
872
873   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
878                 type   string
879
880                 default
881                        None
882
883   The [view] section
884       The  view section contains configuration options that effect the visual
885       appearance when using khal and ikhal.
886
887       agenda_day_format
888              Specifies how each day header is formatted.
889
890                 type   string
891
892                 default
893                        {bold}{name}, {date-long}{reset}
894
895       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
903                 type   string
904
905                 default
906                        {calendar-color}{cancelled}{start-end-time-style} {ti‐
907                        tle}{repeat-symbol}{description-separator}{descrip‐
908                        tion}{reset}
909
910       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
915                 type   boolean
916
917                 default
918                        True
919
920       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
928                 type   boolean
929
930                 default
931                        True
932
933       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
940                 type   string
941
942                 default
943                        {calendar-color}{cancelled}{start}-{end}   {title}{re‐
944                        peat-symbol}{description-separator}{description}{re‐
945                        set}
946
947       event_view_always_visible
948              Set to true to always show the event view window when looking at
949              the event list
950
951                 type   boolean
952
953                 default
954                        False
955
956       event_view_weighting
957              weighting that is applied to the event view window
958
959                 type   integer
960
961                 default
962                        1
963
964       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
972                 type   option, allowed values are False, width, color and top
973
974                 default
975                        False
976
977       theme  Choose a color theme for khal.
978
979              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
988              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
993                 type   option, allowed values are dark and light
994
995                 default
996                        dark
997
998       A minimal sample configuration could look like this:
999
1000   Example
1001          [calendars]
1002          [[home]]
1003          path = ~/.calendars/home/
1004
1005          [[work]]
1006          path = ~/.calendars/work/
1007
1008          [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
1017
1018   Exemplary discover usage
1019       If you have the following directory layout:
1020
1021          ~/calendars
1022          ├- work/
1023          ├- home/
1024          └─ family/
1025
1026       where  work,  home  and family are all different vdirs, each containing
1027       one calendar, a matching calendar section could look like this:
1028
1029          [[calendars]]
1030          path = ~/calendars/*
1031          type = discover
1032          color = dark green
1033
1034   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

STANDARDS

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
1049   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
1056   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
1063       [1]  unless a lot of users request this feature
1064
1065   Events with neither END nor DURATION
1066       While the RFC states:
1067
1068          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
1075       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
1081       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
1086   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
1093       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
1104       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
1110       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
1117       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
1126       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

FAQ

1131       Frequently asked questions:
1132
1133
1134
1135         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
1143
1144
1145         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
1152
1153
1154         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

LICENSE

1161       khal is released under the Expat/MIT License:
1162
1163          Copyright (c) 2013-2017 Christian Geier et al.
1164
1165          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
1172          The above copyright notice and this permission notice shall be included in all
1173          copies or substantial portions of the Software.
1174
1175          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

AUTHOR

1183       Christan Geier et al.
1184
1186       2014-2022, Christan Geier et al.
1187
1188
1189
1190
11910.9.10                           Jul 21, 2022                          KHAL(1)
Impressum