| KHAL(1) | khal | KHAL(1) |
khal - khal Documentation
Khal is a calendar program for the terminal for viewing, adding and editing events and calendars. Khal is build on the iCalendar and vdir (allowing the use of vdirsyncer(1) for CalDAV compatibility) standards.
Khal offers a set of commands, most importantly list, calendar, interactive, new, printcalendars, printformats, and search. See below for a description of what every command does. khal does currently not support any default command, i.e., run a command, even though none has been specified. This is intentional.
khal (without any commands) has some options to print some information about khal:
Several options are common to almost all of khal's commands (exceptions are described below):
By default, all-day events have no times. To see a start and end time anyway simply add -full to the end of any template with start/end, for instance start-time becomes start-time-full and will always show start and end times (instead of being empty for all-day events).
In addition, there are colors: black, red, green, yellow, blue, magenta, cyan, white (and their bold versions: red-bold, etc.). There is also reset, which clears the styling, and bold, which is the normal bold.
A few control codes are exposed. 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}"
If the --day-format is passed an empty string then it will not print the day headers (for an empty line pass in a whitespace character).
Almost everywhere khal accepts dates, khal should recognize relative date names like today, tomorrow and the names of the days of the week (also in three letters abbreviated form). Week day names get interpreted as the date of the next occurrence of a day with that name. 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 (no year is 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.
shows all events scheduled for a given date (or datetime) range, with custom formatting:
khal list [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT] [--day-format DAYFORMAT] [--once] [--notstarted] [START [END | DELTA] ]
START and END can both be given as dates, datetimes or times (it is 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 is not explicitly given. If DELTA, 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, is given, 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.
The --once option only allows events to appear once even if they are on multiple days. With the --notstarted option only events are shown that start after START.
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.
khal at [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT] [--notstarted] [[START DATE] TIME | now]
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.
will help users creating an initial configuration file. configure will refuse to run if there already is a configuration file.
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.
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).
When the calendar on the left is in focus, you can
When an event list is in focus, you can
In the event editor, you can
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.
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.
new accepts these combinations for start and endtimes (specifying the end is always optional):
where the formats for datetime and time are as follows:
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) makes all arguments optional and interactively prompts for required fields, then the event may be edited, the same way as in the edit command.
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.
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.
prints a list of all configured calendars.
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.
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.
The command
khal search party
prints all events matching party.
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.
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.
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 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
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 <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.
Some default values and behaviors are set here.
When highlight_event_days is enabled, this section specifies how the highlighting/coloring of days is handled.
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.
It is mandatory to set (long)date-, time-, and datetimeformat options, all others options in the [locale] section are optional and have (sensible) defaults.
The formatting string is interpreted as defined by Python's strftime <https://docs.python.org/3/library/time.html#time.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.
The view section contains configuration options that effect the visual appearance when using khal and ikhal.
This is very much work in progress. Help is really welcome! The two currently available color schemes (dark and light) are defined in khal/ui/colors.py, you can either help improve those or create a new one (see below). As ikhal uses urwid, have a look at urwid's documentation <http://urwid.org/manual/displayattributes.html> for how to set colors and/or at the existing schemes. If you cannot change the color of an element (or have any other problems) please open an issue on github.
If you want to create your own color scheme, copy the structure of the existing ones, give it a new and unique name and also add it as an option in khal/settings/khal.spec in the section [default] of the property theme.
A minimal sample configuration could look like this:
[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
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
To get khal working with CalDAV you will first need to setup vdirsyncer <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).
khal tries to follow standards and RFCs (most importantly RFC 5545 <https://datatracker.ietf.org/doc/html/rfc5545.html> iCalendar) wherever possible. Known intentional and unintentional deviations are listed below.
RDATE s with PERIOD values are currently not supported, as icalendar <https://github.com/collective/icalendar> does not support it yet. Please submit any real world examples of events with RDATE;VALUE=PERIOD you might encounter (khal will print warnings if you have any in your calendars).
Recurrent events with the RANGE=THISANDPRIOR are and will not be [1] supported by khal, as applications supporting the latest standard <http://tools.ietf.org/html/rfc5546> MUST NOT create those. khal will print a warning if it encounters an event containing RANGE=THISANDPRIOR.
While the RFC states:
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.
khal transforms those events into all-day events lasting for one day (the start date). As long a those events do not get edited, these changes will not be written to the vdir (and with that to the CalDAV server). Any timezone information that was associated with the start date gets discarded.
NOTE:
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 I'll briefly describe here, how khal tries to handle timezone information, which information it can handle and which it can't.
In general, there are two different type of events. Localized events (with localized start and end datetimes) which have timezone information attached to their start and end datetimes, and floating events (with floating start and end datetimes), which have no timezone information attached (all-day events, events that last for complete days are floating as well). 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 different local times. On the other hand, 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 are converted to UTC (but don't worry, 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 presented with their start and end datetimes converted to your local datetime. For floating events no conversion is necessary.
Khal (i.e. icalendar <https://github.com/collective/icalendar>) can understand all timezone identifiers as used in the Olson DB <https://en.wikipedia.org/wiki/Tz_database> and custom timezone definitions, if those VTIMEZONE components are placed before the VEVENTS that make use of them (as most calendar programs seem to do). 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).
Frequently asked questions:
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.
Christan Geier et al.
Copyright (c) 2013-2022 khal contributors
| February 12, 2023 | 0.10.5 |