1CALCURSE(1) CALCURSE(1)
2
6 calcurse - terminal-based organizer for interactive and command line
7 use
8
10 calcurse [-D datadir] [-C confdir] [-c calendar-file]
11 calcurse -Q [--from date] [--to date | --days number]
13 calcurse -a | -d date | -d number | -n | -r[number] | -s[date] |
15 -t[number]
16 calcurse -G [filter options] [format options] | -P [filter options]
18 [format options]
19 calcurse -h | --status | -g | -i file | -x[file] | --daemon
21 The first form shows how to invoke calcurse interactively; the
23 remainder is command line forms.
24 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 The fourth form shows operations on the calcurse data files, one for
31 display of entries, the other for removal of them.
32 The fifth form is miscellaneous help and support functions.
34 All details are in OPTIONS.
36
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 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 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 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 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 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 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 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 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 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
101 Most options imply command line mode. Options compatible with
102 interactive mode are marked "(also interactively)".
103 -a, --appointment
105 Print the appointments and events for the current day. Equivalent
106 to -Q --filter-type cal.
107 -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 -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 -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 -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 • a date
129 • a number num
131 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 --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 --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 --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 --export-uid
159 When exporting items, add the hash of each item to the exported
160 object as a UID property.
161 --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 -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 -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 -G, --grep
180 Print appointments, events and TODO items in calcurse data file
181 format.
182 -h, --help
184 Print a short help text describing the supported command-line
185 options.
186 -i file, --import file
188 Import the icalendar data contained in file.
189 --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 -l num, --limit num
198 Limit the number of results printed to num.
199 -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 --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 -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 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 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 -q, --quiet
229 (also interactively) Be quiet. Do not show system dialogs.
230 -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 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 Day range has an effect on queries only.
243 -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 --read-only
252 (also interactively) Do not save configuration nor appointments and
253 todos.
254 Warning: If you run calcurse interactively in read-only mode, all
256 changes from that session will be lost without warning!
257 -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 -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 --status
268 Display the status of running instances of calcurse, interactive or
269 background mode. The process pid is also printed.
270 -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 --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 -v, --version
286 Display calcurse version.
287 -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
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 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 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 Outside the three groups is the invert filter.
310 --filter-invert
312 Invert the combined effect of any other filters, i.e. load the
313 items that do not match them.
314 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 --filter-pattern pattern
323 Include items with a description that matches the pattern. The
324 pattern is interpreted as an extended regular expression.
325 --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 Calendar filters
333 For filter options ending in -from, -to, -after, -before and -range,
334 start or end time is the filter criterion.
335 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 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 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 --filter-start-from date
354 Include items that start at or after a given date.
355 --filter-start-to date
357 Include items that start at or before a given date.
358 --filter-start-after date
360 Include items that start after a given date.
361 --filter-start-before date
363 Include items that start before a given date.
364 --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 --filter-end-from date
371 Include items that end at or after a given date.
372 --filter-end-to date
374 Include items that end at or before a given date.
375 --filter-end-after date
377 Include items that end after a given date.
378 --filter-end-before date
380 Include items that end before a given date.
381 --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 Todo filters
388 --filter-priority priority
389 Include TODO items with a given priority.
390 --filter-completed
392 Include completed TODO items.
393 --filter-uncompleted
395 Include uncompleted TODO items.
396
398 Format options have effect on queries, grep and --dump-imported.
399 The options specify a format for appointments, recurring appointments,
401 events, recurring events or todo items, respectively.
402 --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 Note: Use of a format option requires explicit formatting of field
412 separation and line spacing.
413 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 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 --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 In all other cases (grep and dump-imported) the default format string
431 is "%(raw)".
432 Appointments
434 %d
435 Print the duration of the appointment in seconds
436 %e
438 Print the end time of the appointment as the Unix time in seconds
439 %E
441 Print the end time of the appointment or the marker ..:.. if it
442 ends after midnight
443 %m
445 Print the description of the item
446 %n
448 Print the name of the note file belonging to the item
449 %N
451 Print the note belonging to the item
452 %r
454 Print the remaining time before the appointment
455 %s
457 Print the start time of the appointment as the Unix time in seconds
458 %S
460 Print the start time of the appointment or the marker ..:.. if it
461 begins before midnight
462 Events
464 %m
465 Print the description of the item
466 %n
468 Print the name of the note file belonging to the item
469 %N
471 Print the note belonging to the item
472 Todo items
474 %m
475 Print the description of the item
476 %n
478 Print the name of the note file belonging to the item
479 %N
481 Print the note belonging to the item
482 %p
484 Print the priority of the item
485 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 %(duration[:format])
493 extended form of %d
494 %(remaining[:format])
496 extended form of %r
497 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 %(start[:format])
509 extended form of %s
510 %(end[:format])
512 extended form of %e
513 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 %(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 %(hash)
527 the (SHA1) hash of the above; can be used with all format options
528
530 calcurse -d tomorrow
531 Display the calendar for tomorrow (same as calcurse -Q
532 --filter-type cal --from tomorrow).
533 calcurse -d friday
535 Display the calendar for the upcoming friday.
536 calcurse -d 7
538 Display the calendar for the next seven days (same as calcurse -Q
539 -filter-type cal --days 7).
540 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 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 - Some appointment (18:30 to 21:30)
551 calcurse -t --format-todo "(%p) %m\n"
553 List all todo items and put parentheses around the priority
554 specifiers.
555 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 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 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 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 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 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 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
590 The following structure is created by default in your home directory
591 the first time calcurse is run without any options:
592 $XDG_DATA_HOME/calcurse/ $XDG_CONFIG_HOME/calcurse/
594 |___apts |___conf
595 |___notes/ |___hooks/
596 |___todo |___keys
597 $XDG_DATA_HOME defaults to $HOME/.local/share and $XDG_CONFIG_HOME
599 defaults to $HOME/.config.
600 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 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 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 An alternative calendar file may be specified with the -c option.
619 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 Directory configuration
626 An alternative directory for both the configuration files and the data
627 directory may be specified with the -D option.
628 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 If $HOME/.calcurse exists, then it will be used as the default for both
636 the data directory and the configuration directory.
637 <datadir> <confdir>
639 | |
640 |__ apts |___ conf
641 |__ todo |___ keys
642 |__ notes/ |___ hooks/
643 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 calcurse may switch between two configuration setups, but still access
650 the same data files e.g. with:
651 $ calcurse
653 $ calcurse -C "$HOME/.config/calcurse/config"
655 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 pre-load
663 Executed before the data files are loaded.
664 post-load
666 Executed after the data files are loaded.
667 pre-save
669 Executed before the data files are saved.
670 post-save
672 Executed after the data files are saved.
673 Some examples can be found in the contrib/hooks/ directory of the
675 calcurse source tree.
676
678 A few environment variables affect how calcurse operates.
679 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 CALCURSE_PAGER, PAGER
686 Specifies - as for the editor - the default viewer to be used for
687 reading notes. Default is less.
688 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 See also FILES.
695
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
702 The ical specification (rfc2445) can be found at:
703 http://tools.ietf.org/html/rfc2445
704 The pcal project page: http://pcal.sourceforge.net/
706 calcurse home page: http://calcurse.org/
708 calcurse at GitHub: https://github.com/lfos/calcurse
710 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
716 • Frederic Culot <frederic@culot.org>
717 • Lukas Fleischer <lfleischer@calcurse.org>
719
721 Copyright (c) 2004-2020 calcurse Development Team. This software is
722 released under the BSD License.
723 04/11/2021 CALCURSE(1)