1CALCURSE(1)                                                        CALCURSE(1)
2
3
4

NAME

6       calcurse - terminal-based organizer for interactive and command line
7       use
8

SYNOPSIS

10       calcurse [-D datadir] [-C confdir] [-c calendar-file]
11
12       calcurse -Q [--from date] [--to date | --days number]
13
14       calcurse -a | -d date | -d number | -n | -r[number] | -s[date] |
15       -t[number]
16
17       calcurse -G [filter options] [format options] | -P [filter options]
18       [format options]
19
20       calcurse -h | --status | -g | -i file | -x[file] | --daemon
21
22       The first form shows how to invoke calcurse interactively; the
23       remainder is command line forms.
24
25       The second form shows queries (as opposed to interactive use). For
26       convenience, common queries have abbreviated forms shown in the third
27       line. All queries may be combined with filter options as well as format
28       options.
29
30       The fourth form shows operations on the calcurse data files, one for
31       display of entries, the other for removal of them.
32
33       The fifth form is miscellaneous help and support functions.
34
35       All details are in OPTIONS.
36

DESCRIPTION

38       calcurse is a calendar and scheduling application for use in a terminal
39       session (terminal emulator). When invoked without options, calcurse
40       enters interactive mode; in most other cases, calcurse produces output
41       on the terminal and exits. It helps keeping track of events,
42       appointments and everyday tasks. Interactive mode is used when data are
43       entered or when already existing entries are inspected or edited. All
44       data are saved to disk as text files. Command line mode is used for
45       queries and administrative tasks and for automating tasks in scripts.
46
47       The interactive interface is based on ncurses and can be customized to
48       suit user preferences. Customization includes program behaviour as well
49       as visual appearance and key bindings, and is performed interactively;
50       the result is automatically saved to disk and loaded on every
51       invocation. Available actions are documented in an online help system.
52       A configurable notification system issues reminders of upcoming
53       deadlines.
54
55       When leaving the interactive program, a background daemon may continue
56       running and issue reminders; it stops automatically when the
57       interactive mode is reentered.
58
59       This man page mainly describes the command-line mode. The following two
60       subsections contain some general descriptions of command line options
61       and usage.
62
63   Input and Output Date Format
64       Many options require a date argument, and query results per day are set
65       apart by a leading date line.
66
67       The input format of date options and the output format of date lines
68       are taken from the configuration file (see FILES). The formats are set
69       in the "General Options" submenu in interactive mode. Particularly in
70       scripts it may be desirable that formats are independent of the local
71       user configuration. For this purpose use the options --input-datefmt
72       and --output-datefmt.
73
74       An input date consists of date, month and year. Here day must be in the
75       range 1-31 and month in 1-12. Depending on the operating system year
76       must be in the range 1902-2037 or 1902-?. Additionally, some short
77       forms are allowed with the obvious meaning: today, tomorrow, yesterday,
78       now and weekdays mon, ..., sun.
79
80       Optionally, a date argument for a filter option (see Filter Options)
81       may be followed by a time-of-day specification in hours and minutes
82       (24-hour clock). The specification has the fixed format hh:mm (example:
83       "2018-12-1 20:30" when the input date format is the ISO standard
84       format). Note that the entire date specification must be quoted to
85       create one argument.
86
87   Filter, format and day range options
88       These options do not accomplish anything in and of themselves. They
89       influence other options and are in a way opposites: filter options
90       affect the input to, format and day range options the output from
91       calcurse. Specifically, filter options limit what is loaded from the
92       data files into calcurse, day range options limit what is output (see
93       -Q), and format options describe how it is presented.
94
95       Filter options have effect on queries (-Q and query short-forms), grep
96       (-G), purge (-P) and export (-x). Format options have effect on
97       queries, grep and --dump-imported. Day range options have effect on
98       queries only.
99

OPTIONS

101       Most options imply command line mode. Options compatible with
102       interactive mode are marked "(also interactively)".
103
104       -a, --appointment
105           Print the appointments and events for the current day. Equivalent
106           to -Q --filter-type cal.
107
108       -c file, --calendar file
109           (also interactively) Specify the calendar file to use. The default
110           calendar is located at <datadir>/apts (see FILES). If file is not
111           an absolute path name, it is interpreted relative to the current
112           working directory. The option has precedence over -D.
113
114       -C dir, --confdir dir
115           (also interactively) Specify the configuration directory to use.
116           See section FILES for the default directory and the interaction
117           with -D.
118
119       -D dir, --datadir dir
120           (also interactively) Specify the (data) directory to use. See
121           section FILES for the default directory and the interaction with
122           -C.
123
124       -d date|num, --day date|num
125           Print appointments and events for the given date or given range of
126           days, depending on the argument format:
127
128           •   a date
129
130           •   a number num
131
132           In the first case, appointments and events for date are returned,
133           while in the second case those for num days are returned. Positive
134           values of num means the future, negative the past; the range either
135           starts or ends with the current day. As an example calcurse -d 3
136           displays appointments and events for today, tomorrow and the day
137           after tomorrow, while calcurse -d -2 displays those for yesterday
138           and today. The first form is equivalent to -Q --filter-type cal
139           --from date, the second to -Q --filter-type cal --days num.
140
141       --daemon
142           Start calcurse in background mode; restart, if the daemon was
143           already running. Usually done automatically by setting the
144           configuration option daemon.enable in the Notify submenu in
145           interactive mode.
146
147       --days num
148           Specify the range of days when used with -Q. Can be combined with
149           --from, but not with --to. Without --from, the first day of the
150           range defaults to the current day. The number may be negative, see
151           -Q --query.
152
153       --dump-imported
154           When importing items, print each newly created object to stdout.
155           Format options can be used to specify which details are printed.
156           See also Format Options.
157
158       --export-uid
159           When exporting items, add the hash of each item to the exported
160           object as a UID property.
161
162       --from date
163           Specify the start date of the day range when used with -Q. When
164           used without -to or --days the range is one day (the specified
165           day), see -Q --query.
166
167       -F, --filter
168           Deprecated, see -P. Note that this option is for backward
169           compatibility and not the same as -P (it does not use the invert
170           filter option).
171
172       -g, --gc
173           Run the garbage collector for note files. The garbage collector
174           removes files from the notes directory (see FILES) that are no
175           longer linked to an item. Usually done automatically by setting the
176           configuration option general.autogc in the General Options submenu
177           in interactive mode.
178
179       -G, --grep
180           Print appointments, events and TODO items in calcurse data file
181           format.
182
183       -h, --help
184           Print a short help text describing the supported command-line
185           options.
186
187       -i file, --import file
188           Import the icalendar data contained in file.
189
190       --input-datefmt format
191           For command line and script use only: override the configuration
192           file setting of the option format.inputdate (General Options
193           submenu in interactive mode). A valid format is any of 1, 2, 3, or
194           4, with 1 = mm/dd/yyyy, 2 = dd/mm/yyyy, 3 = yyyy/mm/dd, 4 =
195           yyyy-mm-dd.
196
197       -l num, --limit num
198           Limit the number of results printed to num.
199
200       -n, --next
201           Print the first appointment within the next 24 hours. The printed
202           time is the number of hours and minutes left before this
203           appointment.
204
205       --output-datefmt format
206           For command line and script use only: override the configuration
207           file setting of the option format.outputdate (General Options
208           submenu in interactive mode). A valid format is any strftime(3)
209           format string.
210
211       -P, --purge
212           Load items from the data files and save them back; the items are
213           described by suitable filter options (see Filter Options). It may
214           be used to drop specific items from the data files, see EXAMPLES.
215
216           The matching items are (silently) removed from the data files. Any
217           combination of filter options, except --filter-invert, may be used
218           in describing the items to be removed. The invert filter is used
219           internally by the purge option, and its simultaneous use on the
220           command line may result in unpredictable behaviour.
221
222           Warning: Be careful with this option, specifying the wrong filter
223           options may result in data loss. It is highly recommended to test
224           with -G first and fine-tune the filters to show the items to be
225           removed. Then run the same command with -P instead of -G. In any
226           case, make a backup of the data files in advance.
227
228       -q, --quiet
229           (also interactively) Be quiet. Do not show system dialogs.
230
231       -Q, --query
232           Print all appointments and events in a given range of days followed
233           by all TODO items. The calendar part is displayed per day with a
234           leading line containing the date and a trailing empty line (much
235           like the calendar panel in interactive mode).
236
237           The day range defaults to the current day and is changed with the
238           options --from and --to/--days. The range --from a --to z includes
239           both a and z. The range --from a --days n, includes a as the first
240           day, if n is positive, or last day, if n is negative.
241
242           Day range has an effect on queries only.
243
244       -r[num], --range[=num]
245           Print appointments and events for num number of days starting with
246           the current day. If num is left out, a range of 1 day is used. The
247           number may be negative in which case the range is in the past,
248           ending with the current day. Equivalent to -Q --filter-type cal
249           --days num.
250
251       --read-only
252           (also interactively) Do not save configuration nor appointments and
253           todos.
254
255           Warning: If you run calcurse interactively in read-only mode, all
256           changes from that session will be lost without warning!
257
258       -s[date], --startday[=date]
259           Print events and appointments from the optional date; default is
260           the current day. Equivalent to -Q --filter-type cal --from date.
261
262       -S regex, --search regex
263           When used with any of -a, -d, -r, -s, or -t print only the items
264           having a description that matches the given regular expression.
265           Equivalent to -Q --filter-pattern regex.
266
267       --status
268           Display the status of running instances of calcurse, interactive or
269           background mode. The process pid is also printed.
270
271       -t[num], --todo[=num]
272           Print the todo list. If the optional number num is given, then only
273           uncompleted (open) todos having a priority equal to num will be
274           returned. The priority number must be between 1 (highest) and 9
275           (lowest). It is also possible to specify 0 for the priority, in
276           which case only completed (closed) tasks will be shown. Equivalent
277           to -Q --filter-type todo, combined with --filter-priority and
278           --filter-completed or --filter-uncompleted.
279
280       --to date
281           Specify the end date of the day range when used with -Q. When used
282           without --from the start day is the current day. Cannot be combined
283           with --days, see -Q --query.
284
285       -v, --version
286           Display calcurse version.
287
288       -x[format], --export[=format]
289           Export user data in the specified format. Events, appointments and
290           todos are converted and echoed to stdout. Two formats are
291           available: ical and pcal. The default format is ical.
292

FILTER OPTIONS

294       Filter options have effect on queries (-Q and query short-forms), grep
295       (-G), purge (-P) and export (-x), see also options in the DESCRIPTION
296       section.
297
298       Several filter options may be given. For an item to be loaded into
299       calcurse it must match all filters. In other words, filters are
300       logically "and"-ed. The --filter-type option has a default value which
301       matches any item. All other filter options have no default value and
302       only apply when explicitly set.
303
304       The filter options fall into three groups: general, calendar, todo. The
305       general filters apply to all items, the calendar filters concern start
306       and end times and apply to appointments and events only, and the todo
307       filters concern priority and completeness and apply to TODOs only.
308
309       Outside the three groups is the invert filter.
310
311       --filter-invert
312           Invert the combined effect of any other filters, i.e. load the
313           items that do not match them.
314
315   General filters
316       --filter-type type
317           Include items that match type. The type value is a comma-separated
318           list of type descriptions selected from event, apt, recur-event,
319           recur-apt and todo. You can also use recur as a shorthand for
320           recur-event,recur-apt and cal as a shorthand for event,apt,recur.
321
322       --filter-pattern pattern
323           Include items with a description that matches the pattern. The
324           pattern is interpreted as an extended regular expression.
325
326       --filter-hash string
327           Include items with a hash starting with string. The filter can be
328           negated by prepending an exclamation mark (!): include items with a
329           hash string not starting with string. For the (SHA1) hash of an
330           item refer to Extended format specifiers.
331
332   Calendar filters
333       For filter options ending in -from, -to, -after, -before and -range,
334       start or end time is the filter criterion.
335
336       An event is an all-day appointment for which no times are displayed.
337       The start time of an event is the beginning of the event day
338       (midnight), the end time is the end of the event day (one second before
339       next midnight).
340
341       The -start- options ending in -from, -after and -range refer to the
342       same filter criterion and cannot be used together. The same is the case
343       for options ending in -to, -before and -range. Similar restrictions
344       apply to -end- options.
345
346       Start and end times of a recurrent item refer to the very first
347       occurrence, not to those of any of the repetitions. If a recurrent item
348       meets the criterion, all of the repetitions are displayed in queries,
349       even though they may not meet the criterion. If they are unwanted, they
350       may be removed from the output with the day range options, although
351       this will also remove other items in that range.
352
353       --filter-start-from date
354           Include items that start at or after a given date.
355
356       --filter-start-to date
357           Include items that start at or before a given date.
358
359       --filter-start-after date
360           Include items that start after a given date.
361
362       --filter-start-before date
363           Include items that start before a given date.
364
365       --filter-start-range range
366           Include items with a start date that belongs to a given range. A
367           range consists of a start date and an end date, separated by a
368           comma.
369
370       --filter-end-from date
371           Include items that end at or after a given date.
372
373       --filter-end-to date
374           Include items that end at or before a given date.
375
376       --filter-end-after date
377           Include items that end after a given date.
378
379       --filter-end-before date
380           Include items that end before a given date.
381
382       --filter-end-range range
383           Include items with an end date that belongs to a given range. A
384           range consists of a start date and an end date, separated by a
385           comma.
386
387   Todo filters
388       --filter-priority priority
389           Include TODO items with a given priority.
390
391       --filter-completed
392           Include completed TODO items.
393
394       --filter-uncompleted
395           Include uncompleted TODO items.
396

FORMAT OPTIONS

398       Format options have effect on queries, grep and --dump-imported.
399
400       The options specify a format for appointments, recurring appointments,
401       events, recurring events or todo items, respectively.
402
403       --format-apt format, --format-recur-apt format, --format-event format,
404       --format-recur-event format, --format-todo format
405           The format argument is a string composed of printf-style format
406           specifiers, which are replaced as explained below, and ordinary
407           characters, which are copied to stdout without modification. Each
408           option has a default format string which is used when the option is
409           not given. Default strings are described in Default Format Strings.
410
411           Note: Use of a format option requires explicit formatting of field
412           separation and line spacing.
413
414   Default format strings
415       Each specifier is introduced by a % followed by a character which tells
416       what to print. The available specifiers depend on the item type. Times
417       are printed as hours and minutes (hh:mm) unless otherwise noted; time
418       formats can be changed with extended specifiers.
419
420       For each format option there is a default format string which is used
421       when the option is not given. In query results the default format
422       options are:
423
424           --format-apt " - %S -> %E\n\t%m\n"
425           --format-recur-apt " - %S -> %E\n\t%m\n"
426           --format-event " * %m\n"
427           --format-recur-event " * %m\n"
428           --format-todo "%p. %m\n"
429
430       In all other cases (grep and dump-imported) the default format string
431       is "%(raw)".
432
433   Appointments
434       %d
435           Print the duration of the appointment in seconds
436
437       %e
438           Print the end time of the appointment as the Unix time in seconds
439
440       %E
441           Print the end time of the appointment or the marker ..:..  if it
442           ends after midnight
443
444       %m
445           Print the description of the item
446
447       %n
448           Print the name of the note file belonging to the item
449
450       %N
451           Print the note belonging to the item
452
453       %r
454           Print the remaining time before the appointment
455
456       %s
457           Print the start time of the appointment as the Unix time in seconds
458
459       %S
460           Print the start time of the appointment or the marker ..:..  if it
461           begins before midnight
462
463   Events
464       %m
465           Print the description of the item
466
467       %n
468           Print the name of the note file belonging to the item
469
470       %N
471           Print the note belonging to the item
472
473   Todo items
474       %m
475           Print the description of the item
476
477       %n
478           Print the name of the note file belonging to the item
479
480       %N
481           Print the note belonging to the item
482
483       %p
484           Print the priority of the item
485
486   Extended format specifiers
487       Extended format specifiers can be used to control the printing of times
488       for some of the single-letter specifiers. Additionally there are two
489       specifiers that do not have any corresponding short form and are
490       intended for use in scripting.
491
492       %(duration[:format])
493           extended form of %d
494
495       %(remaining[:format])
496           extended form of %r
497
498           format may contain any of the strftime(3) specifiers %d, %H, %M or
499           %S with the following modifications: 1) days are not limited to the
500           "calendar" values 0-31 (hours, minutes and seconds are "clock"
501           values, but see E in the following) 2) each number is by default
502           padded with zeros to two decimal places, 3) the % character may be
503           followed by one or two optional flags: -, which suppresses the
504           zero-padding, E, which will suppress the "clock" limits on %H, %M
505           and %S; if both are used, - must precede E, 4) no other flags or
506           width specifications are supported
507
508       %(start[:format])
509           extended form of %s
510
511       %(end[:format])
512           extended form of %e
513
514           format may be any strftime(3) format specifier or one of the
515           strings epoch or default; the former is equivalent to the
516           (calcurse) specifiers %s and %e (seconds since the Epoch); the
517           latter is equivalent to the (calcurse) specifiers %S and %E or the
518           (strftime) format string %H:%M, except that the continuation marker
519           ..:..  is printed if the start/end time belongs to another day
520
521       %(raw)
522           the text file format of an item as saved on disk; the default
523           format for the grep and dump-imported options; can be used with all
524           format options
525
526       %(hash)
527           the (SHA1) hash of the above; can be used with all format options
528

EXAMPLES

530       calcurse -d tomorrow
531           Display the calendar for tomorrow (same as calcurse -Q
532           --filter-type cal --from tomorrow).
533
534       calcurse -d friday
535           Display the calendar for the upcoming friday.
536
537       calcurse -d 7
538           Display the calendar for the next seven days (same as calcurse -Q
539           -filter-type cal --days 7).
540
541       calcurse -r7 --format-apt " - %S -> %E\n\t%m\n%N"
542           Print appointments and events for the next seven days. Also, print
543           the notes attached to each regular appointment.
544
545       calcurse -r7 --format-apt " - %m (%S to %E)\n" --format-recur-apt " -
546       %m (%S to %E)\n"
547           Print appointments and events for the next seven days and use a
548           custom format for (recurrent) appointments:
549
550           - Some appointment (18:30 to 21:30)
551
552       calcurse -t --format-todo "(%p) %m\n"
553           List all todo items and put parentheses around the priority
554           specifiers.
555
556       If the calcurse data files contain many entries which are no longer
557       needed or wanted, they can, of course, be removed interactively. If
558       there are many, it can be a tedious task and may be done better as in
559       the following two examples.
560
561       calcurse --input-datefmt 4 -G --filter-start-before 2015-1-1
562           List event and appointment entries in the data files with a start
563           time before 1 January 2015, and all TODO entries.
564
565           Purge. When -G is replaced by -P, those entries are removed. This
566           may remove recurring items that have occurrences after 1 January
567           2015.
568
569       calcurse --input-datefmt 1 -G --filter-start-from 11/1/2015
570       --filter-type event,apt
571           List (ordinary) event and appointment entries with a start time of
572           1 November 2015 or later.
573
574       calcurse -G --filter-type apt --format-apt "%(hash) %m\n"
575           For each appointment list the SHA1 hash of the data file entry
576           followed by the description.
577
578       calcurse -G --filter-type apt --format-apt
579       "%(duration:%d/%EH/%EM)\t%m\n"
580           For each appointment list the (total) duration as either days,
581           hours or minutes followed by the description.
582
583       calcurse -G --filter-type apt --format-apt "%(start:%c) %(duration:%d
584       %H:%M)\t%m\n"
585           For each appointment list the start time in a localized standard
586           format, followed by the duration in days, hours and minutes,
587           followed by the description.
588

FILES

590       The following structure is created by default in your home directory
591       the first time calcurse is run without any options:
592
593           $XDG_DATA_HOME/calcurse/        $XDG_CONFIG_HOME/calcurse/
594                             |___apts                          |___conf
595                             |___notes/                        |___hooks/
596                             |___todo                          |___keys
597
598       $XDG_DATA_HOME defaults to $HOME/.local/share and $XDG_CONFIG_HOME
599       defaults to $HOME/.config.
600
601       The files are of two different kinds: data and configuration. The data
602       files constitute the calcurse database and are independent of the
603       calcurse release version; the configuration files depend on the
604       calcurse version although backwards compatibility is always aimed at.
605
606   Data files
607       The calendar file apts contains all of the user’s appointments and
608       events, and the todo file contains the todo list. The notes
609       subdirectory contains the notes which are attached to appointments,
610       events or todos. One text file is created per note, whose name is the
611       SHA1 message digest of the note itself.
612
613       The (hidden) lock files of the calcurse (.calcurse.pid) and daemon
614       (.daemon.log) programs are present when they are running. If daemon log
615       activity has been enabled in the notification configuration menu, the
616       file daemon.log is present.
617
618       An alternative calendar file may be specified with the -c option.
619
620   Configuration files
621       The conf file contains the user configuration and the keys file the
622       user-defined key bindings. The hooks directory contains user-supplied
623       scripts, see Hooks.
624
625   Directory configuration
626       An alternative directory for both the configuration files and the data
627       directory may be specified with the -D option.
628
629       An alternative directory for the configuration files only may be
630       specified with the -C option; in that case data files are either in the
631       default directory or in the directory specified by -D. If both -D and
632       -C are present, configuration files in the data directory, if any, are
633       ignored.
634
635       If $HOME/.calcurse exists, then it will be used as the default for both
636       the data directory and the configuration directory.
637
638           <datadir>      <confdir>
639                |             |
640                |__ apts      |___ conf
641                |__ todo      |___ keys
642                |__ notes/    |___ hooks/
643
644           defaults:
645                <datadir>: $XDG_DATA_HOME/calcurse ($HOME/.local/share/calcurse)
646                <confdir>: $XDG_CONFIG_HOME/calcurse ($HOME/.config/calcurse)
647                both: $HOME/.calcurse (only if it exists)
648
649       calcurse may switch between two configuration setups, but still access
650       the same data files e.g. with:
651
652           $ calcurse
653
654           $ calcurse -C "$HOME/.config/calcurse/config"
655
656   Hooks
657       Scripts placed in <confdir>/calcurse/hooks/ (see Directory
658       configuration) trigger actions at certain events. To enable a hook, add
659       a script with one of the following names to this directory. Also make
660       sure the script is executable.
661
662       pre-load
663           Executed before the data files are loaded.
664
665       post-load
666           Executed after the data files are loaded.
667
668       pre-save
669           Executed before the data files are saved.
670
671       post-save
672           Executed after the data files are saved.
673
674       Some examples can be found in the contrib/hooks/ directory of the
675       calcurse source tree.
676

ENVIRONMENT

678       A few environment variables affect how calcurse operates.
679
680       CALCURSE_EDITOR, VISUAL, EDITOR
681           Specifies the external editor to use for writing notes. They are
682           tried in the order listed until one is found. If none of them are
683           set, vi is used.
684
685       CALCURSE_PAGER, PAGER
686           Specifies - as for the editor - the default viewer to be used for
687           reading notes. Default is less.
688
689       MERGETOOL
690           Tool used to merge two files to solve a save conflict. Default is
691           vimdiff. The program is called with two file names as the only
692           arguments.
693
694       See also FILES.
695

BUGS

697       If you find a bug, please send a report to bugs@calcurse.org, or, if
698       you are a Github user, raise an issue at
699       https://github.com/lfos/calcurse.
700

SEE ALSO

702       The ical specification (rfc2445) can be found at:
703       http://tools.ietf.org/html/rfc2445
704
705       The pcal project page: http://pcal.sourceforge.net/
706
707       calcurse home page: http://calcurse.org/
708
709       calcurse at GitHub: https://github.com/lfos/calcurse
710
711       The complete manual, maintained in html format, can be found in the
712       doc/ directory of the source package, or at:
713       http://calcurse.org/files/manual.html
714

AUTHORS

716Frederic Culot <frederic@culot.org>
717
718Lukas Fleischer <lfleischer@calcurse.org>
719
721       Copyright (c) 2004-2020 calcurse Development Team. This software is
722       released under the BSD License.
723
724
725
726                                  04/11/2021                       CALCURSE(1)
Impressum