Provided by: calcurse_4.8.1-1_amd64 bug

NAME

       calcurse - terminal-based organizer for interactive and command line use

SYNOPSIS

       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.

DESCRIPTION

       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.

OPTIONS

       Most options imply command line mode. Options compatible with interactive mode are marked
       "(also interactively)".

       -a, --appointment
           Print the appointments and events for the current day. Equivalent to -Q --filter-type
           cal.

       -c file, --calendar file
           (also interactively) Specify the calendar file to use. The default calendar is located
           at <datadir>/apts (see FILES). If file is not an absolute path name, it is interpreted
           relative to the current working directory. The option has precedence over -D.

       -C dir, --confdir dir
           (also interactively) Specify the configuration directory to use. See section FILES for
           the default directory and the interaction with -D.

       -D dir, --datadir dir
           (also interactively) Specify the (data) directory to use. See section FILES for the
           default directory and the interaction with -C.

       -d date|num, --day date|num
           Print appointments and events for the given date or given range of days, depending on
           the argument format:

           •   a date

           •   a number 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.

       --daemon
           Start calcurse in background mode; restart, if the daemon was already running. Usually
           done automatically by setting the configuration option daemon.enable in the Notify
           submenu in interactive mode.

       --days num
           Specify the range of days when used with -Q. Can be combined with --from, but not with
           --to. Without --from, the first day of the range defaults to the current day. The
           number may be negative, see -Q --query.

       --dump-imported
           When importing items, print each newly created object to stdout. Format options can be
           used to specify which details are printed. See also Format Options.

       --export-uid
           When exporting items, add the hash of each item to the exported object as a UID
           property.

       --from date
           Specify the start date of the day range when used with -Q. When used without -to or
           --days the range is one day (the specified day), see -Q --query.

       -F, --filter
           Deprecated, see -P. Note that this option is for backward compatibility and not the
           same as -P (it does not use the invert filter option).

       -g, --gc
           Run the garbage collector for note files. The garbage collector removes files from the
           notes directory (see FILES) that are no longer linked to an item. Usually done
           automatically by setting the configuration option general.autogc in the General
           Options submenu in interactive mode.

       -G, --grep
           Print appointments, events and TODO items in calcurse data file format.

       -h, --help
           Print a short help text describing the supported command-line options.

       -i file, --import file
           Import the icalendar data contained in file.

       --input-datefmt format
           For command line and script use only: override the configuration file setting of the
           option format.inputdate (General Options submenu in interactive mode). A valid format
           is any of 1, 2, 3, or 4, with 1 = mm/dd/yyyy, 2 = dd/mm/yyyy, 3 = yyyy/mm/dd, 4 =
           yyyy-mm-dd.

       -l num, --limit num
           Limit the number of results printed to num.

       -n, --next
           Print the first appointment within the next 24 hours. The printed time is the number
           of hours and minutes left before this appointment.

       --output-datefmt format
           For command line and script use only: override the configuration file setting of the
           option format.outputdate (General Options submenu in interactive mode). A valid format
           is any strftime(3) format string.

       -P, --purge
           Load items from the data files and save them back; the items are described by suitable
           filter options (see Filter Options). It may be used to drop specific items from the
           data files, see EXAMPLES.

           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.

       -q, --quiet
           (also interactively) Be quiet. Do not show system dialogs.

       -Q, --query
           Print all appointments and events in a given range of days followed by all TODO items.
           The calendar part is displayed per day with a leading line containing the date and a
           trailing empty line (much like the calendar panel in interactive mode).

           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.

       -r[num], --range[=num]
           Print appointments and events for num number of days starting with the current day. If
           num is left out, a range of 1 day is used. The number may be negative in which case
           the range is in the past, ending with the current day. Equivalent to -Q --filter-type
           cal --days num.

       --read-only
           (also interactively) Do not save configuration nor appointments and todos.

           Warning: If you run calcurse interactively in read-only mode, all changes from that
           session will be lost without warning!

       -s[date], --startday[=date]
           Print events and appointments from the optional date; default is the current day.
           Equivalent to -Q --filter-type cal --from date.

       -S regex, --search regex
           When used with any of -a, -d, -r, -s, or -t 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, interactive or background mode.
           The process pid is also printed.

       -t[num], --todo[=num]
           Print the todo list. If the optional number num is given, then only uncompleted (open)
           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 (closed) 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 day range when used with -Q. When used without --from the
           start day is the current day. Cannot be combined with --days, see -Q --query.

       -v, --version
           Display calcurse version.

       -x[format], --export[=format]
           Export user data in the specified format. Events, appointments and todos are converted
           and echoed to stdout. Two formats are available: ical and pcal. The default format is
           ical.

FILTER OPTIONS

       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.

       --filter-invert
           Invert the combined effect of any other filters, i.e. load the items that do not match
           them.

   General filters
       --filter-type type
           Include items that match type. The type value is a comma-separated list of type
           descriptions selected from 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
           Include items with a description that matches the pattern. The pattern is interpreted
           as an extended regular expression.

       --filter-hash string
           Include items with a hash starting with string. The filter can be negated by
           prepending an exclamation mark (!): include items with a hash string not starting with
           string. For the (SHA1) hash of an item refer to Extended format specifiers.

   Calendar filters
       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.

       --filter-start-from date
           Include items that start at or after a given date.

       --filter-start-to date
           Include items that start at or before a given date.

       --filter-start-after date
           Include items that start after a given date.

       --filter-start-before date
           Include items that start before a given date.

       --filter-start-range range
           Include items with a start date that belongs to a given range. A range consists of a
           start date and an end date, separated by a comma.

       --filter-end-from date
           Include items that end at or after a given date.

       --filter-end-to date
           Include items that end at or before a given date.

       --filter-end-after date
           Include items that end after a given date.

       --filter-end-before date
           Include items that end before a given date.

       --filter-end-range range
           Include items with an end date that belongs to a given range. A range consists of a
           start date and an end date, separated by a comma.

   Todo filters
       --filter-priority priority
           Include TODO items with a given priority.

       --filter-completed
           Include completed TODO items.

       --filter-uncompleted
           Include uncompleted TODO items.

FORMAT OPTIONS

       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
           The format argument is a string composed of printf-style format specifiers, which are
           replaced as explained below, and ordinary characters, which are copied to stdout
           without modification. Each option has a default format string which is used when the
           option is not given. Default strings are described in Default Format Strings.

           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)".

   Appointments
       %d
           Print the duration of the appointment in seconds

       %e
           Print the end time of the appointment as the Unix time in seconds

       %E
           Print the end time of the appointment or the marker ..:..  if it ends after midnight

       %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

       %r
           Print the remaining time before the appointment

       %s
           Print the start time of the appointment as the Unix time in seconds

       %S
           Print the start time of the appointment or the marker ..:..  if it begins before
           midnight

   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

   Todo items
       %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

       %p
           Print the priority of the item

   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.

       %(duration[:format])
           extended form of %d

       %(remaining[:format])
           extended form of %r

           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

       %(start[:format])
           extended form of %s

       %(end[:format])
           extended form of %e

           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

       %(raw)
           the text file format of an item as saved on disk; the default format for the grep and
           dump-imported options; can be used with all format options

       %(hash)
           the (SHA1) hash of the above; can be used with all format options

EXAMPLES

       calcurse -d tomorrow
           Display the calendar for tomorrow (same as calcurse -Q --filter-type cal --from
           tomorrow).

       calcurse -d friday
           Display the calendar for the upcoming friday.

       calcurse -d 7
           Display the calendar for the next seven days (same as calcurse -Q -filter-type cal
           --days 7).

       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.

       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 parentheses around the priority specifiers.

       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
           List event and appointment entries in the data files with a start time before 1
           January 2015, and all TODO entries.

           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
           List (ordinary) event and appointment entries with a start time of 1 November 2015 or
           later.

       calcurse -G --filter-type apt --format-apt "%(hash) %m\n"
           For each appointment list the SHA1 hash of the data file entry followed by the
           description.

       calcurse -G --filter-type apt --format-apt "%(duration:%d/%EH/%EM)\t%m\n"
           For each appointment list the (total) duration as either days, hours or minutes
           followed by the description.

       calcurse -G --filter-type apt --format-apt "%(start:%c) %(duration:%d %H:%M)\t%m\n"
           For each appointment list the start time in a localized standard format, followed by
           the duration in days, hours and minutes, followed by the description.

FILES

       The following structure is created by default in your home directory the first time
       calcurse is run without any options:

           $XDG_DATA_HOME/calcurse/        $XDG_CONFIG_HOME/calcurse/
                             |___apts                          |___conf
                             |___notes/                        |___hooks/
                             |___todo                          |___keys

       $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.

   Data files
       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.

   Configuration files
       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.

   Directory configuration
       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.

           <datadir>      <confdir>
                |             |
                |__ 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"

   Hooks
       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.

       pre-load
           Executed before the data files are loaded.

       post-load
           Executed after the data files are loaded.

       pre-save
           Executed before the data files are saved.

       post-save
           Executed after the data files are saved.

       Some examples can be found in the contrib/hooks/ directory of the calcurse source tree.

ENVIRONMENT

       A few environment variables affect how calcurse operates.

       CALCURSE_EDITOR, VISUAL, EDITOR
           Specifies the external editor to use for writing notes. They are tried in the order
           listed until one is found. If none of them are set, vi is used.

       CALCURSE_PAGER, PAGER
           Specifies - as for the editor - the default viewer to be used for reading notes.
           Default is less.

       MERGETOOL
           Tool used to merge two files to solve a save conflict. Default is vimdiff. The program
           is called with two file names as the only arguments.

       See also FILES.

BUGS

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

SEE ALSO

       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

AUTHORS

Frederic Culot <frederic@culot.org>

       •   Lukas Fleischer <lfleischer@calcurse.org>

COPYRIGHT

       Copyright (c) 2004-2023 calcurse Development Team. This software is released under the BSD
       License.

                                            05/22/2023                                CALCURSE(1)