Configuring¶
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]]).
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 specify 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
-
type
Set the type of this collection, the default is
calendar
. If set tobirthdays
khal will expect a VCARD collection and extract birthdays from those VCARDS.birthdays
also impliesreadonly=True
. If set tocalendar
only files with the.ics
extension will be used and if set tobirthdays
only files with the.vcf
extension will be used.type: option, allowed values are calendar and birthdays default: calendar
-
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
) but the search is not recursive.type: string default: None
-
readonly
setting this to True, will keep khal from making any changes to this calendar
type: boolean default: False
-
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 paltte or a 24-bit color code can be used, if your terminal supports this. The 256-color paltte 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 the color is set to ‘’ (the default), the default_color (see below) is used.
type: color default:
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.
-
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
-
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
-
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
-
datetimeformat
khal will display and understand all datetimes in this format, see timeformat for the format.
type: string default: %d.%m. %H:%M
-
dateformat
khal will display and understand all dates in this format, see timeformat for the format
type: string default: %d.%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
-
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: %d.%m.%Y
-
timeformat
khal will display and understand all times in this format.
The formatting string is interpreted as defined by Python’s strftime, which is similar to the format specified in
man strftime
.type: string default: %H:%M
-
encoding
set this to the encoding of your terminal emulator
type: string default: utf-8
-
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 [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 just add concatenate them (with a space in between), e.g. ctrl n.
-
right
move the cursor right (in the calendar browser)
type: list default: right, l, space
-
search
open a text field to start a search for events
type: list default: /
-
mark
go into highlight (visual) mode to choose a date range
type: list default: v
-
up
move the cursor up (in the calendar browser)
type: list default: up, k
-
duplicate
duplicate the currently selected event
type: list default: p
-
other
in highlight mode go to the other end of the highlighted date range
type: list default: o
-
export
export event as ICS
type: list default: e
-
new
create a new event on the selected date
type: list default: n
-
view
show details or edit (if details are already shown) the currently selected event
type: list default: enter, tab
-
today
focus the calendar browser on today
type: list default: t
-
left
move the cursor left (in the calendar browser)
type: list default: left, h, backspace
-
delete
delete the currently selected event
type: list default: d
-
down
move the cursor down (in the calendar browser)
type: list default: down, j
-
save
save the currently edited event and leave the event editor
type: list default: meta enter
The [default] section¶
The default section begins with a [default] tag. Some default values and behaviours are set here.
-
default_command
command to be executed if no command is given when executing khal
type: option, allowed values are calendar, agenda, interactive, printformats, printcalendars and ** default: calendar
-
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
-
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 requre an explicit value.
type: string default: None
-
highlight_event_days
If true, khal will highlight days with events. Options for highlighting are in [highlight_days] section.
type: boolean default: False
-
days
By default, khal show events for today and tomorrow. Setting this to a different value will show events of that amount of days by defaut.
type: integer default: 2
-
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
The [view] section¶
The view section contains config options that effect the visual appearance when using ikhal
-
event_view_weighting
This is the 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.
type: boolean default: False
-
event_view_always_visible
Set to true to always show the event view window when looking at the event list
type: boolean default: False
-
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/themes.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 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, just 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
-
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
The [highlight_days] section¶
When highlight_event_days is enabled, this section specifies how is the highlighting rendered.
-
multiple
How to color days with events from multiple calendars - either explicit color or use calendars’ colors when set to ‘’
type: color default:
-
method
Highlighting method to use - foreground or background
type: option, allowed values are foreground, fg, background and bg default: fg
-
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 se to ‘’ it actually disables highlighting for events that should use the default color.
type: color default:
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).