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 = 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 and light red
default:	None

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

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.

debug

whether to print debugging information or not

type:	boolean
default:	False

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 this is a rather important subcommand

type:	option, allowed values are calendar, agenda and interactive
default:	calendar

A minimal sample configuration could look like this:

agenda¶

shows all events scheduled for given dates. khal agenda should understand the following syntax:

khal agenda [-a CALENDAR ... | -d CALENDAR ...] [--days N] [DATE ...]

If no dates are supplied as arguments, today and tomorrow are used. Dates must be given in the format specified in khal’s config file as dateformat or longdateformat. If dateformat is used, the current year is implied.

--days N¶

Specify how many days’ (following each DATE) events should be shown.

calendar¶

shows a calendar (similiar to cal(1)) and agenda. khal calendar should understand the following syntax:

khal calendar [-a CALENDAR ... | -d CALENDAR ...] [--days N] [DATE ...]

Date selection works exactly as for khal agenda. The displayed calendar contains three consecutive months, where the first month is the month containing the first given date. If today is included, it is highlighted. Have a look at khal agenda for a descrption of the options.

interactive¶

invokes the interactive version of khal, can also be invoked by calling ikhal.

Use the arrow keys to navigate in the calendar. Press ‘tab’ or ‘enter’ to move the focus into the events column and ‘left arrow’ to return the focus to the calendar area. You can navigate the events column with the up and down arrows and view an event via pressing ‘enter’. Pressing ‘d’ will delete an event (a ‘D’ will appear in front of the events description, or ‘RO’ if you cannot delete that event). Pressing ‘d’ again will undelete that event.

When viewing an event’s details, pressing ‘enter’ again will open the currently selected event in a simple event editor; you can navigate with the arrow keys again. As long as the event has not been edited you can leave the editor with pressing ‘escape’. Once it has been edited you need to move down the ‘Cancel’ button and press the ‘enter’ key to discard your edits or press the ‘Save’ button to save your edits (and upload them on the next sync).

While the calendar area is focused, pressing ‘n’ will add a new event on the currently selected date.

new¶

allows for quick adding of new events. khal new should understand the following syntax:

khal new [-a CALENDAR] startdatetime [enddatetime] summary [description]

where start- and enddatetime are either datetimes or times in the formats defined in the config file. If no calendar is given via -a, the default calendar is used. new does no support -d and also -a may only be used once.

Start- and enddatetime can be one of the following:

• datetime datetime: start and end datetime specified, if no year is given (like the non-long version of dateformat, see config file, should allow), this year is used.
• datetime time: end date will be same as start date, unless that would make the event end before it has started, then the next day is used as end date
• datetime: event will last for defaulttime
• time time: event starting today at the first time and ending today at the second time, unless that would make the event end before it has started, then the next day is used as end date
• time: event starting today at time, lasting for the default length
• date date: all day event starting on the first and ending on the last event
• date: all day event starting at given date and lasting for default length

description is a string started by :: (which will be removed) and will be used as the new event’s description, i.d., the body of the event.

At the moment default length is either 1 hour or 1 day (should be configurable soon, too).

Some examples:

khal new 18:00 Awesome Event

adds a new event starting today at 18:00 with summary ‘awesome event’ (lasting for the default time of one hour) to the default calendar

khal new 25.10. 16:00 18:00 Another Event :: with Alice and Bob

adds a new event on 25th of October lasting from 16:00 to 18:00 with an additional description

khal new -a work 26.07. Great Event

adds a new all day event on 26th of July to the calendar work.

printcalendars¶

prints a list of all configured calendars.

CHANGELOG¶

• new unified documentation

  • html documentation (website) and man pages are all generated from the same sources via sphinx (type make html or make man in doc/, the result will be build in build/html or build/man respectively (also available on Read the Docs)
  • the new documentation lives in doc/
  • the package sphinxcontrib-newsfeed is needed for generating the html version (for generating an RSS feed)
  • the man pages live doc/build/man/, they can be build by running make man in doc/sphinx/

• new dependencies: configobj, tzlocal>=1.0

• IMPORTANT: the configuration file’s syntax changed (again), have a look at the new documentation for details

• local_timezone and default_timezone will now be set to the timezone the computer is set to (if they are not set in the configuration file)