KHAL(1)

📦
version 0.14.0 · 6 versions
, in ubuntu stonking

💖 KHAL(1) 💖

bestie. sit down. grab a snack 🍓. we're talking about khal, and honestly? she's iconic.

🌸 NAME 🌸

khal — khal Documentation ✨

okay so like: khal is a calendar program for the terminal, for viewing, adding and editing events and calendars. no cap. and the way it's built?? it's built on the iCalendar and vdir standards (which is what lets you use vdirsyncer(1) for CalDAV compatibility 💅). periodt.

💅 USAGE 💅

khal hands you a whole lil set of commands, and the most important ones are list, calendar, interactive, new, printcalendars, printformats, and search. scroll down for what each and every one of them does 👑

and now the part everyone gets wrong: khal does not currently support any default command, i.e. it will not run a command even though none has been specified. and that is intentional. it's giving on purpose. 😌

✨ Options ✨

khal (with no commands attached) has a couple of options that just print some info about khal:

  • --version — prints khal's version number and then dips out. bye bestie 👋
  • -h, --help — prints a summary of khal's options and commands, and then exits.

Several options are common to almost all of khal's commands (the exceptions get described below, dw):

  • -v, --verbosity LVL — sets how chatty things are (like, print debugging information and stuff). LVL has to be one of CRITICAL, ERROR, WARNING, INFO, or DEBUG.
  • -l, --logfile LOFILE — use logfile LOFILE for logging. the default is logging to stdout.
  • -c CONFIGFILE — use an alternate configuration file.
  • -a CALENDAR — pick a calendar to use (it must be configured in the configuration file). you can use this several times. any calendar you did not specify gets disregarded for this run 🙈
  • -d CALENDAR — pick a calendar that will be disregarded for this run. can be used several times.
  • --color / --no-color — khal detects if standard output is not a tty (like, if you redirect khal's output into a file) and if so it removes all the highlighting/coloring from its output. use --color if you want to force highlighting/coloring, and --no-color if you want coloring always removed 💅
  • --format FORMAT — for all of khal's commands that print events, you can specify how that event gets formatted with this option. FORMAT is a template string, and identifiers wrapped in curly braces ({}) get expanded to an event's properties. FORMAT supports all the formatting options that python's str.format() offers (because that's what's used internally). the available template options are:
    • title — the title of the event.
    • description — the description of the event.
    • description-separator — a separator, " :: ", that appears when there is a description.
    • uid — the UID of the event.
    • start — the start datetime in datetimeformat.
    • start-long — the start datetime in longdatetimeformat.
    • start-date — the start date in dateformat.
    • start-date-long — the start date in longdateformat.
    • start-time — the start time in timeformat.
    • end — the end datetime in datetimeformat.
    • end-long — the end datetime in longdatetimeformat.
    • end-date — the end date in dateformat.
    • end-date-long — the end date in longdateformat.
    • end-time — the end time in timeformat.
    • repeat-symbol — a repeating symbol (loop arrow) if the event is repeating.
    • alarm-symbol — an alarm symbol (alarm clock) if the event has at least one alarm.
    • location — the event location.
    • calendar — the calendar name.
    • calendar-color — changes the output color to the calendar's color.
    • start-style — the start time in timeformat OR an appropriate symbol.
    • to-style — a hyphen - or nothing, such that it appropriately fits between start-style and end-style.
    • end-style — the end time in timeformat OR an appropriate symbol.
    • start-end-time-style — a concatenation of start-style, to-style, and end-style OR an appropriate symbol.
    • end-necessary — for an allday event this is an empty string, unless the end date and start date are different. for a non-allday event this shows the time, or the datetime if the event start and end date are different.
    • end-necessary-long — same as end-necessary but uses datelong and datetimelong.
    • status — the status of the event (if this event has one), something like CONFIRMED or CANCELLED.
      • status-symbol — the status of the event as a symbol, ✓ or ✗ or ?.
      • partstat-symbol — the participation status of the event as a symbol, ✓ or ✗ or ?.
    • cancelled — the string CANCELLED (plus one blank) if the event's status is cancelled, otherwise nothing.
    • organizer — the organizer of the event 💌. if the format has CN in it, it returns "CN (email)"; if CN does not exist it returns just the email string. so like:
ORGANIZER;CN=Name Surname:mailto:name@mail.com

returns Name Surname (name@mail.com), and if it has no CN attribute it returns the last element after the colon:

ORGANIZER;SENT-BY="mailto:toemail@mail.com":mailto:name@mail.com

returns name@mail.com

  • url — the URL embedded in the event, otherwise nothing.
  • url-separator — a separator, " :: ", that appears when there is a url.
  • duration — the duration of the event in terms of days, hours, months, and seconds (abbreviated to d, h, m, and s respectively).
  • repeat-pattern — the raw iCal recurrence rule if the event is repeating.
  • all-day — a boolean indicating whether it is an all-day event or not.
  • categories — the categories of the event.

by default, all-day events have no times. if you wanna see a start and end time anyway, just add -full to the end of any template with start/end or duration — for instance start-time becomes start-time-full and will always show start and end times (instead of being empty for all-day events) 🕐

also there are colors: black, red, green, yellow, blue, magenta, cyan, white (and their bold versions: red-bold, etc.). there's also reset, which clears the styling, and bold, which is the normal bold.

a few control codes are exposed too. you can access newline (nl), 'tab', and 'bell'. control codes, such as nl, are best used with --list mode.

below is an example command which prints the title and description of all events today:

khal list --format "{title} {description}"
  • --json FIELD ... — works similar to --format, but instead of defining a format string, a JSON object is created for each specified field. the matching events get collected into a JSON array. this option accepts the following subset of --format template options:
title, description, uid, start, start-long, start-date,
start-date-long, start-time, end, end-long, end-date,
end-date-long, end-time, start-full, start-long-full,
start-date-full, start-date-long-full, start-time-full,
end-full, end-long-full, end-date-full, end-date-long-full,
end-time-full, repeat-symbol, location, calendar,
calendar-color, start-style, to-style, end-style,
start-end-time-style, end-necessary, end-necessary-long,
status, cancelled, organizer, url, duration, duration-full,
repeat-pattern, all-day, categories

note that calendar-color will be the actual color name rather than the ANSI color code, and the repeat-symbol, status, and cancelled values will have leading/trailing whitespace stripped. additionally, if only the special value all is specified, then all fields will be enabled 👑

below is an example command which prints a JSON list of objects containing the title and description of all events today:

khal list --json title --json description
  • --day-format DAYFORMAT — works similar to --format, but for day headings 📆. it only has a few options (in addition to all the color options):
    • date — the date in dateformat.
    • date-long — the date in longdateformat.
    • name — the date's name (Monday, Tuesday,…) or today or tomorrow.

if --day-format is passed an empty string, then it will not print the day headers (for an empty line, pass in a whitespace character).

🗓️ dates 🗓️

basically everywhere khal accepts dates, it should also recognize relative date names like today, tomorrow, and the names of the days of the week (three-letter abbreviated forms count too 💖). week day names get interpreted as the date of the next occurrence of a day with that name. and the name of the current day gets interpreted as that date next week (i.e. seven days from now).

if a short datetime format is used (like, no year given), khal will interpret the date to be in the future. the inferred — it might be in the next year if the given date has already passed in the current year.

👑 Commands 👑

list

shows all events scheduled for a given date (or datetime) range, with custom formatting ✨:

khal list [-a CALENDAR ... | -d CALENDAR ...]
[--format FORMAT] [--json FIELD ...] [--day-format DAYFORMAT]
[--once] [--notstarted] [START [END | DELTA] ]

START and END can both be given as dates, datetimes or times (it's assumed today is meant in the case of only a given time) in the formats configured in the configuration file.

if END is not given, midnight of the start date is assumed.

today is used for START if it isn't explicitly given.

if DELTA is given — a (date)time range in the format I{m,h,d}, where I is an integer and m means minutes, h means hours, and d means days — then END is assumed to be START + DELTA. a value of eod is also accepted as DELTA and means the end of day of the start date. in addition, the DELTA week may be used to specify that the daterange should actually be the week containing the START. slay 🌈

The --once option only lets an event show up once, even if it's sitting on multiple days. With --notstarted you only get events that actually start after START. <em>periodt.</em>

✨ Some examples ✨

Including or excluding specific calendars, because sometimes you just want one vibe:

  • khal list -d soccer will display events, in list form, from every calendar except "soccer." 🙈
  • khal list -a soccer will display events, in list form, from only the "soccer" calendar. 💅

Working with date ranges, bestie:

  • khal list -a soccer today 30d will show all events in next 30 days (from the "soccer" calendar).
  • khal list 2019-12-01 31d will show all all events for the 31 days following Dec 1, 2019.

🌸 at

shows all events scheduled for a given datetime. khal at should be supplied with a date and time, a time (the date is then assumed to be today) or the string now. at defaults to now. The at command works just like the list command, except it has an implicit end time of zero minutes after the start. (so basically a tiny little snapshot moment, iconic)

khal at [-a CALENDAR ... | -d CALENDAR ...]
[--format FORMAT] [--json FIELD ...]
[--notstarted] [[START DATE] TIME | now]

🎀 calendar

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

khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME]
[END DATETIME]

Date selection works exactly as for khal list. 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 list for a description of the options. 🗓️✨

🦋 configure

will help users creating an initial configuration file. configure will refuse to run if there already is a configuration file. (it's giving "you already did this, girl, sit down")

💜 import

lets the user import .ics files with the following syntax:

khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE

If an event with the same UID is already present in the (implicitly) selected calendar khal import will ask before updating (i.e. overwriting) that old event with the imported one, unless --batch is given, than it will always update. If this behaviour is not desired, use the --random-uid flag to generate a new, random UID. If no calendar is specified (and not --batch), you will be asked to choose a calendar. You can either enter the number printed behind each calendar's name or any unique prefix of a calendar's name. 🍓

👑 interactive

invokes the interactive version of khal, can also be invoked by calling ikhal. While ikhal can be used entirely with the keyboard, some elements respond if clicked on with a mouse (mostly by being selected). mouse girls, you're valid too

When the calendar on the left is in focus, you can

  • move through the calendar (default keybindings are the arrow keys, space and backspace, those keybindings are configurable in the config file)
  • focus on the right column by pressing tab or enter
  • re-focus on the current date, default keybinding t as in today
  • marking a date range, default keybinding v, as in visual, think visual mode in Vim, pressing esc escapes this visual mode
  • if in visual mode, you can select the other end of the currently marked range, default keybinding o as in other (again as in Vim)
  • create a new event on the currently focused day (or date range if a range is selected), default keybinding n as in new
  • search for events, default keybinding /, a pop-up will ask for your search term

When an event list is in focus, you can

  • view an event's details with pressing enter (or tab) and edit it with pressing enter (or tab) again (if [default] event_view_always_visible is set to True, the event in focus will always be shown in detail)
  • toggle an event's deletion status, default keybinding d as in delete, events marked for deletion will appear with a D in front and will be deleted when khal exits.
  • duplicate the selected event, default keybinding p as in duplicate (d was already taken) 😭
  • export the selected event, default keybinding e

In the event editor, you can

  • jump to the next (previous) selectable element with pressing tab (shift+tab)
  • quick save, default keybinding meta+enter (meta will probably be alt)
  • use some common editing short cuts in most text fields (ctrl+w deletes word before cursor, ctrl+u (ctrl+k) deletes till the beginning (end) of the line, ctrl+a (ctrl+e) will jump to the beginning (end) of the line
  • in the date and time fields you can increment and decrement the number under the cursor with ctrl+a and ctrl+x (time in 15 minute steps)
  • in the date fields you can access a miniature calendar by pressing enter
  • activate actions by pressing enter on text enclosed by angled brackets, e.g. < Save > (sometimes this might open a pop up)

Pressing esc will cancel the current action and/or take you back to the previously shown pane (i.e. what you see when you open ikhal), if you are at the start pane, ikhal will quit on pressing esc again. 🫶

🌈 new

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

khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
[:: DESCRIPTION]]

where start- and enddatetime are either datetimes, times, or keywords and times in the formats defined in the config file. If no calendar is given via -a, the default calendar is used. new does not support -d and also -a may only be used once. (one -a, that's the rule, don't push it)

new accepts these combinations for start and endtimes (specifying the end is always optional):

  • datetime [datetime|time] [timezone]
  • time [time] [timezone]
  • date [date]

where the formats for datetime and time are as follows:

  • datetime = (longdatetimeformat|datetimeformat|keyword-date timeformat)
  • time = timeformat
  • date = (longdateformat|dateformat)

and timezone, which describes the timezone the events start and end time are in, should be a valid Olson DB identifier (like Europe/Berlin or America/New_York. If no timezone is given, the defaulttimezone as configured in the configuration file is used instead.

The exact format of longdatetimeformat, datetimeformat, timeformat, longdateformat and dateformat can be configured in the configuration file. Valid keywords for dates are today, tomorrow, the English name of all seven weekdays and their three letter abbreviations (their next occurrence is used). ✨

If no end is given, the default length of one hour or one day (for all-day events) is used. If only a start time is given the new event is assumed to be starting today. If only a time is given for the event to end on, the event ends on the same day it starts on, unless that would make the event end before it has started, then the next day is used as end date

If a 24:00 time is configured (timeformat = %H:%M) an end time of 24:00 is accepted as the end of a given date.

If the summary contains the string ::, everything after :: is taken as the description of the new event, i.e., the "body" of the event (and :: will be removed).

Passing the option --interactive (-i </usr/share/doc/python3-doc/html/using/cmdline.html#cmdoption-i>) makes all arguments optional and interactively prompts for required fields, then the event may be edited, the same way as in the edit command.

💖 Options

  • -l, --location=LOCATION — specify where this event will be held.
  • -g, --categories=CATEGORIES — specify which categories this event belongs to. Comma separated list of categories. Beware: some servers (e.g. SOGo) do not support multiple categories. (rude of them tbh)
  • -r, --repeat=RRULE — specify if and how this event should be recurring. Valid values for RRULE are daily, weekly, monthly and yearly
  • -u, --until=UNTIL — specify until when a recurring event should run
  • --url — specify the URL element of the event
  • --alarms DURATION,... — will add alarm times as DELTAs comma separated for this event, DURATION should look like 1day 10minutes or 1d3H10m, negative DURATIONs will set alarm after the start of the event.

⭐ Examples

These may need to be adapted for your configuration and/or locale (START and END need to match the format configured). See printformats.

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 tomorrow 16:30 Coffee Break

adds a new event tomorrow at 16:30

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

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

khal new -a work 26.07. Great Event -g meeting -r weekly

adds a new all day event on 26th of July to the calendar work in the meeting category, which recurs every week.

🧚 edit

an interactive command for editing and deleting events using a search string

khal edit [--show-past] event_search_string

the command will loop through all events that match the search string, prompting the user to delete, or change attributes. (one by one, bestie, buckle up)

🎀 printcalendars

prints a list of all configured calendars.

🌟 printformats

prints a fixed date (2013-12-21 21:45) in all configured date(time) formats. This is supposed to help check if those formats are configured as intended. vibe check for your formats, basically

search for events matching a search string and print them. Currently, search will print one line for every different event in a recurrence set, that is one line for the master event, and one line for every different overwritten event. No advanced search features are currently supported. (keep expectations realistic, ok?)

The command

khal search party

prints all events matching party. 🎉

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

🫶 heads up bestie: two of those spots are deprecated, so don't be out here building your whole life on ~/.khal/khal.conf or ./khal.conf, okay?

🌸 The [calendars] Section 🌸

Ok bestie, listen — this section is mandatory, no skipping it, and it has to have at least one subsection. Every subsection needs a unique name (and that name lives wrapped in two square brackets, okay? two, not one). Each subsection needs exactly one path setting — that's the non-negotiable one — and literally everything else is optional. Here's a lil baby example so you can see the vibe:

[calendars]

  [[home]]
    path = ~/.calendars/home/
    color = dark green
    priority = 20

  [[work]]
    path = ~/.calendars/work/
    readonly = True
    addresses = user@example.com
  • addresses — Every email address tied to this account, separated by commas. Ngl, right now it's only used to check what participation status (that's "PARTSTAT") belongs to you.
    • type: list
    • default: (blank)
  • color — khal will use this color to colorize this calendar's event, cute right? Here are the color names that 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. Heads up though — depending on your terminal emulator's settings, they might look totally different than what their name implies 🙈. On top of those 16 named colors, you can also use an index from the 256-color palette or a 24-bit color code, but only if your terminal supports it. The 256-color palette index is just a number between 0 and 255. The 24-bit color has to be given as #RRGGBB, where RR, GG, BB is the hexadecimal value of the red, green and blue component, respectively. When you're using a 24-bit color, make sure to enclose the color value in ' or " ! If color is set to auto (which is the default), khal goes looking for a color value in a color file inside this calendar's vdir. If that color file doesn't exist, the default_color (see below, bestie) gets used. If color is set to '', then default_color is always used. Also psst — you can use vdirsyncer metasync to synchronize colors with your caldav server. Iconic.
    • type: color
    • default: auto
  • path — The path to an existing directory where this calendar is saved as a vdir. That directory gets searched for events or birthdays (see type). The path also accepts glob expansion via * or ? when type is set to discover. And ** means arbitrary depths of directories. This lets you use 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. (Heads up: the previous behavior of recursively searching directories has been replaced with globbing — so don't come at it expecting the old ways 💀.)
    • type: string
    • default: None
  • priority — When it's coloring days, the color gets determined based on the calendar with the highest priority. If the priorities are equal, then the "multiple" color gets used instead.
    • type: integer
    • default: 10
  • readonly — Setting this to True keeps khal from making any changes to this calendar. Absolutely locked, no edits, no cap 🔒.
    • type: boolean
    • default: False
  • type — Setting the type of this collection (the default calendar). Okay this one has lore, let me break it down:
    • If set to calendar (the default), this collection is used as a standard calendar — that is, only files with the .ics extension will be considered, and 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, and all other files will be ignored. Also birthdays implies readonly=True. Periodt.
    • If set to discover, khal will use globbing <https://en.wikipedia.org/wiki/Glob_(programming)> 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 get set here. The vibes presets, if you will.

  • default_calendar — The calendar to use if none is specified for some operation (like when you're adding a new event). If this isn't set, those operations will 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: (blank)
  • 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: (blank)
  • 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. The options for highlighting live in the [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? Choose your fighter.
    • 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. The glow-up station 💅.

  • color — What color to use when highlighting — either an explicit color or use calendar color when set to ''.
    • type: color
    • default: (blank)
  • 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: (blank)
  • 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 an explicit color or use calendars' colors when set to ''.
    • type: color
    • default: (blank)
  • 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. And for binding key combinations, concatenate the 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

enter — that's the default, and honestly? It ate. No notes. 💅

The [locale] section 🌍

Okay bestie, pay attention because this one is not fully optional. You are required to set the (long)date-, time-, and datetimeformat options. Like, all of them. Mandatory mandatory. Everything else in the [locale] section is optional and has (sensible) defaults, so you can just vibe with those.

  • dateformat — khal will display and understand all dates in this format. Wanna know how the format string works? Go peep timeformat below, it's the same deal.
    • type: string
    • default: %x
  • datetimeformat — khal will display and understand all datetimes in this format. Same formatting rules as timeformat, again.
    • type: string
    • default: %c
  • default_timezone — this timezone gets used for new events (aka when you don't specify a timezone) and also when khal literally cannot understand the timezone that's in the icalendar file. If you don't set a timezone here, khal falls back to whatever timezone your computer is set to.
    • 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. And if no timezone is set? You guessed it, your computer's timezone gets the job. 🫶
    • type: timezone
    • default: None
  • longdateformat — khal displays and understands all dates in this format, and it should contain a year (like %Y, okay?). See timeformat for the formatting rules.
    • type: string
    • default: %x
  • longdatetimeformat — same situation but for datetimes, and it also should contain a year (e.g. %Y). See timeformat.
    • type: string
    • default: %c
  • timeformat — khal will display and understand all times in this format.

The formatting string is interpreted exactly as defined by Python's strftime — that's over at https://docs.python.org/3/library/time.html#time.strftime — which is similar to the format specified in man strftime.

Heads up: in the configuration file it may be necessary to enclose the format in quotation marks to force it to be loaded as a string. Don't get caught out. 🙈
  • type: string
  • default: %X
  • unicode_symbols — by default khal uses some unicode symbols (as in 'non-ascii', bestie) as indicators for things like repeating events. If your font, encoding etc. does not support those symbols, set this to False and it'll enable ascii based replacements instead. ✨
    • type: boolean
    • default: True
  • weeknumbers — enables weeknumbers in calendar and interactive (ikhal) mode. You specify whether they should be displayed on the 'left' or 'right'. These are iso weeknumbers, so they will only work properly if firstweekday is set to 0. Facts.
    • type: weeknumbers
    • default: off

The [palette] section 🎨

This is where you override ikhal's color theme with a custom palette. It's genuinely useful when you want to style certain elements of ikhal individually — like, yes, that element, the one that's been bothering you.

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 over at http://urwid.org/manual/displayattributes.html#standard-foreground-colors. 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. Protect your hex codes, bestie. 😭

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. And if you can't theme an element in ikhal, please open an issue on github at https://github.com/pimutils/khal/issues/new/choose — they want to know, fr fr.

The [sqlite] section 🗄️

  • path — khal stores its internal caching database here. By default this will be in the $XDG_CACHE_HOME/khal/khal.db (which will most likely be ~/.cache/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. Aesthetic section, honestly.

  • agenda_day_format — specifies how each day header is formatted.
    • type: string
    • default: {bold}{name}, {date-long}{reset}
  • agenda_event_format — the default formatting for events, used when you ask for all events in a given time range. It's used for list, calendar, and in interactive (ikhal) mode. 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. Sorry babes, that's just the rules. 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 — adds 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 they do allow using light background colors. Trade-offs, bestie.
    • 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, and 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, and 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 — 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 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 the calendar command, default is 3 months.
    • type: integer
    • default: 3
  • monthdisplay — display the month name on a 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. Main character energy, genuinely. 👑

  • 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 — that's at https://github.com/pimutils/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). Let it cook on a schedule, bestie. ⭐

🌈 STANDARDS 🌈

okay so bestie, khal is an overachiever (affectionate) and genuinely tries to follow standards and RFCs wherever it possibly can — the big one being RFC 5545 iCalendar (https://datatracker.ietf.org/doc/html/rfc5545.html). But perfection is a myth 💀 so here are the known deviations, both the intentional ones and the oops ones, listed below fr fr.

🎀 RDATE;VALUE=PERIOD 🎀

RDATEs with PERIOD values are currently not supported, because icalendar (https://github.com/collective/icalendar) does not support it yet. So if you've got real-world examples of events with RDATE;VALUE=PERIOD, please submit them, bestie, they want to see them!! Also good news: khal will print warnings if you have any of those in your calendars, so you won't be blindsided 💖

🚫 RANGE=THISANDPRIOR 🚫

Recurrent events with RANGE=THISANDPRIOR are not supported by khal and never will be [1], because applications that support the latest standard (http://tools.ietf.org/html/rfc5546) MUST NOT create those. So, like, it's a them problem, not a us problem 💅 khal will print a warning if it encounters an event containing RANGE=THISANDPRIOR.

[1] unless a lot of users request this feature 🙈

🗓️ Events with neither END nor DURATION 🗓️

so the RFC says this, verbatim:

A calendar entry with a "DTSTART" property but no "DTEND" property does not take up any time. It is intended to represent an event that is associated with a given calendar date and time of day, such as an anniversary. Since the event does not take up any time, it MUST NOT be used to record busy time no matter what the value for the "TRANSP" property.

...and khal does not do that. Instead, khal transforms those events into all-day events lasting for one day (the start date). And here's the tea: as long as those events don't get edited, these changes will not be written to the vdir (and with that, not to the CalDAV server either). Any timezone information that was associated with the start date gets discarded 😭

Note: lowkey the main rationale for this behaviour was laziness on the part of khal's main author 🙈 but other calendar software shows the same behaviour (e.g. Google Calendar and Evolution), so. solidarity ✨

🌍 Timezones 🌍

Getting localized time right seems to be the most difficult part about calendaring — and messing it up ends in missing the one important meeting of the week 😭 so here's a brief rundown of how khal tries to handle timezone info, what it can handle, and what it absolutely cannot.

In general, there are two different types of events:

  • Localized events (with localized start and end datetimes) — these have timezone information attached to their start and end datetimes. Localized events are always observed at the same UTC (https://en.wikipedia.org/wiki/Coordinated_Universal_Time) no matter what time zone the observer is in, but at different local times.
  • Floating events (with floating start and end datetimes) — these have no timezone information attached. All-day events, and events that last for complete days, are floating as well. Floating events are always observed at the same local time, which might be different in UTC.

In khal, all localized datetimes are saved to the local database as UTC. Datetimes that are already UTC, e.g. 19980119T070000Z, are saved as such; others get converted to UTC (but don't worry bestie, the timezone information does not get lost 🫶). Floating events get saved in floating time, independently of the localized events.

If you want to look up which events take place at a specified datetime, khal always expects that you want to know what events take place at that local datetime. Therefore, the (local) datetime you asked for gets converted to UTC, the appropriate localized events get selected, and they get presented with their start and end datetimes converted to your local datetime ✨ For floating events, no conversion is necessary.

khal — like, specifically icalendar (https://github.com/collective/icalendar) — can understand all timezone identifiers as used in the Olson DB (https://en.wikipedia.org/wiki/Tz_database), plus custom timezone definitions, if those VTIMEZONE components are placed before the VEVENTs that make use of them (which is what most calendar programs seem to do anyway). In case an unknown (or unsupported) timezone is found, khal will assume you want that event to be placed in the default timezone — which can be configured in the configuration file as well 👑

khal expects you always want all start and end datetimes displayed in local time (which can be set in the configuration file as well, otherwise your computer's timezone is used).

🙋 FAQ 🙋

Frequently asked questions, aka the group chat highlights:

  • Installation stops with an error: source/str_util.c:25:20: fatal error: Python.h: No such file or directory You do not have the Python development headers installed, bestie 😭 on Debian based Distributions you can install them via aptitude install python-dev.
  • unknown key "default_command" This key was deprecated by f8d9135. See https://github.com/pimutils/khal/issues/648 for the rationale behind this removal. rip 🪦

📜 LICENSE 📜

khal is released under the Expat/MIT License:

Copyright (c) 2013-2022 khal contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

✍️ Author ✍️

Christan Geier et al.

Copyright (c) 2013-2022 khal contributors

and that's a wrap, bestie!! 🎀 this whole thing is version 0.14.0+ds, dated Aug 15, 2026 — go forth and calendar responsibly, you absolute icon 👑💖

📦 where this page comes from