An interface between org mode and khal cli calendar
MIT License
Click here for the GitHub page.
The demo below demonstrates the following features using the neovim plugin called nvim-khalorg:
khalorg new
: convert an org agenda item into a khal
agenda item.khalorg list
: convert a khal
agenda item into an org agenda item.khalorg edit
: edit an existing khal
agenda item with org mode.khalorg delete
: delete an existing khal
item.khalorg
is an interface between Org mode and Khal cli calendar.
I use org mode to manage my agenda and my notes. However, in a professional
setting, you are often required to use proprietary software for your agenda,
like Office 365. Luckily, programs exist that can synchronize agendas from
different sources, by implementing the CalDav standard. Personally, I like to
use vdirsyncer
with khal
to synchronize my agendas. To bridge the gap
between khal
and org mode
, only 1 program exists called: khalel
. However,
this program is designed for emacs
. Since there are also org mode users
outside of emacs
(e.g. neovim
), khalorg
aims to be a general interface
between vdirsyncer
/khal
and org mode
.
Based on the above, the following workflow is desired:
CalDav
vdirsyncer
khal
khalorg
org mode
khal
khalorg new
: convert an org agenda item into a khal
agendakhalorg list
: convert a khal
agenda item into an org agendakhalorg edit
: edit an existing khal
agenda item with org mode.khalorg delete
: delete an existing khal
item.+1w
). The following is supported:
+{integer}{d,w,m,y}
khalorg new
and khalorg edit --edit-dates
support 1 time stampkhalorg list
concatenates timestamps that cannot be describes byuntil
date for recurring items. The until date can beUNTIL
.For safety, always make a back-up of your calendar before installing software that is new to you.
Make sure your khal
date format is compatible with org, otherwise it
will not work. When running khal printformats
you should get:
longdatetimeformat: 2013-12-21 Sat 21:45
datetimeformat: 2013-12-21 Sat 21:45
longdateformat: 2013-12-21 Sat
dateformat: 2013-12-21 Sat
timeformat: 21:45
If not, check the documentation of khal
on how to change this.
Install by running the following command:
pip install khalorg
Set your current working directory to the root directory, i.e, the
directory containing the pyproject.toml
file. Next, run:
pip install .
After this, the executable khalorg
will be available.
If you want to develop the code, debug it, and test it, run:
pip install -e '.[test,debug]'
Use khalorg --help
to get information about the cli of khalorg
. The
following section discuss the khalorg
commands that are available.
Agenda items from khal
can be converted to org items using the
khalorg list
command. For examples:
khalorg list my_calendar today 90d > my_calendar.org
Here, the khal
agenda items of the calendar my_calendar
are
converted to org format and written to a file called my_calendar.org
.
The range is specified from today
till 90d
(90 days) in the future.
For more information about the allowed date formats, check the
khal list
command, which is used for this functionality. It is assumed
that the khal
calendar called my_calendar
exists. Make sure
my_calendar
is a calendar that exists on your local file system.
If khalorg list --format
option is not defined, the default one is
used which can be found at ./khalorg/static/khalorg_format.txt
. If you
want to define your own format, you have 2 options: you can use the
khalorg list --format
option, or you can place your custom format at
$HOME/.config/khalorg/khalorg_format.txt
this format will then be used
instead of the default one that is shown below.
* {title}
{timestamps}
:PROPERTIES:
:ATTENDEES: {attendees}
:CALENDAR: {calendar}
:CATEGORIES: {categories}
:LOCATION: {location}
:ORGANIZER: {organizer}
:STATUS: {status}
:UID: {uid}
:URL: {url}
:END:
{description}
the following keys are supported:
{attendees}
: a comma separated list of email addresses of attendees{calendar}
: the name of the khal calendar{categories}
: the categories property of the item{description}
: the description of the item{location}
: the location of the item{organizer}
: the email of the organizer{status}
: the status of the item, e.g., TENTATIVE or ACCEPTED{timestamps}
: the timestamp of the item{title}
: the summary of the item{uid}
: the UID of the item{rrule_until}
: the until value of the RRULE.{url}
: the url propertythe following keys are supported but are typically reserved for internal use and are therefore less informative:
{until}
: the until property value. Is empty when using khalorg list
.{rrule}
: the ICal RRULE of the item.The khalorg list
command relies on the khal list
command. Using this
command the RRULE
of each item is retrieved to created the correct org
repeater. Only simple org repeaters are supported that have the
following form: +[number][h,w,m,y]
. Complex RRULEs
are described by
concatenating the corresponding timestamps within 1 agenda item,
resulting in a list of items. For example, the agenda item below
represents a weekly recurring event where the first meeting was moved to
another date, resulting in a timestamp without a repeater, and one with
a repeater.
* Meeting
<2023-01-05 Thu 01:00-02:00>
<2023-01-08 Sun 01:00-02:00 +1w>
:PROPERTIES:
:UID: 123
:LOCATION: Somewhere
:ORGANIZER: Someone ([email protected])
:ATTENDEES: [email protected], [email protected]
:URL: www.test.com
:END:
Hello,
Lets have a meeting.
Regards,
Someone
An org agenda item can be converted to a new khal
agenda item by
feeding the org item through stdin to khalorg new
and specifying the
khal calendar name as a positional argument. For example, the consider
the org item below, which is saved as meeting.org
.
* Meeting
<2023-01-01 Sun 01:00-02:00 +1w>
:PROPERTIES:
:UID: 123
:LOCATION: Somewhere
:ORGANIZER: Someone ([email protected])
:ATTENDEES: [email protected], [email protected]
:URL: www.test.com
:END:
Hello,
Lets have a meeting.
Regards,
Someone
This item can be converted to the khal
calendar called
"mycalendar" as follows:
cat meeting.org | khalorg new my_calendar
It is assumed that the khal
calendar called "mycalendar"
exists. Make sure "mycalendar" is a calendar that exists on
your local file system.
Only 1 timestamp per org item is supported. Note that the meeting above
is repeated every week (+1w
). Only simple org repeaters are supported
that have the following form: +[number][h,w,m,y]
. These events repeat
forever, unless you specify an end date using the `UNTIL` property in
the org file.
Personally, when I need to create a complex repeat pattern (or when I
need outlook specific items like a Teams invite), I create the event in
outlook first. Next, I use khalorg edit
to change the fields that need
editing (e.g., the description).
Optionally, attendees can be added to the ATTENDEES
property field.
The attendees will be added to the Attendees
field of khal
. Once you
synchronize khal
with a server (e.g., outlook) an invitation will be
send to the attendees.
Existing khal
events can be updates by feeding an org file with the
corresponding UID through stdin to the khalorg edit
command. For
example, the org agenda item of New can be altered and used as an input for
khalorg edit
, as long as the UID remains untouched.
* Edited meeting
<2023-01-01 Sun 01:00-02:00 +1w>
:PROPERTIES:
:UID: 123
:ORGANIZER: Someone ([email protected])
:ATTENDEES: [email protected]
:END:
Hello,
I edited the meeting by removing the location and url. I also changed the
title and the attendees field.
Regards,
Someone
Next, run the following command:
cat meeting.org | khalorg edit my_calendar
When using khalorg edit
please consider the following:
icalendar
file is retained. Only parts of it are altered.khalorg
. For example, a Microsoft Teamkhal edit
will only update the dates + recurrence if the--edit-dates
flag is passed. This avoids editing the start-stop dateAn event can be deleted from a khal calendar by feeding an org file to the
khalorg delete
command through stdin. The org file must contain an agenda
item with a non-empty UID property. For example, the khal event that was
created using the New command
above can be removed by feeding the same file to khalorg delete
:
cat meeting.org | khalorg delete my_calendar
When deleting recurring items the whole series will be removed. Removing occurrences is not supported.
The neovim plugin can be found here: nvim-khalorg. Check out the demo at the top of the page.
The diagram below illustrates the workflow than can be achieved when using
khalorg
. The folder extras
, on the
GitHub page, contains a bash
script
called calsync
, that synchronizes vdirsyncer
calendars and exports them as
an org file using the khalorg list
command. Davmail is used as the CalDav
server in this specific example.
Office 365
Davmail
vdirsyncer
khal
khalorg
org mode
If you encounter any issues, please report them on the issue tracker at: khalorg issues
Contributions are welcome! Please see CONTRIBUTING for more information.
Distributed under the MIT License.
khalorg
will only work whenkhal
config.khalorg new
and khal edit
only support 1 timestamp per item.orgagenda
. To achieveRRULE
that describes them. Also, set the UNTIL
date toRRULE
can be found, raise an error. AnotherRDATE
option of ICal.RRULE
that describes them.