Provided by: khal_0.11.2-2_all 
NAME
khal - khal Documentation
Khal is a calendar program for the terminal for viewing, adding and editing events and
calendars. Khal is build on the iCalendar and vdir (allowing the use of vdirsyncer(1) for
CalDAV compatibility) standards.
USAGE
Khal offers a set of commands, most importantly list, calendar, interactive, new,
printcalendars, printformats, and search. See below for a description of what every
command does. khal does currently not support any default command, i.e., run a command,
even though none has been specified. This is intentional.
Options
khal (without any commands) has some options to print some information about khal:
--version
Prints khal's version number and exits
-h, --help
Prints a summary of khal's options and commands and then exits
Several options are common to almost all of khal's commands (exceptions are described
below):
-v, --verbosity LVL
Configure verbosity (e.g. print debugging information), LVL needs to be one of
CRITICAL, ERROR, WARNING, INFO, or DEBUG.
-l, --logfile LOFILE
Use logfile LOGFILE for logging, default is logging to stdout.
-c CONFIGFILE
Use an alternate configuration file.
-a CALENDAR
Specify a calendar to use (which must be configured in the configuration file), can
be used several times. Calendars not specified will be disregarded for this run.
-d CALENDAR
Specify a calendar which will be disregarded for this run, can be used several
times.
--color/--no-color
khal will detect if standard output is not a tty, e.g., you redirect khal's output
into a file, and if so remove all highlighting/coloring from its output. Use
--color if you want to force highlighting/coloring and --no-color if you want
coloring always removed.
--format FORMAT
For all of khal's commands that print events, the formatting of that event can be
specified with this option. FORMAT is a template string, in which identifiers
delimited by curly braces ({}) will be expanded to an event's properties. FORMAT
supports all formatting options offered by python's str.format()
<https://docs.python.org/3/library/string.html#formatstrings> (as it is used
internally). The available template options are:
title The title of the event.
description
The description of the event.
description-separator
A separator: " :: " that appears when there is a description.
uid The UID of the event.
start The start datetime in datetimeformat.
start-long
The start datetime in longdatetimeformat.
start-date
The start date in dateformat.
start-date-long
The start date in longdateformat.
start-time
The start time in timeformat.
end The end datetime in datetimeformat.
end-long
The end datetime in longdatetimeformat.
end-date
The end date in dateformat.
end-date-long
The end date in longdateformat.
end-time
The end time in timeformat.
repeat-symbol
A repeating symbol (loop arrow) if the event is repeating.
alarm-symbol
An alarm symbol (alarm clock) if the event has at least one alarm.
location
The event location.
calendar
The calendar name.
calendar-color
Changes the output color to the calendar's color.
start-style
The start time in timeformat OR an appropriate symbol.
to-style
A hyphen "-" or nothing such that it appropriately fits between start-style
and end-style.
end-style
The end time in timeformat OR an appropriate symbol.
start-end-time-style
A concatenation of start-style, to-style, and end-style OR an appropriate
symbol.
end-necessary
For an allday event this is an empty string unless the end date and start
date are different. For a non-allday event this will show the time or the
datetime if the event start and end date are different.
end-necessary-long
Same as end-necessary but uses datelong and datetimelong.
status The status of the event (if this event has one), something like CONFIRMED or
CANCELLED.
cancelled
The string CANCELLED (plus one blank) if the event's status is cancelled,
otherwise nothing.
organizer
The organizer of the event. If the format has CN then it returns "CN
(email)" if CN does not exist it returns just the email string. Example:
ORGANIZER;CN=Name Surname:mailto:name@mail.com returns Name Surname
(name@mail.com) and if it has no CN attribute it returns the last element
after the colon:
ORGANIZER;SENT-BY="mailto:toemail@mail.com":mailto:name@mail.com returns
name@mail.com
url The URL embedded in the event, otherwise nothing.
By default, all-day events have no times. To see a start and end time anyway simply
add -full to the end of any template with start/end, for instance start-time
becomes start-time-full and will always show start and end times (instead of being
empty for all-day events).
In addition, there are colors: black, red, green, yellow, blue, magenta, cyan,
white (and their bold versions: red-bold, etc.). There is also reset, which clears
the styling, and bold, which is the normal bold.
A few control codes are exposed. You can access newline (nl), 'tab', and 'bell'.
Control codes, such as nl, are best used with --list mode.
Below is an example command which prints the title and description of all events
today.
khal list --format "{title} {description}"
--day-format DAYFORMAT
works similar to --format, but for day headings. It only has a few options (in
addition to all the color options):
date The date in dateformat.
date-long
The date in longdateformat.
name The date's name (Monday, Tuesday,…) or today or tomorrow.
If the --day-format is passed an empty string then it will not print the day
headers (for an empty line pass in a whitespace character).
dates
Almost everywhere khal accepts dates, khal should recognize relative date names like
today, tomorrow and the names of the days of the week (also in three letters abbreviated
form). Week day names get interpreted as the date of the next occurrence of a day with
that name. The name of the current day gets interpreted as that date next week (i.e. seven
days from now).
If a short datetime format is used (no year is given), khal will interpret the date to be
in the future. The inferred it might be in the next year if the given date has already
passed in the current year.
Commands
list
shows all events scheduled for a given date (or datetime) range, with custom formatting:
khal list [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
[--day-format DAYFORMAT] [--once] [--notstarted] [START [END | DELTA] ]
START and END can both be given as dates, datetimes or times (it is assumed today is meant
in the case of only a given time) in the formats configured in the configuration file. If
END is not given, midnight of the start date is assumed. Today is used for START if it is
not explicitly given. If DELTA, a (date)time range in the format I{m,h,d}, where I is an
integer and m means minutes, h means hours, and d means days, is given, END is assumed to
be START + DELTA. A value of eod is also accepted as DELTA and means the end of day of
the start date. In addition, the DELTA week may be used to specify that the daterange
should actually be the week containing the START.
The --once option only allows events to appear once even if they are on multiple days.
With the --notstarted option only events are shown that start after START.
at
shows all events scheduled for a given datetime. khal at should be supplied with a date
and time, a time (the date is then assumed to be today) or the string now. at defaults to
now. The at command works just like the list command, except it has an implicit end time
of zero minutes after the start.
khal at [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
[--notstarted] [[START DATE] TIME | now]
calendar
shows a calendar (similar to cal(1)) and list. khal calendar should understand the
following syntax:
khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME]
[END DATETIME]
Date selection works exactly as for khal list. The displayed calendar contains three
consecutive months, where the first month is the month containing the first given date. If
today is included, it is highlighted. Have a look at khal list for a description of the
options.
configure
will help users creating an initial configuration file. configure will refuse to run if
there already is a configuration file.
import
lets the user import .ics files with the following syntax:
khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE
If an event with the same UID is already present in the (implicitly) selected calendar
khal import will ask before updating (i.e. overwriting) that old event with the imported
one, unless --batch is given, than it will always update. If this behaviour is not
desired, use the --random-uid flag to generate a new, random UID. If no calendar is
specified (and not --batch), you will be asked to choose a calendar. You can either enter
the number printed behind each calendar's name or any unique prefix of a calendar's name.
interactive
invokes the interactive version of khal, can also be invoked by calling ikhal. While ikhal
can be used entirely with the keyboard, some elements respond if clicked on with a mouse
(mostly by being selected).
When the calendar on the left is in focus, you can
• move through the calendar (default keybindings are the arrow keys, space and
backspace, those keybindings are configurable in the config file)
• focus on the right column by pressing tab or enter
• re-focus on the current date, default keybinding t as in today
• marking a date range, default keybinding v, as in visual, think visual mode in Vim,
pressing esc escapes this visual mode
• if in visual mode, you can select the other end of the currently marked range,
default keybinding o as in other (again as in Vim)
• create a new event on the currently focused day (or date range if a range is
selected), default keybinding n as in new
• search for events, default keybinding /, a pop-up will ask for your search term
When an event list is in focus, you can
• view an event's details with pressing enter (or tab) and edit it with pressing enter
(or tab) again (if [default] event_view_always_visible is set to True, the event in
focus will always be shown in detail)
• toggle an event's deletion status, default keybinding d as in delete, events marked
for deletion will appear with a D in front and will be deleted when khal exits.
• duplicate the selected event, default keybinding p as in duplicate (d was already
taken)
• export the selected event, default keybinding e
In the event editor, you can
• jump to the next (previous) selectable element with pressing tab (shift+tab)
• quick save, default keybinding meta+enter (meta will probably be alt)
• use some common editing short cuts in most text fields (ctrl+w deletes word before
cursor, ctrl+u (ctrl+k) deletes till the beginning (end) of the line, ctrl+a (ctrl+e)
will jump to the beginning (end) of the line
• in the date and time fields you can increment and decrement the number under the cursor
with ctrl+a and ctrl+x (time in 15 minute steps)
• in the date fields you can access a miniature calendar by pressing enter
• activate actions by pressing enter on text enclosed by angled brackets, e.g. < Save >
(sometimes this might open a pop up)
Pressing esc will cancel the current action and/or take you back to the previously shown
pane (i.e. what you see when you open ikhal), if you are at the start pane, ikhal will
quit on pressing esc again.
new
allows for adding new events. khal new should understand the following syntax:
khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
[:: DESCRIPTION]]
where start- and enddatetime are either datetimes, times, or keywords and times in the
formats defined in the config file. If no calendar is given via -a, the default calendar
is used. new does not support -d and also -a may only be used once.
new accepts these combinations for start and endtimes (specifying the end is always
optional):
• datetime [datetime|time] [timezone]
• time [time] [timezone]
• date [date]
where the formats for datetime and time are as follows:
• datetime = (longdatetimeformat|datetimeformat|keyword-date timeformat)
• time = timeformat
• date = (longdateformat|dateformat)
and timezone, which describes the timezone the events start and end time are in, should be
a valid Olson DB identifier (like Europe/Berlin or America/New_York. If no timezone is
given, the defaulttimezone as configured in the configuration file is used instead.
The exact format of longdatetimeformat, datetimeformat, timeformat, longdateformat and
dateformat can be configured in the configuration file. Valid keywords for dates are
today, tomorrow, the English name of all seven weekdays and their three letter
abbreviations (their next occurrence is used).
If no end is given, the default length of one hour or one day (for all-day events) is
used. If only a start time is given the new event is assumed to be starting today. If only
a time is given for the event to end on, the event ends on the same day it starts on,
unless that would make the event end before it has started, then the next day is used as
end date
If a 24:00 time is configured (timeformat = %H:%M) an end time of 24:00 is accepted as the
end of a given date.
If the summary contains the string ::, everything after :: is taken as the description of
the new event, i.e., the "body" of the event (and :: will be removed).
Passing the option --interactive (-i) makes all arguments optional and interactively
prompts for required fields, then the event may be edited, the same way as in the edit
command.
Options
• -l, --location=LOCATION specify where this event will be held.
• -g, --categories=CATEGORIES specify which categories this event belongs to. Comma
separated list of categories. Beware: some servers (e.g. SOGo) do not support multiple
categories.
• -r, --repeat=RRULE specify if and how this event should be recurring. Valid values for
RRULE are daily, weekly, monthly and yearly
• -u, --until=UNTIL specify until when a recurring event should run
• --url specify the URL element of the event
• --alarms DURATION,... will add alarm times as DELTAs comma separated for this event,
DURATION should look like 1day 10minutes or 1d3H10m, negative DURATIONs will set alarm
after the start of the event.
Examples
These may need to be adapted for your configuration and/or locale (START and END need to
match the format configured). See printformats.
khal new 18:00 Awesome Event
adds a new event starting today at 18:00 with summary 'awesome event' (lasting for the
default time of one hour) to the default calendar
khal new tomorrow 16:30 Coffee Break
adds a new event tomorrow at 16:30
khal new 25.10. 18:00 24:00 Another Event :: with Alice and Bob
adds a new event on 25th of October lasting from 18:00 to 24:00 with an additional
description
khal new -a work 26.07. Great Event -g meeting -r weekly
adds a new all day event on 26th of July to the calendar work in the meeting category,
which recurs every week.
edit
an interactive command for editing and deleting events using a search string
khal edit [--show-past] event_search_string
the command will loop through all events that match the search string, prompting the user
to delete, or change attributes.
printcalendars
prints a list of all configured calendars.
printformats
prints a fixed date (2013-12-21 21:45) in all configured date(time) formats. This is
supposed to help check if those formats are configured as intended.
search
search for events matching a search string and print them. Currently, search will print
one line for every different event in a recurrence set, that is one line for the master
event, and one line for every different overwritten event. No advanced search features
are currently supported.
The command
khal search party
prints all events matching party.
CONFIGURATION
khal reads configuration files in the ini syntax, meaning it understands keys separated
from values by a =, while section and subsection names are enclosed by single or double
square brackets (like [sectionname] and [[subsectionname]]). Any line beginning with a #
will be treated as a comment.
Help with initial configuration
If you do not have a configuration file yet, running khal configure will launch a small,
interactive tool that should help you with initial configuration of khal.
Location of configuration file
khal is looking for configuration files in the following places and order:
$XDG_CONFIG_HOME/khal/config (on most systems this is ~/.config/khal/config),
~/.khal/khal.conf (deprecated) and a file called khal.conf in the current directory
(deprecated). Alternatively you can specify which configuration file to use with -c
path/to/config at runtime.
The [calendars] section
The [calendars] section is mandatory and must contain at least one subsection. Every
subsection must have a unique name (enclosed by two square brackets). Each subsection
needs exactly one path setting, everything else is optional. Here is a small example:
[calendars]
[[home]]
path = ~/.calendars/home/
color = dark green
priority = 20
[[work]]
path = ~/.calendars/work/
readonly = True
color khal will use this color for coloring this calendar's event. The following color
names are supported: black, white, brown, yellow, dark gray, dark green, dark blue,
light gray, light green, light blue, dark magenta, dark cyan, dark red, light
magenta, light cyan, light red. Depending on your terminal emulator's settings,
they might look different than what their name implies. In addition to the 16
named colors an index from the 256-color palette or a 24-bit color code can be
used, if your terminal supports this. The 256-color palette index is simply a
number between 0 and 255. The 24-bit color must be given as #RRGGBB, where RR, GG,
BB is the hexadecimal value of the red, green and blue component, respectively.
When using a 24-bit color, make sure to enclose the color value in ' or "! If
color is set to auto (the default), khal looks for a color value in a color file in
this calendar's vdir. If the color file does not exist, the default_color (see
below) is used. If color is set to '', the default_color is always used. Note that
you can use vdirsyncer metasync to synchronize colors with your caldav server.
type color
default
auto
path The path to an existing directory where this calendar is saved as a vdir. The
directory is searched for events or birthdays (see type). The path also accepts
glob expansion via * or ? when type is set to discover. ** means arbitrary depths
of directories. This allows for paths such as ~/accounts/*/calendars/*, where the
calendars directory contains vdir directories. In addition, ~/calendars/* and
~/calendars/default are valid paths if there exists a vdir in the default
directory. (The previous behavior of recursively searching directories has been
replaced with globbing).
type string
default
None
priority
When coloring days, the color will be determined based on the calendar with the
highest priority. If the priorities are equal, then the "multiple" color will be
used.
type integer
default
10
readonly
setting this to True, will keep khal from making any changes to this calendar
type boolean
default
False
type Setting the type of this collection (default calendar).
If set to calendar (the default), this collection will be used as a standard
calendar, that is, only files with the .ics extension will be considered, all other
files are ignored (except for a possible color file).
If set to birthdays khal will expect a VCARD collection and extract birthdays from
those VCARDS, that is only files with .vcf extension will be considered, all other
files will be ignored. birthdays also implies readonly=True.
If set to discover, khal will use globbing
<https://en.wikipedia.org/wiki/Glob_(programming)> to expand this calendar's path
to (possibly) several paths and use those as individual calendars (this cannot be
used with birthday collections`). See Exemplary discover usage for an example.
If an individual calendar vdir has a color file, the calendar's color will be set
to the one specified in the color file, otherwise the color from the calendars
subsection will be used.
type option, allowed values are calendar, birthdays and discover
default
calendar
The [default] section
Some default values and behaviors are set here.
default_calendar
The calendar to use if none is specified for some operation (e.g. if adding a new
event). If this is not set, such operations require an explicit value.
type string
default
None
default_dayevent_duration
Define the default duration for an event ('khal new' only)
type timedelta
default
1h
default_event_duration
Define the defaut duration for a day-long event ('khal new' only)
type timedelta
default
1d
highlight_event_days
If true, khal will highlight days with events. Options for highlighting are in
[highlight_days] section.
type boolean
default
False
print_new
After adding a new event, what should be printed to standard out? The whole event
in text form, the path to where the event is now saved or nothing?
type option, allowed values are event, path and False
default
False
show_all_days
By default, khal displays only dates with events in list or calendar view. Setting
this to True will show all days, even when there is no event scheduled on that day.
type boolean
default
False
timedelta
Controls for how many days into the future we show events (for example, in khal
list) by default.
type timedelta
default
2d
The [highlight_days] section
When highlight_event_days is enabled, this section specifies how the highlighting/coloring
of days is handled.
color What color to use when highlighting -- explicit color or use calendar color when
set to ''
type color
default
default_color
Default color for calendars without color -- when set to '' it actually disables
highlighting for events that should use the default color.
type color
default
method Highlighting method to use -- foreground or background
type option, allowed values are foreground, fg, background and bg
default
fg
multiple
How to color days with events from multiple calendars -- either explicit color or
use calendars' colors when set to ''
type color
default
multiple_on_overflow
When multiple is set to a specific color, setting this to True will cause khal to
use that color only for days with events from 3 or more calendars (hence preserving
the two-color-highlight for days where all calendar colors can be displayed)
type boolean
default
False
The [keybindings] section
Keybindings for ikhal are set here. You can bind more than one key (combination) to a
command by supplying a comma-separated list of keys. For binding key combinations
concatenate them keys (with a space in between), e.g. ctrl n.
delete delete the currently selected event
type list
default
d
down move the cursor down (in the calendar browser)
type list
default
down, j
duplicate
duplicate the currently selected event
type list
default
p
export export event as a .ics file
type list
default
e
external_edit
edit the currently selected events' raw .ics file with $EDITOR Only use this, if
you know what you are doing, the icalendar library we use doesn't do a lot of
validation, it silently disregards most invalid data.
type list
default
meta E
left move the cursor left (in the calendar browser)
type list
default
left, h, backspace
log show logged messages
type list
default
L
mark go into highlight (visual) mode to choose a date range
type list
default
v
new create a new event on the selected date
type list
default
n
other in highlight mode go to the other end of the highlighted date range
type list
default
o
quit quit
type list
default
q, Q
right move the cursor right (in the calendar browser)
type list
default
right, l, space
save save the currently edited event and leave the event editor
type list
default
meta enter
search open a text field to start a search for events
type list
default
/
today focus the calendar browser on today
type list
default
t
up move the cursor up (in the calendar browser)
type list
default
up, k
view show details or edit (if details are already shown) the currently selected event
type list
default
enter
The [locale] section
It is mandatory to set (long)date-, time-, and datetimeformat options, all others options
in the [locale] section are optional and have (sensible) defaults.
dateformat
khal will display and understand all dates in this format, see timeformat for the
format
type string
default
%x
datetimeformat
khal will display and understand all datetimes in this format, see timeformat for
the format.
type string
default
%c
default_timezone
this timezone will be used for new events (when no timezone is specified) and when
khal does not understand the timezone specified in the icalendar file. If no
timezone is set, the timezone your computer is set to will be used.
type timezone
default
None
firstweekday
the first day of the week, where Monday is 0 and Sunday is 6
type integer, allowed values are between 0 and 6
default
0
local_timezone
khal will show all times in this timezone If no timezone is set, the timezone your
computer is set to will be used.
type timezone
default
None
longdateformat
khal will display and understand all dates in this format, it should contain a year
(e.g. %Y) see timeformat for the format.
type string
default
%x
longdatetimeformat
khal will display and understand all datetimes in this format, it should contain a
year (e.g. %Y) see timeformat for the format.
type string
default
%c
timeformat
khal will display and understand all times in this format.
The formatting string is interpreted as defined by Python's strftime
<https://docs.python.org/3/library/time.html#time.strftime>, which is similar to
the format specified in man strftime.
In the configuration file it may be necessary to enclose the format in quotation
marks to force it to be loaded as a string.
type string
default
%X
unicode_symbols
by default khal uses some unicode symbols (as in 'non-ascii') as indicators for
things like repeating events, if your font, encoding etc. does not support those
symbols, set this to False (this will enable ascii based replacements).
type boolean
default
True
weeknumbers
Enable weeknumbers in calendar and interactive (ikhal) mode by specifying whether
they should be displayed on the 'left' or 'right'. These are iso weeknumbers, so
will only work properly if firstweekday is set to 0
type weeknumbers
default
off
The [sqlite] section
path khal stores its internal caching database here, by default this will be in the
$XDG_DATA_HOME/khal/khal.db (this will most likely be ~/.local/share/khal/khal.db).
type string
default
None
The [view] section
The view section contains configuration options that effect the visual appearance when
using khal and ikhal.
agenda_day_format
Specifies how each day header is formatted.
type string
default
{bold}{name}, {date-long}{reset}
agenda_event_format
Default formatting for events used when the user asks for all events in a given
time range, used for list, calendar and in interactive (ikhal). Please note, that
any color styling will be ignored in ikhal, where events will always be shown in
the color of the calendar they belong to. The syntax is the same as for --format.
type string
default
{calendar-color}{cancelled}{start-end-time-style}
{title}{repeat-symbol}{alarm-symbol}{description-separator}{description}{reset}
blank_line_before_day
Add a blank line before the name of the day (khal only)
type boolean
default
False
bold_for_light_color
Whether to use bold text for light colors or not. Non-bold light colors may not
work on all terminals but allow using light background colors.
type boolean
default
True
dynamic_days
Defines the behaviour of ikhal's right column. If True, the right column will show
events for as many days as fit, moving the cursor through the list will also select
the appropriate day in the calendar column on the left. If False, only a fixed
([default] timedelta) amount of days' events will be shown, moving through events
will not change the focus in the left column.
type boolean
default
True
event_format
Default formatting for events used when the start- and end-date are not clear
through context, e.g. for search, used almost everywhere but list and calendar. It
is therefore probably a sensible choice to include the start- and end-date. The
syntax is the same as for --format.
type string
default
{calendar-color}{cancelled}{start}-{end}
{title}{repeat-symbol}{alarm-symbol}{description-separator}{description}{reset}
event_view_always_visible
Set to true to always show the event view window when looking at the event list
type boolean
default
False
event_view_weighting
weighting that is applied to the event view window
type integer
default
1
frame Whether to show a visible frame (with box drawing characters) around some (groups
of) elements or not. There are currently several different frame options available,
that should visually differentiate whether an element is in focus or not. Some of
them will probably be removed in future releases of khal, so please try them out
and give feedback on which style you prefer (the color of all variants can be
defined in the color themes).
type option, allowed values are False, width, color and top
default
False
min_calendar_display
Minimum number of months displayed by calendar command default is 3 months
type integer
default
3
monthdisplay
Display month name on row when the week contains the first day of the month
('firstday') or when the first day of the week is in the month ('firstfullweek')
type monthdisplay
default
firstday
theme Choose a color theme for khal.
This is very much work in progress. Help is really welcome! The two currently
available color schemes (dark and light) are defined in khal/ui/colors.py, you can
either help improve those or create a new one (see below). As ikhal uses urwid,
have a look at urwid's documentation
<http://urwid.org/manual/displayattributes.html> for how to set colors and/or at
the existing schemes. If you cannot change the color of an element (or have any
other problems) please open an issue on github.
If you want to create your own color scheme, copy the structure of the existing
ones, give it a new and unique name and also add it as an option in
khal/settings/khal.spec in the section [default] of the property theme.
type option, allowed values are dark and light
default
dark
A minimal sample configuration could look like this:
Example
[calendars]
[[home]]
path = ~/.calendars/home/
[[work]]
path = ~/.calendars/work/
[locale]
local_timezone= Europe/Berlin
default_timezone= Europe/Berlin
timeformat= %H:%M
dateformat= %d.%m.
longdateformat= %d.%m.%Y
datetimeformat= %d.%m. %H:%M
longdatetimeformat= %d.%m.%Y %H:%M
Exemplary discover usage
If you have the following directory layout:
~/calendars
├- work/
├- home/
└─ family/
where work, home and family are all different vdirs, each containing one calendar, a
matching calendar section could look like this:
[[calendars]]
path = ~/calendars/*
type = discover
color = dark green
Syncing
To get khal working with CalDAV you will first need to setup vdirsyncer
<https://github.com/pimutils/vdirsyncer>. After each start khal will automatically check
if anything has changed and automatically update its caching db (this may take some time
after the initial sync, especially for large calendar collections). Therefore, you might
want to execute khal automatically after syncing with vdirsyncer (e.g. via cron).
STANDARDS
khal tries to follow standards and RFCs (most importantly RFC 5545
<https://datatracker.ietf.org/doc/html/rfc5545.html> iCalendar) wherever possible. Known
intentional and unintentional deviations are listed below.
RDATE;VALUE=PERIOD
RDATE s with PERIOD values are currently not supported, as icalendar
<https://github.com/collective/icalendar> does not support it yet. Please submit any real
world examples of events with RDATE;VALUE=PERIOD you might encounter (khal will print
warnings if you have any in your calendars).
RANGE=THISANDPRIOR
Recurrent events with the RANGE=THISANDPRIOR are and will not be [1] supported by khal, as
applications supporting the latest standard <http://tools.ietf.org/html/rfc5546> MUST NOT
create those. khal will print a warning if it encounters an event containing
RANGE=THISANDPRIOR.
[1] unless a lot of users request this feature
Events with neither END nor DURATION
While the RFC states:
A calendar entry with a "DTSTART" property but no "DTEND"
property does not take up any time. It is intended to represent
an event that is associated with a given calendar date and time
of day, such as an anniversary. Since the event does not take up
any time, it MUST NOT be used to record busy time no matter what
the value for the "TRANSP" property.
khal transforms those events into all-day events lasting for one day (the start date). As
long a those events do not get edited, these changes will not be written to the vdir (and
with that to the CalDAV server). Any timezone information that was associated with the
start date gets discarded.
NOTE:
While the main rationale for this behaviour was laziness on part of khal's main author,
other calendar software shows the same behaviour (e.g. Google Calendar and Evolution).
Timezones
Getting localized time right, seems to be the most difficult part about calendaring (and
messing it up ends in missing the one important meeting of the week). So I'll briefly
describe here, how khal tries to handle timezone information, which information it can
handle and which it can't.
In general, there are two different type of events. Localized events (with localized start
and end datetimes) which have timezone information attached to their start and end
datetimes, and floating events (with floating start and end datetimes), which have no
timezone information attached (all-day events, events that last for complete days are
floating as well). Localized events are always observed at the same UTC
<https://en.wikipedia.org/wiki/Coordinated_Universal_Time> (no matter what time zone the
observer is in), but different local times. On the other hand, floating events are always
observed at the same local time, which might be different in UTC.
In khal all localized datetimes are saved to the local database as UTC. Datetimes that
are already UTC, e.g. 19980119T070000Z, are saved as such, others are converted to UTC
(but don't worry, the timezone information does not get lost). Floating events get saved
in floating time, independently of the localized events.
If you want to look up which events take place at a specified datetime, khal always
expects that you want to know what events take place at that local datetime. Therefore,
the (local) datetime you asked for gets converted to UTC, the appropriate localized events
get selected and presented with their start and end datetimes converted to your local
datetime. For floating events no conversion is necessary.
Khal (i.e. icalendar <https://github.com/collective/icalendar>) can understand all
timezone identifiers as used in the Olson DB <https://en.wikipedia.org/wiki/Tz_database>
and custom timezone definitions, if those VTIMEZONE components are placed before the
VEVENTS that make use of them (as most calendar programs seem to do). In case an unknown
(or unsupported) timezone is found, khal will assume you want that event to be placed in
the default timezone (which can be configured in the configuration file as well).
khal expects you always want all start and end datetimes displayed in local time (which
can be set in the configuration file as well, otherwise your computer's timezone is used).
FAQ
Frequently asked questions:
•
Installation stops with an error: source/str_util.c:25:20: fatal error: Python.h: No
such file or directory
You do not have the Python development headers installed, on Debian based
Distributions you can install them via aptitude install python-dev.
•
unknown key "default_command"
This key was deprecated by f8d9135. See
https://github.com/pimutils/khal/issues/648 for the rationale behind this
removal.
LICENSE
khal is released under the Expat/MIT License:
Copyright (c) 2013-2022 khal contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
AUTHOR
Christan Geier et al.
COPYRIGHT
Copyright (c) 2013-2022 khal contributors