CALCURSE(1)

📦
version 4.8.2 · 4 versions
, in alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

CALCURSE(1) 💖

okay bestie, welcome to the calcurse manual page — a terminal-based organizer for interactive and command line use. she does calendars, she does appointments, she does tasks, and she does it all in your terminal. let's get into it 🎀

✨ 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

so the first form is how you invoke calcurse interactively, and literally everything else is a command line form. ✨

the second form is all about queries (as opposed to interactive use, which is a whole different vibe). and for convenience, the common queries have abbreviated forms — those are the ones in the third line. every single query can be combined with filter options and format options, no cap.

the fourth form is operations on the calcurse data files — one for displaying entries, the other for removing them. yes, actually deleting. we'll get there.

the fifth form is the miscellaneous help-and-support corner, aka the "who do I ask for help" section. 🫶

all the details live in OPTIONS — that's where we're headed, don't worry.

🌸 DESCRIPTION 🌸

calcurse is a calendar and scheduling application for use in a terminal session (terminal emulator). when you invoke it with no options at all, calcurse drops straight into interactive mode; in most other cases, it prints output to the terminal and exits. she's here to help you keep track of events, appointments and everyday tasks. interactive mode is the moment for entering data, or for inspecting and editing entries that already exist. all data get saved to disk as text files. command line mode is for queries, administrative tasks, and for automating things in scripts (iykyk 🧚).

the interactive interface is built on ncurses and can be customized to match your preferences. customization covers program behaviour, visual appearance and key bindings, and it all happens interactively — the result is automatically saved to disk and loaded on every single invocation, so your setup is just there every time. 💅 available actions are documented in an online help system. and there's a configurable notification system that issues reminders of upcoming deadlines, because she's thoughtful like that.

when you leave the interactive program, a background daemon may keep running and issue reminders; it stops automatically when interactive mode is reentered. it just knows. ✨

this man page mainly describes the command-line mode. the next two subsections have some general descriptions of command line options and usage.

💜 Input and Output Date Format 💜

a lot of options need 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 (peep FILES). these formats are set in the "General Options" submenu in interactive mode. but here's the thing — particularly in scripts, it may be desirable for the formats to be independent of the local user configuration. for exactly that 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-?. also, 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 (check Filter Options) may be followed by a time-of-day specification in hours and minutes (24-hour clock). that 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. one. single. argument. don't split it, she will be confused.

🌈 Filter, format and day range options 🌈

these options do not accomplish anything in and of themselves. they're influencers, not main characters — they influence other options. and they're kind of opposites of each other: filter options affect the input to calcurse, while format and day range options affect 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)
  • format options describe how it is presented

filter options have effect on queries (-Q and the 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. periodt. 👑

✨ OPTIONS ✨

okay bestie so most of these options literally flip calcurse into command line mode, like it stops being a whole interactive vibe and just does the one thing you asked and dips. the ones that also work while you're in interactive mode? they get labeled (also interactively) so you know they're chill both ways. 🫶

  • -a, --appointment — prints the appointments and events for the current day, that's it, that's the whole job. equivalent to -Q --filter-type cal. 💖
  • -c file, --calendar file — (also interactively) tells calcurse which calendar file to use. the default calendar lives at <datadir>/apts (peep the FILES section for the deets). if file isn't an absolute path name, it gets interpreted relative to the current working directory. also, this option has precedence over -D. 👑
  • -C dir, --confdir dir — (also interactively) pick which configuration directory to use. the FILES section has the default directory and how it interacts with -D, so go look if you're curious. ✨
  • -D dir, --datadir dir — (also interactively) pick which (data) directory to use. again, FILES section covers the default directory and the -C interaction situation. 🌸
  • -d date|num, --day date|num — prints appointments and events for a given date, or for a given range of days, and which one you get depends on the argument format you hand it:
    • a date
    • a number num

so with the first case, appointments and events for date come back. with the second, you get those for num days. positive values of num mean the future, negative means the past, and the range either starts or ends with the current day. for 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 — starts calcurse in background mode, and restarts it if the daemon was already running. usually this happens automatically when you set the configuration option daemon.enable in the Notify submenu in interactive mode, so you lowkey never have to type it yourself. 💅
  • --days num — sets the range of days when it's 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 you're importing items, this prints each newly created object to stdout. format options can be used to specify which details get printed. also see Format Options. 👀
  • --export-uid — when exporting items, this adds the hash of each item to the exported object as a UID property. ✨
  • --from date — sets 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 is not the same as -P (it does not use the invert filter option). 💀
  • -g, --gc — runs 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 this happens automatically when you set the configuration option general.autogc in the General Options submenu in interactive mode. 🧹
  • -G, --grep — prints appointments, events and TODO items in calcurse data file format. 🌈
  • -h, --help — prints a short help text describing the supported command-line options. classic. 🫶
  • -i file, --import file — imports the icalendar data contained in file. 📥
  • --input-datefmt format — for command line and script use only: overrides the configuration file setting of the option format.inputdate (that's the 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 — limits the number of results printed to num. keep it cute, keep it short. ✂️
  • -n, --next — prints 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: overrides 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 — loads items from the data files and saves 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: bestie be SO careful with this one. 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. fr fr. 😭
  • -q, --quiet — (also interactively) be quiet. do not show system dialogs. 🤫
  • -Q, --query — prints 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] — prints 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! so like, don't do that unless you're okay with the ghosting. 👻
  • -s[date], --startday[=date] — prints 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, prints only the items having a description that matches the given regular expression. equivalent to -Q --filter-pattern regex. 🔍
  • --status — displays the status of running instances of calcurse, interactive or background mode. the process pid is also printed. 📊
  • -t[num], --todo[=num] — prints 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's 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 — sets 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 — displays calcurse version. 💜
  • -x[format], --export[=format] — exports 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 💾

okay so the very first time you run calcurse with zero options, it just goes ahead and builds this whole lil home for itself in your home directory, like a hermit crab finding a shell 🐚:

$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. that's just the rules bestie, no cap 💅

so these files come in exactly two flavors, and the difference actually matters:

  • data files — this is the calcurse database, and it does not care what calcurse release version you're on. version-agnostic queen 👑
  • configuration files — these do depend on the calcurse version, tho backwards compatibility is always the goal, so they're trying their best fr fr

🗂️ Data files

  • the calendar file apts holds all of the user's appointments and events 🗓️
  • the todo file holds the todo list ✅
  • the notes subdirectory holds the notes attached to appointments, events or todos 📝 — one text file per note, and the filename is literally the SHA1 message digest of the note itself (cryptographic baddie behavior, we love to see it)
  • the (hidden) lock files of the calcurse program (.calcurse.pid) and the daemon (.daemon.log) show up while those things are running
  • if daemon log activity has been enabled in the notification configuration menu, then the file daemon.log is present
  • you can point at a totally different calendar file with the -c option ✨

⚙️ Configuration files

  • conf = the user configuration
  • keys = the user-defined key bindings ⌨️
  • the hooks directory = user-supplied scripts, go read Hooks below

🏠 Directory configuration

  • you can set an alternative directory for both the configuration files and the data directory with the -D option
  • you can set an alternative directory for the configuration files only with the -C option — in that case, data files live either in the default directory or in whatever -D said
  • if both -D and -C are present, then configuration files sitting in the data directory (if any) get ignored. periodt 🙅
  • if $HOME/.calcurse exists, then it gets 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)

and here's the cute part — calcurse can bounce between two config setups while still reading the same data files, like this:

$ calcurse

$ calcurse -C "$HOME/.config/calcurse/config"

switching outfits, same soul 🦋

🪝 Hooks

scripts dropped into <confdir>/calcurse/hooks/ (peep Directory configuration above) trigger actions at certain events. to enable a hook, add a script with one of these names to that directory — and make sure the script is executable, or it's just gonna sit there doing nothing 😭

  • 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 live in the contrib/hooks/ directory of the calcurse source tree 🎀

🌍 ENVIRONMENT

a few environment variables change how calcurse operates, so let's give them their moment:

  • CALCURSE_EDITOR, VISUAL, EDITOR — specifies the external editor used for writing notes. they're tried in the order listed until one is found. if none of them are set, vi is used 👑
  • CALCURSE_PAGER, PAGER — specifies — same deal as the editor — the default viewer used for reading notes. default is less 📖
  • MERGETOOL — the 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 up there, bestie, it's all connected ✨

🐛 BUGS

if you find a bug, pls send a report to bugs@calcurse.org, or — if you're a Github user — raise an issue at https://github.com/lfos/calcurse. we're not gonna be weird about it, just tell us 💖

👀 SEE ALSO

👑 AUTHORS

  • Frederic Culot <frederic@culot.org>
  • Lukas Fleischer <lfleischer@calcurse.org>

absolute legends, both of them 💜

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

and that's the whole vibe check, bestie 🌸 this was CALCURSE(1), page 1 of section 1, and the copy you're holding is dated 08/07/2025 💅 go schedule something iconic. mwah 🫶✨

📦 where this page comes from