Configuring khal¶
khal reads configuration files in the ini syntax, meaning in understands keys separated from values by a =, while section and subsection names are enclosed by single or double square brackets (like [sectionname] and [[subsectionname]].
Location of configuration file¶
Khal is looking for a configuration file named khal.conf in the following places: in $XDG_CONFIG_HOME/khal/ (on most systems this is ~/.config/khal/ by default), ~/.khal/ and in the current directory. Alternatively you can specifiy with configuration file to use with -c path/to/config at runtime.
The [calendars] section¶
The [calendars] is mandatory and must contain at least one subsection. Every subsection must have a unique name (enclosed by two square brackets). Each subection needs exactly one path setting, everything else is optional. Here is a small example:
[calendars]
[[home]]
path = ~/.calendars/home/
color = dark green
[[work]]
path = ~/.calendars/work/
readonly = True
- color
khal will use this color for coloring this calendar’s event. Depending on your terminal emulator’s settings, they might look different than what their name implies.
type: option, allowed values are black, white, brown, yellow, dark grey, dark green, dark blue, light grey, light green, light blue, dark magenta, dark cyan, dark red, light magenta, light cyan, light red and ** default:
- path
the path to a vdir where this calendar is saved
type: string default: None
- readonly
setting this to True, will keep khal from making any changes to this calendar
type: boolean default: False
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 [locale] section¶
The most important options in the the [locale] section are probably (long-)time and dateformat.
- encoding
set this to the encoding of your terminal emulator
type: string default: utf-8
- 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
- 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
- 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: %d.%m.%Y
- 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: %d.%m.%Y %H:%M
- 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
- datetimeformat
khal will display and understand all datetimes in this format, see timeformat for the format.
type: string default: %d.%m. %H:%M
- weeknumbers
Enable weeknumbers in calendar and interactive (ikhal) mode. As those are iso weeknumbers, they only work properly if firstweekday is set to 0
type: weeknumbers default: off
- timeformat
khal will display and understand all times in this format, use the standard format as understood by strftime, see https://strftime.net or man strftime
type: string default: %H:%M
- dateformat
khal will display and understand all dates in this format, see timeformat for the format
type: string default: %d.%m.
- firstweekday
the day first day of the week, were Monday is 0 and Sunday is 6
type: integer, allowed values are between 0 and 6 default: 0
The [default] section¶
The default section begins with a [default] tag. Some default values and behaviours are set here.
- default_calendar
the calendar to use if no one is specified but only one can be used (e.g. if adding a new event), this should be a valid calendar name.
type: string default: None
- default_command
command to be executed if no command is given when executing khal
type: option, allowed values are calendar, agenda, interactive and ** default: calendar
- 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 event in “agenda” view. Setting this to True will show all days in “agenda”, even when there is no event
type: boolean default: False
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
syncing¶
To get khal working with CalDAV you will first need to setup 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).