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]]).
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
[[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 the color is set to auto (the default), khal tries to read the file color from this calendar’s vdir, if this fails the default_color (see below) is used. If color is set to ‘’, the default_color is always used.
- 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. 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
-
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.ics
extension will be considered, all other files will be ignored.birthdays
also impliesreadonly=True
.If set to
discover
, khal will use globbing 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_command
Command to be executed if no command is given when executing khal.
- type
option, allowed values are calendar, list, interactive, printformats, printcalendars, printics and **
- default
calendar
-
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
The [keybindings] section¶
Keybindings for ikhal are set here. You can bind more then 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
-
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
%d.%m.
-
datetimeformat
khal will display and understand all datetimes in this format, see timeformat for the format.
- type
string
- default
%d.%m. %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
-
firstweekday
the first day of the week, were 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
%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
-
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
-
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. As those are iso weeknumbers, they 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}{description-separator}{description}{reset}
-
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}{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
-
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 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. 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).