Usage
*****

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.


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, --verbosity LVL

   Configure verbosity (e.g. print debugging information), *LVL* needs
   to be one of CRITICAL, ERROR, WARNING, INFO, or DEBUG.

-l, --logfile LOFILE

   Use logfile *LOGFILE* for logging, default is logging to stdout.

-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

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

--format FORMAT

   For all of khal's commands that print events, the formatting of
   that event can be specified with this option.  "FORMAT" is a
   template string, in which identifiers delimited by curly braces
   (*{}*) will be expanded to an event's properties.  "FORMAT"
   supports all formatting options offered by python's str.format()
   (as it is 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 will
      show 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 then it returns
      "CN (email)" if CN does not exist it returns just the email
      string. Example: 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. To see a start and end
   time anyway simply 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).

   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}"

--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 are 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 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).


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

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.


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

**Some examples**

Including or excluding specific calendars:

* *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:

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

   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.


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

**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") 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.

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


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.


search
------

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