CALCURSE - text-based organizer

1. Abstract

This manual describes calcurse functionalities, and how to use them. The installation from source is first described, together with the available command line arguments. The user interface is then presented, with all of the customizable options that change calcurse behavior. Last, bug reporting procedure is explained, as well as the way one can contribute to calcurse development.

2. Introduction

calcurse is a text-based calendar and scheduling application. It helps keeping track of events, appointments and everyday tasks. A configurable notification system reminds user of upcoming deadlines, and the curses based interface can be customized to suit user needs. All of the commands are documented within an online help system.

3. Overview

3.1. Creation history

Frederic started thinking about this project when he was finishing his Ph.D. in Astrophysics as it started to be a little hard to organize himself and he really needed a good tool for managing his appointments and todo list. Unfortunately, he finished his Ph.D. before finishing calcurse but he continued working on it, hoping it would be helpful to other people.

In mid-2010, Lukas took over development of calcurse and is now the main contributor and reviewer of patches.

But why calcurse anyway? Well, it is simply the concatenation of *cal*endar and *curse*s, the name of the library used to build the user interface.

3.2. Important features

Calcurse is multi-platform and intended to be lightweight, fast and reliable. It is to be used inside a console or terminal, locally or on a distant machine within an ssh (or similar) connection.

Calcurse can be run in two different modes : interactive or non-interactive mode. The first mode allows oneself to view its own personal organizer almost everywhere, thanks to the text-based interface. The second mode permits to easily build reminders just by adding calcurse with appropriate command line arguments inside a cron tab or within a shell init script.

Moreover, calcurse was created with the end-user in mind, and tends to be as friendly as possible. This means a complete on-line help system, together with having all of the possible actions displayed at any time inside a status bar. The user interface is configurable, and one can choose between several color and layout combinations. Key bindings are also configurable, to fit everyone’s needs. Last, a configurable notification system reminds user of upcoming appointments. The reminders are sent even if the user’s interface is not running, as calcurse is able to run in background.

4. Installation

4.1. Requirements

4.1.1. ncurses library

Calcurse requires only a C compiler, such as cc or gcc, and the ncurses library. It would be very surprising not to have a valid ncurses library already installed on your computer, but if not, you can find it at the following url: http://ftp.gnu.org/pub/gnu/ncurses/

It is also possible to link calcurse against the ncursesw library (ncurses with support for unicode).

4.1.2. gettext library

calcurse supports internationalization (i18n hereafter) through the gettext utilities. This means calcurse can produce multi-lingual messages if compiled with native language support (i.e. NLS).

However, NLS is optionnal and if you do not want to have support for multi-lingual messages, you can disable this feature. This is done by giving the --disable-nls option to configure (see section Install process). To check if the gettext utilities are installed on your system, you can search for the libintl.h header file for instance:

$ locate libintl.h

If this header file is not found, then you can obtain the gettext sources at the following url : http://ftp.gnu.org/pub/gnu/gettext/

Even if libintl.h is found on your system, it can be wise to specify its location during the install process, by using the --with-libintl-prefix option with configure. Indeed, the configure could fail to locate this library if installed in an uncommon place.

4.2. Install process

First you need to gunzip and untar the source archive:

$ tar zxvf calcurse-4.6.0.tar.gz

Once you meet the requirements and have extracted the archive, the install process is quite simple, and follows the standard three steps process:

$ ./configure
$ make
$ make install    # (may require root privilege)

Use ./configure --help to obtain a list of possible options.

5. calcurse basics

5.1. Invocation

5.1.1. Command line arguments

calcurse takes the following options from the command line (both short and long options are supported):

-a, --appointment

Print the appointments and events for the current day and exit. Equivalent to -Q --filter-type cal. The calendar from which to read the appointments can be specified using the -c flag.

-c <file>, --calendar <file>

Specify the calendar file to use. The default calendar is located at <datadir>/apts (see section calcurse files). This option has precedence over -D.

-C <dir>, --directory <dir>

Specify the configuration directory to use. See calcurse files for the default directory and for the interaction with -D.

-d <date|num>, --day <date|num>

Print the appointments for the given date or for the given number of upcoming days, depending on the argument format. Two possible formats are supported:

a date (possible formats described below).
a number n.

In the first case, the appointment list for the specified date will be returned, while in the second case the appointment list for the n upcoming days will be returned. As an example, typing calcurse -d 3 will display your appointments for today, tomorrow, and the day after tomorrow. The first form is equivalent to -Q --filter-type cal --from <date>, the second form is equivalent to -Q --filter-type cal --days <num>.

Note: as for the -a flag, the calendar from which to read the appointments can be specified using the -c flag.

--daemon

Start calcurse in background mode. Restart if the daemon was already running. See Background mode for details.

--days <num>

Specify the length of the range (in days) when used with -Q. Cannot be combined with --to.

-D <dir>, --directory <dir>

Specify the (data) directory to use. See calcurse files for the default directory and for the interaction with -C.

--filter-type <type>

Ignore any items that do not match the type mask. See Filters for details.

--filter-pattern <pattern>

Ignore any items with a description that does not match the pattern. See Filters for details.

--filter-start-from <date>

Ignore any items that start before a given date. See Filters for details.

--filter-start-to <date>

Ignore any items that start after a given date. See Filters for details.

--filter-start-after <date>

Only include items that start after a given date. See Filters for details.

--filter-start-before <date>

Only include items that start before a given date. See Filters for details.

--filter-start-range <range>

Only include items within a given range. See Filters for details.

--filter-end-from <date>

Ignore any items that end before a given date. See Filters for details.

--filter-end-to <date>

Ignore any items that end after a given date. See Filters for details.

--filter-end-after <date>

Only include items that end after a given date. See Filters for details.

--filter-end-before <date>

Only include items that end before a given date. See Filters for details.

--filter-end-range <range>

Only include items within a given range. See Filters for details.

--filter-priority <priority>

Only include items with a given priority. See Filters for details.

--filter-completed

Only include completed TODO items. See