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.
khal (without any commands) has some options to print some information about khal:
Prints khal’s version number and exits
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):
Be more verbose (e.g. print debugging information)
Use an alternate configuration file
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.
Specifiy a calendar which will be disregarded for this run, can be used several times.
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.
Specify how many days’ (following each DATE) events should be shown.
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]
shows a calendar (similiar to cal(1)) and agenda. khal calendar should understand the following syntax:
khal calendar [-a CALENDAR ... | -d CALENDAR ...] [--days N] [DATE ...]
Date selection works exactly as for khal agenda. The displayed calendar contains three consecutive months, where the first month is the month containing the first given date. If today is included, it is highlighted. Have a look at khal agenda for a descrption of the options.
invokes the interactive version of khal, can also be invoked by calling ikhal.
Use the arrow keys to navigate in the calendar. Press ‘tab’ or ‘enter’ to move the focus into the events column and ‘left arrow’ to return the focus to the calendar area. You can navigate the events column with the up and down arrows and view an event via pressing ‘enter’. Pressing ‘d’ will delete an event (a ‘D’ will appear in front of the events description, or ‘RO’ if you cannot delete that event). Pressing ‘d’ again will undelete that event.
When viewing an event’s details, pressing ‘enter’ again will open the currently selected event in a simple event editor; you can navigate with the arrow keys again. As long as the event has not been edited you can leave the editor with pressing ‘escape’. Once it has been edited you need to move down the ‘Cancel’ button and press the ‘enter’ key to discard your edits or press the ‘Save’ button to save your edits (and upload them on the next sync).
While the calendar area is focused, pressing ‘n’ will add a new event on the currently selected date.
allows for quick adding of new events. khal new should understand the following syntax:
khal new [-a CALENDAR] [OPTIONS] startdatetime [enddatetime] summary [description]
where start- and enddatetime are either datetimes or times in the formats defined in the config file. If no calendar is given via -a, the default calendar is used. new does no support -d and also -a may only be used once.
Start- and enddatetime can be one of the following:
description is a string started by :: (which will be removed) and will be used as the new event’s description, i.d., the body of the event.
The default length is either 1 hour or 1 day, depending on the type of event.
khal new 18:00 Awesome Event
adds a new event starting today at 18:00 with summary ‘awesome event’ (lasting for the default time of one hour) to the default calendar
khal new 25.10. 16:00 18:00 Another Event :: with Alice and Bob
adds a new event on 25th of October lasting from 16:00 to 18:00 with an additional description
khal new -a work 26.07. Great Event -r weekly
adds a new all day event on 26th of July to the calendar work which recurs every week.
prints a list of all configured calendars.
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 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.