CALCURSE(1)CALCURSE(1)NAMEcalcurse - text-based organizer
SYNOPSIScalcurse-Q [options] [--from <date>] [--to <date>|--days <num>]
calcurse-G [options]
calcurse -i<file>
calcurse -x<format>
calcurse--gc
calcurse--status
calcurse--version
calcurse--help
DESCRIPTION
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.
OPTIONS
The following options are supported:
-a, --appointment
Print the appointments and events for the current day and exit.
Equivalent to -Q --filter-type cal. Note: 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
~/.calcurse/apts (see section FILES below). This option has
precedence over -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.
--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. If not specified, the default
directory is ~/.calcurse/.
--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 FILTERS for details.
--filter-uncompleted
Only include uncompleted TODO items. See FILTERS for details.
--format-apt <format>
Specify a format to control the output of appointments in
non-interactive mode. See the FORMAT STRINGS section for detailed
information on format strings.
--format-recur-apt <format>
Specify a format to control the output of recurrent appointments in
non-interactive mode. See the FORMAT STRINGS section for detailed
information on format strings.
--format-event <format>
Specify a format to control the output of events in non-interactive
mode. See the FORMAT STRINGS section for detailed information on
format strings.
--format-recur-event <format>
Specify a format to control the output of recurrent events in
non-interactive mode. See the FORMAT STRINGS section for detailed
information on format strings.
--format-todo <format>
Specify a format to control the output of todo items in
non-interactive mode. See the FORMAT STRINGS section for detailed
information on format strings.
--from <date>
Specify the start date of the range when used with -Q.
-g, --gc
Run the garbage collector for note files and exit.
-G, --grep
Print appointments and TODO items using the calcurse data file
format. The filter interface can be used to further restrict the
output. See also: FILTERS.
-h, --help
Print a short help text describing the supported command-line
options, and exit.
-i <file>, --import <file>
Import the icalendar data contained in file.
-l <num>, --limit <num>
Limit the number of results printed to num.
-n, --next
Print the next appointment within upcoming 24 hours and exit. The
indicated time is the number of hours and minutes left before this
appointment.
Note: the calendar from which to read the appointments can be
specified using the -c flag.
-Q, --query
Print all appointments inside a given query range, followed by all
TODO items. The query range defaults to the current day and can be
changed by using the --from and --to (or --days) parameters. The
filter interface can be used to further restrict the output. See
also: FILTERS.
-r[num], --range[=num]
Print events and appointments for the num number of days and exit.
If no num is given, a range of 1 day is considered. Equivalent to
-Q --filter-type cal --days <num>.
--read-only
Don’t save configuration nor appointments/todos.
Warning: Use this this with care! If you run an interactive
calcurse instance in read-only mode, all changes from this session
will be lost without warning!
-s[date], --startday[=date]
Print events and appointments from date and exit. If no date is
given, the current day is considered. Equivalent to -Q
--filter-type cal --from <date>.
-S<regex>, --search=<regex>
When used with the -a, -d, -r, -s, or -t flag, print only the items
having a description that matches the given regular expression.
Equivalent to -Q --filter-pattern <regex>.
--status
Display the status of running instances of calcurse. If calcurse is
running, this will tell if the interactive mode was launched or if
calcurse is running in background. The process pid will also be
indicated.
-t[num], --todo[=num]
Print the todo list and exit. If the optional number num is given,
then only todos having a priority equal to num will be returned.
The priority number must be between 1 (highest) and 9 (lowest). It
is also possible to specify 0 for the priority, in which case only
completed tasks will be shown. Equivalent to -Q --filter-type todo,
combined with --filter-priority and --filter-completed or
--filter-uncompleted.
--to <date>
Specify the end date of the range when used with -Q. Cannot be
combined with --days.
-v, --version
Display calcurse version and exit.
-x[format], --export[=format]
Export user data to specified format. Events, appointments and
todos are converted and echoed to stdout. Two possible formats are
available: ical and pcal. If the optional argument format is not
given, ical format is selected by default.
Note: redirect standard output to export data to a file, by issuing
a command such as:
$ calcurse--export > my_data.dat
Note: The -N option has been removed in calcurse 3.0.0. See the FORMAT
STRINGS section on how to print note along with appointments and
events.
FILTERS
Filters can be used to restrict the set of items which are loaded from
the appointments file when using calcurse in non-interactive mode. The
following filters are currently supported:
--filter-type <type>
Ignore any items that do not match the type mask. The type mask is
a comma-separated list of valid type descriptions which include
event, apt, recur-event, recur-apt and todo. You can also use recur
as a shorthand for recur-event,recur-apt and cal as a shorthand for
event,apt,recur.
--filter-pattern <pattern>
Ignore any items with a description that does not match the
pattern. The pattern is interpreted as extended regular expression.
--filter-start-from <date>
Ignore any items that start before a given date.
--filter-start-to <date>
Ignore any items that start after a given date.
--filter-start-after <date>
Only include items that start after a given date.
--filter-start-before <date>
Only include items that start before a given date.
--filter-start-range <range>
Only include items with a start date that falls within a given
range. A range consists of a start date and an end date, separated
by a comma.
--filter-end-from <date>
Ignore any items that end before a given date.
--filter-end-to <date>
Ignore any items that end after a given date.
--filter-end-after <date>
Only include items that end after a given date.
--filter-end-before <date>
Only include items that end before a given date.
--filter-end-range <range>
Only include items with an end date that falls within a given
range. A range consists of a start date and an end date, separated
by a comma.
--filter-priority <priority>
Only include items with a given priority.
--filter-completed
Only include completed TODO items.
--filter-uncompleted
Only include uncompleted TODO items.
FORMAT STRINGS
Format strings are composed of printf()-style format specifiers —
ordinary characters are copied to stdout without modification. Each
specifier is introduced by a % and is followed by a character which
specifies the field to print. The set of available fields depends on
the item type.
Format specifiers for appointments
s
Print the start time of the appointment as UNIX time stamp
S
Print the start time of the appointment using the hh:mm format
d
Print the duration of the appointment in seconds
e
Print the end time of the appointment as UNIX time stamp
E
Print the end time of the appointment using the hh:mm format
m
Print the description of the item
n
Print the name of the note file belonging to the item
N
Print the note belonging to the item
Format specifiers for events
m
Print the description of the item
n
Print the name of the note file belonging to the item
N
Print the note belonging to the item
Format specifiers for todo items
p
Print the priority of the item
m
Print the description of the item
n
Print the name of the note file belonging to the item
N
Print the note belonging to the item
Examples
calcurse-r7 --format-apt='- %S -> %E\n\t%m\n%N'
Print appointments and events for the next seven days. Also, print
the notes attached to each regular appointment (simulates -N for
appointments).
calcurse-r7 --format-apt=' - %m (%S to %E)\n' --format-recur-apt=' -
%m (%S to %E)\n'
Print appointments and events for the next seven days and use a
custom format for (recurrent) appointments: * - Some appointment
(18:30 to 21:30)*.
calcurse-t --format-todo '(%p) %m\n'
List all todo items and put parenthesesaround the priority
specifiers.
Extended format specifiers
Extended format specifiers can be used if you want to specify advanced
formatting options. Extended specifiers are introduced by %( and are
terminated by a closing parenthesis ()). The following list includes
all short specifiers and corresponding long options:
· s: (start)
· S: (start:epoch)
· e: (end)
· E: (end:epoch)
· d: (duration)
· r: (remaining)
· m: (message)
· n: (noteid)
· N: (note)
· p: (priority)
The (start) and (end) specifiers support strftime()-style extended
formatting options that can be used for fine-grained formatting.
Additionally, the special formats epoch (which is equivalent to
(start:%s) or (end:%s)) and default (which is mostly equivalent to
(start:%H:%M) or (end:%H:%M) but displays ..:.. if the item doesn’t
start/end at the current day) are supported.
The (remaining) and (duration) specifiers support a subset of the
strftime()-style formatting options, along with two extra qualifiers.
The supported options are %d, %H, %M and %S, and by default each of
these is zero-padded to two decimal places. To avoid the zero-padding,
add - in front of the formatting option (for example, %-d).
Additionally, the E option will display the total number of time units
until the appointment, rather than showing the remaining number of time
units modulo the next larger time unit. For example, an appointment in
50 hours will show as 02:00 with the formatting string %H:%M, but will
show 50:00 with the formatting string %EH:%M. Note that if you are
combining the - and E options, the - must come first. The default
format for the (remaining) specifier is %EH:%M.
NOTES
Calcurse interface contains three different panels (calendar,
appointment list, and todo list) on which you can perform different
actions. All the possible actions, together with their associated
keystrokes, are listed on the status bar. This status bar takes place
at the bottom of the screen.
At any time, the built-in help system can be invoked by pressing the ?
key. Once viewing the help screens, informations on a specific command
can be accessed by pressing the keystroke corresponding to that
command.
CONFIGURATION
The calcurse options can be changed from the configuration menu (shown
when C is hit). Five possible categories are to be chosen from : the
color scheme, the layout (the location of the three panels on the
screen), notification options, key bindings configuration menu, and
more general options (such as automatic save before quitting). All of
these options are detailed in the configuration menu.
FILES
The following structure is created in your $HOME directory (or in the
directory you specified with the -D option), the first time calcurse is
run:
$HOME/.calcurse/
|___notes/
|___conf
|___keys
|___apts
|___todo
The notes subdirectory contains descriptions of 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 conf file contains the user configuration. The keys file contains
the user-defined key bindings. The apts file contains all of the user’s
appointments and events, and the todo file contains the todo list.
Note: if the logging of calcurse daemon activity was set in the
notification configuration menu, the extra file daemon.log will appear
in calcurse data directory. This file contains logs about calcurse
activity when running in background.
ENVIRONMENT
This section describes the environment variables that affect how
calcurse operates.
VISUAL
Specifies the external editor to use for writing notes.
EDITOR
If the VISUAL environment variable is not set, then EDITOR will be
used as the default external editor. If none of those variables are
set, then /usr/bin/vi is used instead.
PAGER
Specifies the default viewer to be used for reading notes. If this
variable is not set, then /usr/bin/less is used.
BUGS
Incorrect highlighting of items appear when using calcurse black and
white theme together with a $TERM variable set to xterm-color. To fix
this bug, and as advised by Thomas E. Dickey (xterm maintainer),
xterm-xfree86 should be used instead of xterm-color to set the $TERM
variable:
"The xterm-color value for $TERM is a bad choice for
XFree86 xterm because it is commonly used for a
terminfo entry which happens to not support bce.
Use the xterm-xfree86 entry which is distributed
with XFree86 xterm (or the similar one distributed
with ncurses)."
If you find other bugs, please send a report to bugs@calcurse.org or to
one of the authors, below.
SEE ALSOvi(1), less(1), ncurses(3), mkstemp(3)
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 complete manual, translated in many languages and maintained
in html format, can be found in the doc/ directory of the source
package, or at: http://calcurse.org/files/manual.html
AUTHORS
· Frederic Culot <frederic@culot.org>
· Lukas Fleischer <calcurse@cryptocrack.de>
COPYRIGHT
Copyright (c) 2004-2015 calcurse Development Team. This software is
released under the BSD License.
02/22/2015 CALCURSE(1)
