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