table of contents
KHAL(1) | khal | KHAL(1) |
NAME¶
khal - khal DocumentationKhal 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.
USAGE¶
Khal offers a set of commands, most importantly agenda, calendar, interactive, new, printcalendars, printformats, and search. See below for a description of what every command does. Calling khal without any command will invoke the default command, which can be specified in the configuration file.Options¶
khal (without any commands) has some options to print some information about khal:- --version
- Prints khal's version number and exits
- -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 (exceptions are described below):
- -v
- Be more verbose (e.g. print debugging information)
- -c CONFIGFILE
- Use an alternate configuration file
- -a CALENDAR
- Specify a calendar to use (which must be configured in the configuration file), can be used several times. Calendars not specified will be disregarded for this run.
- -d CALENDAR
- Specifiy a calendar which will be disregarded for this run, can be used several times.
- --color/--no-color
- khal will detect if standard output is not a tty, e.g., you redirect khal's output into a file, and if so remove all highlighting/coloring from its output. Use --color if you want to force highlighting/coloring and --no-color if you want coloring always removed.
dates¶
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).Commands¶
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.
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.khal at [-a CALENDAR ... | -d CALENDAR ...] [DATETIME | now]
calendar¶
shows a calendar (similar 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 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.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).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 escape 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 field you can increment and decrement the number under the cursor with ctrl+a and ctrl+x (time in 15 minute steps)
- 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] startdatetime [enddatetime] [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):
- 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).
Options¶
- -l, --location=LOCATION specify where this event will be held.
- -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
- --alarm DURATION will add an alarm DURATION before the start of the event, DURATION should look like 1day 10minutes or 1d3H10m, negative DURATIONs will set alarm after the start of the event.
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 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 -r weekly
adds a new all day event on 26th of July to the calendar work which recurs every week.
printcalendars¶
prints a list of all configured calendars.printformats¶
prints a fixed date (2013-12-11 10:09) in all configured date(time) formats. This is supposed to help check if those formats are configured as intended.search¶
search for events matching a search string and print them. Currently recurring events are only printed once. No advanced search features are currently supported.The command
khal search party
prints all events matching party.
CONFIGURING¶
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]]).Location of configuration file¶
khal is looking for a configuration file named khal.conf in the following places: in $XDG_CONFIG_HOME/khal/ (on most systems this is ~/.config/khal/ by default), ~/.khal/ and in the current directory. Alternatively you can specify with configuration file to use with -c path/to/config at runtime.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 = dark green [[work]] path = ~/.calendars/work/ readonly = True
- type
- Set the type of this collection, the default is calendar. If set to birthdays khal will expect a VCARD collection and extract birthdays from those VCARDS. birthdays also implies readonly=True. If set to calendar only files with the .ics extension will be used, if set to birthdays only files with the .vcf extension will be used, if it is set to discover khal will use all subdirectories of paths's that contain only .ics files.
- type
- option, allowed values are calendar, birthdays and discover
- default
- calendar
- 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 paltte or a 24-bit color code can be used, if your terminal supports this. The 256-color paltte 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 the color is set to auto (the default), khal tries to read the file color from this calendar's vdir, if this fails the default_color (see below) is used. If color is set to '', the default_color is always used.
- 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) but the search is not recursive.
- 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.- 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
- 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
- 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
- encoding
- set this to the encoding of your terminal emulator
- type
- string
- default
- utf-8
- 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
- datetimeformat
- khal will display and understand all datetimes in this format, see timeformat for the format.
- type
- string
- default
- %d.%m. %H:%M
- weeknumbers
- Enable weeknumbers in calendar and interactive (ikhal) mode. As those are iso weeknumbers, they only work properly if firstweekday is set to 0
- type
- weeknumbers
- default
- off
- dateformat
- khal will display and understand all dates in this format, see timeformat for the format
- type
- string
- default
- %d.%m.
- 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
- 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
- timeformat
- khal will display and understand all times in this format.
The formatting string is interpreted as defined by Python's strftime <https://docs.python.org/2/library/time.html#time.strftime>, which is similar to the format specified in man strftime.
- type
- string
- default
- %H:%M
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 just add concatenate them (with a space in between), e.g. ctrl n.- mark
- go into highlight (visual) mode to choose a date range
- type
- list
- default
- v
- duplicate
- duplicate the currently selected event
- type
- list
- default
- p
- new
- create a new event on the selected date
- type
- list
- default
- n
- export
- export event as ICS
- type
- list
- default
- e
- left
- move the cursor left (in the calendar browser)
- type
- list
- default
- left, h, backspace
- 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
- other
- in highlight mode go to the other end of the highlighted date range
- type
- list
- default
- o
- delete
- delete the currently selected event
- type
- list
- default
- d
- view
- show details or edit (if details are already shown) the currently selected event
- type
- list
- default
- enter, tab
- up
- move the cursor up (in the calendar browser)
- type
- list
- default
- up, k
- 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
- down
- move the cursor down (in the calendar browser)
- type
- list
- default
- down, j
The [default] section¶
The default section begins with a [default] tag. Some default values and behaviours are set here.- show_all_days
- By default, khal displays only dates with event in "agenda" view. Setting this to True will show all days in "agenda", even when there is no event
- type
- boolean
- default
- False
- highlight_event_days
- If true, khal will highlight days with events. Options for highlighting are in [highlight_days] section.
- type
- boolean
- default
- False
- days
- By default, khal show events for today and tomorrow. Setting this to a different value will show events of that amount of days by defaut.
- type
- integer
- default
- 2
- 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 requre an explicit value.
- type
- string
- default
- None
- default_command
- command to be executed if no command is given when executing khal
- type
- option, allowed values are calendar, agenda, interactive, printformats, printcalendars and **
- default
- calendar
- 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
The [view] section¶
The view section contains config options that effect the visual appearance when using ikhal- 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
- This is 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.
- 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
- theme
- Choose a color theme for khal.
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/themes.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, just 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.
- type
- option, allowed values are dark and light
- default
- dark
The [highlight_days] section¶
When highlight_event_days is enabled, this section specifies how is the highlighting rendered.- default_color
- Default color for calendars without color - when se 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
- color
- What color to use when highlighting - explicit color or use calendar color when set to ''
- type
- color
- default
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
syncing¶
To get khal working with CalDAV you will first need to setup vdirsyncer <https://github.com/untitaker/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).STANDARD COMPLIANCE¶
khal tries to follow standards and RFCs (most importantly RFC 5545 <https://tools.ietf.org/html/rfc5545.html> iCalendar) where ever possible. Known intentional and unintentional deviations are listed below.RDATE;VALUE=PERIOD¶
RDATE s with PERIOD values are currently not supported, asicalendar_does 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).
RANGE=THISANDPRIOR¶
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.- [1]
- unless a lot of users request this feature
Events with neither END nor DURATION¶
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:
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 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 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_) 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 a 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 (FAQ)¶
- •
- start up of khal and ikhal is very slow
- In some case the pytz (python timezone) is only available as a zip file, as pytz accesses several parts during initialization this takes some time. If time python -c "import pytz; pytz.timezone('Europe/Berlin')" takes nearly as much time as running khal, uncompressing that file via pytz via (sudo) pip unzip pytz might help.
- •
- ikhal raises an Exception: AttributeError: 'module' object has no attribute 'SimpleFocusListWalker'
- You probably need to upgrade urwid to version 1.1.0, if your OS does come with an older version of urwid you can install the latest version to userspace (with out messing up your default installation) with pip install --upgrade urwid --user.
- •
- 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, on Debian based Distributions you can install them via aptitude install python-dev.
LICENSE¶
khal is released under the Expat/MIT License:For full test of this license see /usr/share/doc/khal-doc/copyright
AUTHOR¶
Christan Geier et al.COPYRIGHT¶
2014-2017, Christan Geier et al.May 3, 2017 | 0.8.4 |