# 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
        addresses = user@example.com

addresses

  All email addresses associated with this account, separated by commas. For now it is only used to check what participation status (“PARTSTAT”) belongs to the user.

  > type:

  >   list

  > default:

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 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_alarm

  Define the default alarm for new all dayevents, e.g. ‘12h’

  > type:

  >   timedelta

  > default:

default_dayevent_duration

  Define the defaut duration for a day-long event (‘khal new’ only)

  > type:

  >   timedelta

  > default:

  >   1d

default_event_alarm

  Define the default alarm for new events, e.g. ‘15m’

  > type:

  >   timedelta

  > default:

default_event_duration

  Define the default duration for an event (‘khal new’ only)

  > type:

  >   timedelta

  > default:

  >   1h

enable_mouse

  Whether the mouse should be enabled in interactive mode (‘khal interactive’ and ‘ikhal’ only)

  > type:

  >   boolean

  > default:

  >   True

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, 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 [palette] section

Override ikhal’s color theme with a custom palette. This is useful to style certain elements of ikhal individually. Palette entries take the form of key = foreground, background, mono, foreground_high, background_high where foreground and background are used in “low color mode” and foreground_high and background_high are used in “high color mode” and mono if only monocolor is supported. If you don’t want to set a value for a certain color, use an empty string (‘’). Valid entries for low color mode are listed on the urwid website. For high color mode you can use any valid 24-bit color value, e.g. ‘#ff0000’.

Note

24-bit colors must be enclosed in single quotes to be parsed correctly, otherwise the # will be interpreted as a comment.

Most modern terminals should support high color mode.

Example entry (particular ugly):

    [palette]
    header = light red, default, default, '#ff0000', default
    edit = '', '', 'bold', '#FF00FF', '#12FF14'
    footer = '', '', '', '#121233', '#656599'

See the default palettes in khal/ui/colors.py for all available keys. If you can’t theme an element in ikhal, please open an issue on github.

### 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.

  Khal ships with two color themes, dark and light. Additionally, plugins might supply different color schemes. You can also define your own color theme in the [palette] section.

  > type:

  >   string

  > 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).