calcurse - terminal-based organizer for interactive and command line use
calcurse [-D datadir] [-C confdir] [-c calendar-file]
calcurse -Q [--from date] [--to date | --days number]
calcurse -a | -d date | -d number | -n | -r[number] | -s[date] | -t[number]
calcurse -G [filter options] [format options] | -P [filter options] [format options]
calcurse -h | --status | -g | -i file | -x[file] | --daemon
The first form shows how to invoke calcurse interactively; the remainder is command line forms.
The second form shows queries (as opposed to interactive use). For convenience, common queries have abbreviated forms shown in the third line. All queries may be combined with filter options as well as format options.
The fourth form shows operations on the calcurse data files, one for display of entries, the other for removal of them.
The fifth form is miscellaneous help and support functions.
All details are in OPTIONS.
calcurse is a calendar and scheduling application for use in a terminal session (terminal emulator). When invoked without options, calcurse enters interactive mode; in most other cases, calcurse produces output on the terminal and exits. It helps keeping track of events, appointments and everyday tasks. Interactive mode is used when data are entered or when already existing entries are inspected or edited. All data are saved to disk as text files. Command line mode is used for queries and administrative tasks and for automating tasks in scripts.
The interactive interface is based on ncurses and can be customized to suit user preferences. Customization includes program behaviour as well as visual appearance and key bindings, and is performed interactively; the result is automatically saved to disk and loaded on every invocation. Available actions are documented in an online help system. A configurable notification system issues reminders of upcoming deadlines.
When leaving the interactive program, a background daemon may continue running and issue reminders; it stops automatically when the interactive mode is reentered.
This man page mainly describes the command-line mode. The following two subsections contain some general descriptions of command line options and usage.
Input and Output Date Format¶
Many options require a date argument, and query results per day are set apart by a leading date line.
The input format of date options and the output format of date lines are taken from the configuration file (see FILES). The formats are set in the "General Options" submenu in interactive mode. Particularly in scripts it may be desirable that formats are independent of the local user configuration. For this purpose use the options --input-datefmt and --output-datefmt.
An input date consists of date, month and year. Here day must be in the range 1-31 and month in 1-12. Depending on the operating system year must be in the range 1902-2037 or 1902-?. Additionally, some short forms are allowed with the obvious meaning: today, tomorrow, yesterday, now and weekdays mon, ..., sun.
Optionally, a date argument for a filter option (see Filter Options) may be followed by a time-of-day specification in hours and minutes (24-hour clock). The specification has the fixed format hh:mm (example: "2018-12-1 20:30" when the input date format is the ISO standard format). Note that the entire date specification must be quoted to create one argument.
Filter, format and day range options¶
These options do not accomplish anything in and of themselves. They influence other options and are in a way opposites: filter options affect the input to, format and day range options the output from calcurse. Specifically, filter options limit what is loaded from the data files into calcurse, day range options limit what is output (see -Q), and format options describe how it is presented.
Filter options have effect on queries (-Q and query short-forms), grep (-G), purge (-P) and export (-x). Format options have effect on queries, grep and --dump-imported. Day range options have effect on queries only.
Most options imply command line mode. Options compatible with interactive mode are marked "(also interactively)".
-c file, --calendar file
-C dir, --confdir dir
-D dir, --datadir dir
-d date|num, --day date|num
In the first case, appointments and events for date are returned, while in the second case those for num days are returned. Positive values of num means the future, negative the past; the range either starts or ends with the current day. As an example calcurse -d 3 displays appointments and events for today, tomorrow and the day after tomorrow, while calcurse -d -2 displays those for yesterday and today. The first form is equivalent to -Q --filter-type cal --from date, the second to -Q --filter-type cal --days num.
-i file, --import file
-l num, --limit num
The matching items are (silently) removed from the data files. Any combination of filter options, except --filter-invert, may be used in describing the items to be removed. The invert filter is used internally by the purge option, and its simultaneous use on the command line may result in unpredictable behaviour.
Warning: Be careful with this option, specifying the wrong filter options may result in data loss. It is highly recommended to test with -G first and fine-tune the filters to show the items to be removed. Then run the same command with -P instead of -G. In any case, make a backup of the data files in advance.
The day range defaults to the current day and is changed with the options --from and --to/--days. The range --from a --to z includes both a and z. The range --from a --days n, includes a as the first day, if n is positive, or last day, if n is negative.
Day range has an effect on queries only.
Warning: If you run calcurse interactively in read-only mode, all changes from that session will be lost without warning!
-S regex, --search regex
Filter options have effect on queries (-Q and query short-forms), grep (-G), purge (-P) and export (-x), see also options in the DESCRIPTION section.
Several filter options may be given. For an item to be loaded into calcurse it must match all filters. In other words, filters are logically "and"-ed. The --filter-type option has a default value which matches any item. All other filter options have no default value and only apply when explicitly set.
The filter options fall into three groups: general, calendar, todo. The general filters apply to all items, the calendar filters concern start and end times and apply to appointments and events only, and the todo filters concern priority and completeness and apply to TODOs only.
Outside the three groups is the invert filter.
For filter options ending in -from, -to, -after, -before and -range, start or end time is the filter criterion.
An event is an all-day appointment for which no times are displayed. The start time of an event is the beginning of the event day (midnight), the end time is the end of the event day (one second before next midnight).
The -start- options ending in -from, -after and -range refer to the same filter criterion and cannot be used together. The same is the case for options ending in -to, -before and -range. Similar restrictions apply to -end- options.
Start and end times of a recurrent item refer to the very first occurrence, not to those of any of the repetitions. If a recurrent item meets the criterion, all of the repetitions are displayed in queries, even though they may not meet the criterion. If they are unwanted, they may be removed from the output with the day range options, although this will also remove other items in that range.
Format options have effect on queries, grep and --dump-imported.
The options specify a format for appointments, recurring appointments, events, recurring events or todo items, respectively.
--format-apt format, --format-recur-apt format, --format-event format, --format-recur-event format, --format-todo format
Note: Use of a format option requires explicit formatting of field separation and line spacing.
Default format strings¶
Each specifier is introduced by a % followed by a character which tells what to print. The available specifiers depend on the item type. Times are printed as hours and minutes (hh:mm) unless otherwise noted; time formats can be changed with extended specifiers.
For each format option there is a default format string which is used when the option is not given. In query results the default format options are:
--format-apt " - %S -> %E\n\t%m\n" --format-recur-apt " - %S -> %E\n\t%m\n" --format-event " * %m\n" --format-recur-event " * %m\n" --format-todo "%p. %m\n"
In all other cases (grep and dump-imported) the default format string is "%(raw)".
Extended format specifiers¶
Extended format specifiers can be used to control the printing of times for some of the single-letter specifiers. Additionally there are two specifiers that do not have any corresponding short form and are intended for use in scripting.
format may contain any of the strftime(3) specifiers %d, %H, %M or %S with the following modifications: 1) days are not limited to the "calendar" values 0-31 (hours, minutes and seconds are "clock" values, but see E in the following) 2) each number is by default padded with zeros to two decimal places, 3) the % character may be followed by one or two optional flags: -, which suppresses the zero-padding, E, which will suppress the "clock" limits on %H, %M and %S; if both are used, - must precede E, 4) no other flags or width specifications are supported
format may be any strftime(3) format specifier or one of the strings epoch or default; the former is equivalent to the (calcurse) specifiers %s and %e (seconds since the Epoch); the latter is equivalent to the (calcurse) specifiers %S and %E or the (strftime) format string %H:%M, except that the continuation marker ..:.. is printed if the start/end time belongs to another day
calcurse -d tomorrow
calcurse -d friday
calcurse -d 7
calcurse -r7 --format-apt " - %S -> %E\n\t%m\n%N"
calcurse -r7 --format-apt " - %m (%S to %E)\n" --format-recur-apt " - %m (%S to %E)\n"
- Some appointment (18:30 to 21:30)
calcurse -t --format-todo "(%p) %m\n"
If the calcurse data files contain many entries which are no longer needed or wanted, they can, of course, be removed interactively. If there are many, it can be a tedious task and may be done better as in the following two examples.
calcurse --input-datefmt 4 -G --filter-start-before 2015-1-1
Purge. When -G is replaced by -P, those entries are removed. This may remove recurring items that have occurrences after 1 January 2015.
calcurse --input-datefmt 1 -G --filter-start-from 11/1/2015 --filter-type event,apt
calcurse -G --filter-type apt --format-apt "%(hash) %m\n"
calcurse -G --filter-type apt --format-apt "%(duration:%d/%EH/%EM)\t%m\n"
calcurse -G --filter-type apt --format-apt "%(start:%c) %(duration:%d %H:%M)\t%m\n"
The following structure is created by default in your home directory the first time calcurse is run without any options:
$XDG_DATA_HOME defaults to $HOME/.local/share and $XDG_CONFIG_HOME defaults to $HOME/.config.
The files are of two different kinds: data and configuration. The data files constitute the calcurse database and are independent of the calcurse release version; the configuration files depend on the calcurse version although backwards compatibility is always aimed at.
The calendar file apts contains all of the user’s appointments and events, and the todo file contains the todo list. The notes subdirectory contains the notes which are attached to appointments, events or todos. One text file is created per note, whose name is the SHA1 message digest of the note itself.
The (hidden) lock files of the calcurse (.calcurse.pid) and daemon (.daemon.log) programs are present when they are running. If daemon log activity has been enabled in the notification configuration menu, the file daemon.log is present.
An alternative calendar file may be specified with the -c option.
The conf file contains the user configuration and the keys file the user-defined key bindings. The hooks directory contains user-supplied scripts, see Hooks.
An alternative directory for both the configuration files and the data directory may be specified with the -D option.
An alternative directory for the configuration files only may be specified with the -C option; in that case data files are either in the default directory or in the directory specified by -D. If both -D and -C are present, configuration files in the data directory, if any, are ignored.
If $HOME/.calcurse exists, then it will be used as the default for both the data directory and the configuration directory.
|__ apts |___ conf
|__ todo |___ keys
|__ notes/ |___ hooks/ defaults:
<datadir>: $XDG_DATA_HOME/calcurse ($HOME/.local/share/calcurse)
<confdir>: $XDG_CONFIG_HOME/calcurse ($HOME/.config/calcurse)
both: $HOME/.calcurse (only if it exists)
calcurse may switch between two configuration setups, but still access the same data files e.g. with:
$ calcurse $ calcurse -C "$HOME/.config/calcurse/config"
Scripts placed in <confdir>/calcurse/hooks/ (see Directory configuration) trigger actions at certain events. To enable a hook, add a script with one of the following names to this directory. Also make sure the script is executable.
Some examples can be found in the contrib/hooks/ directory of the calcurse source tree.
A few environment variables affect how calcurse operates.
CALCURSE_EDITOR, VISUAL, EDITOR
See also FILES.
If you find a bug, please send a report to firstname.lastname@example.org, or, if you are a Github user, raise an issue at https://github.com/lfos/calcurse.
The ical specification (rfc2445) can be found at: http://tools.ietf.org/html/rfc2445
The pcal project page: http://pcal.sourceforge.net/
calcurse home page: http://calcurse.org/
calcurse at GitHub: https://github.com/lfos/calcurse
The complete manual, maintained in html format, can be found in the doc/ directory of the source package, or at: http://calcurse.org/files/manual.html
Copyright (c) 2004-2020 calcurse Development Team. This software is released under the BSD License.