Repo Review: Calcurse

by David Pardue (kalwisti)

Calcurse is a text-based calendar and scheduling application for the command line. It helps keep track of events, appointments and daily tasks. It has lots of functionality, is lightweight, fast, reliable and portable (due to being text-file based). The PCLinuxOS repositories have ver. 4.6.0 (released in March 2020).

Calcurse's name is a combination of 'calendar' and 'curses' (the name of the library used to build the user interface). Calcurse is multi-platform. It is available on Linux, three BSD distributions and macOS (via the Homebrew project).

The original author of calcurse is Frédéric Coulot, a programmer and astrophysicist who developed the application in his spare time and first distributed it in 2004. Since 2011, the project has been maintained by Lukas Fleischer (Germany), a computer scientist and software engineer. Many of calcurse's core features since 2017 were designed and implemented by Lars Henriksen (Denmark).

Calcurse has support for internationalization (UTF-8) and has been fully translated into six languages besides English: French, Spanish, Portuguese (Brazilian), German, Dutch and Russian.

You run calcurse by typing calcurse from the Terminal. The screenshot below shows its default layout.

Calcurse divides the screen into three panels: Appointments, Calendar and ToDo. At the bottom of the screen, there is a Notification bar and a Status bar (sometimes referred to as a Menu panel). You cycle through the panels using the Tab key.

Looking at the Status bar, Vim users might notice that calcurse's basic "motion" keys – Left, Down, Up, Right – are identical to Vim's (i.e., h, j, k, l). People who have worked with the Nano text editor will find the layout of calcurse's Status bar familiar.

Calcurse has a minimal learning curve. If you can spare thirty minutes to watch the tutorials listed in the "Additional Resources" section, you can learn the program's basics.

How to Make a Repeating Event

This stumped me until I found an explanation in the program's Help file (which you access by typing " : [colon] help <feature name> ", e.g., " : help repeat " in the Status bar / Menu panel). This is not covered in the video tutorials below, so I hope it will save you some frustration.

• Create your appointment (birthday or bill reminder) in the Appointments panel, as usual.


• Stay inside the Appointments panel and select the item to be repeated.


• Press " r " for 'repeat.'


• Repetition Type: Choose between daily, weekly, monthly or yearly repetition by pressing d, w, m or y.




• Repetition Frequency: Indicates how often the item will be repeated.


• For a birthday, anniversary, etc. press "1" which means it will be repeated every year.


• Other examples: If you go to dine at a restaurant every two days, choose daily repetition ("d") with a frequency of "2".


• For a quarterly bill, choose monthly repetition ("m") with a frequency of "3".

When I first began using calcurse, I could not set appointments/events to repeat because I mistakenly tried to enter the repetition type (e.g., m or y) again, instead of the numerical value (e.g., 1) that calcurse expects. If you enter a letter here, calcurse generates an "Invalid frequency" error message:

• End Date: Specifies when to stop repeating the selected event or appointment.


• To indicate endless repetition, press "0" and the item will be repeated forever.

Repeating items are marked with an "*" [asterisk] inside the Appointments panel to distinguish them from non-repeated items.

How to Delete One Occurrence of a Repeating Event

This is helpful if you use calcurse as a "bill minder" like I do. Once I pay a monthly bill, I delete it from the Appointments panel so that only pending/unpaid bills are listed there.

• From inside the Appointments panel, select the (single) item to be deleted. In this example, I will delete my monthly electricity bill for March 2023.

• Press " d " for 'delete' item.


• Do you really want to delete this item? Answer "y".

• This item is recurrent. Delete all or just one? Type " o " (for 'one').

• The item will disappear.


• To confirm that calcurse deleted only the March bill, I went to the calendar for April 1st and looked at the Appointments panel. "Electricity (Reliant)" is still there for the upcoming month:

If you look in ~/.local/share/calcurse and look at the "apts" file, you can see that the single day (Mar. 1, 2023) of the deleted occurrence has been added to the "recipe" as an exception day on which this item is not displayed.

If you want to completely remove the entry from the data file, select the option "Delete all occurrences."

Usage in Non-interactive Mode

Calcurse's "non-interactive" mode refers to its use on the command line (rather than its three-panel ncurses interface). The non-interactive mode is mainly used for searching; you invoke calcurse with the appropriate options/flags, the application searches its database, outputs the requested data and then returns you to the Terminal prompt.

Here are a few examples:

$ calcurse -a
      This will show all your appointments for today.

$ calcurse -t
      This will show your to-do list for today.

$ calcurse -d 3       ( or, $ calcurse -r3 )
      This will show your appointments for the next three days.

Other Features

Calcurse has other features which I did not experiment with. Calcurse can import calendars in iCalendar format (.ics) and export your data in either iCalendar or PCAL format. (PCAL allows you to generate a printable PostScript version of your calendar).

If you need to synchronize calcurse with your mobile devices, with Google Calendar or Apple Calendar, there is experimental CalDAV support via a script called calcurse-caldav. In order to configure this, you must be running the most recent version of calcurse (4.8.0, released in April 2022) and follow the detailed documentation here. (Users are cautioned that the script is alpha software and might still have bugs).

Many of calcurse's settings can be configured from the Configuration menu (accessed by pressing "C" in the Status bar). For example, once you are in the interactive configure mode, you can select "l" (for "Layout") and choose between eight different panel layouts. Pressing "c" (for "Color") allows you to select different color schemes. All of the program's key bindings are user-definable, by pressing "k" (for "Keys").

Additional Resources

The most succinct YouTube video tutorials I found were created by Brian Schell, Brodie Robertson and Derek Taylor from Distrotube:

Schell, Brian. "Scheduling in the Terminal with Calcurse for Appointments and Todos." YouTube, 23 Mar. 2019. (15 min., 26 sec.)

Robertson, Brodie. "I Wanted a Calendar and Calcurse Is Exactly What I Need!" YouTube, 24 Mar. 2020. (13 min., 37 sec.)

Taylor, Derek. "Calcurse: Organizer and Scheduling App." YouTube, 22 Oct. 2017. (8 min., 44 sec.)

The program's manual is available in HTML or as a PDF file.

Summary

Calcurse is fast, reliable and incorporates many features into a small package. It does not require a steep learning curve; if you have previously worked with Vim or Nano, you should feel right at home with Calcurse's status bar (aka Menu panel). After using calcurse for two weeks, I have found it as convenient as Google Calendar.

If you would like to lessen your dependence on Google Calendar, efficiently manage your schedule and task list while working in a TUI (Text User Interface) environment, calcurse is an excellent option. I encourage you to try it.