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