calcurse Documentation

You can automate tasks by placing executable scripts in the <confdir>/hooks/ directory. The following hooks are supported:

• pre-load: Executed before data files are loaded.
• post-load: Executed after data files are loaded.
• pre-save: Executed before data files are saved.
• post-save: Executed after data files are saved.

The script maintains a synchronization database at $XDG_DATA_HOME/calcurse/caldav/sync.db (or ~/.calcurse/caldav/sync.db). This database stores a snapshot of the last execution.

During a run, the script compares the server state and the local state against this snapshot to:

1. Download and import new server objects.
2. Delete local objects that no longer exist on the server.
3. Upload local objects added to the server.
4. Delete objects from the server that were deleted locally.
5. Update the synchronization database snapshot.

Note: Because calcurse lacks unique identifiers for items, modifications are treated as a deletion of the old item followed by the creation of a new one.

When running calcurse in non-interactive mode, you can use filters to narrow down the results.

Supported filters include:

• --filter-type <type>: Use event, apt, recur-event, recur-apt, todo, or shorthands recur and cal.
• --filter-pattern <pattern>: Use an extended regular expression to match descriptions.
• --filter-priority <priority>: Only include items with a specific priority.
• --filter-completed / --filter-uncompleted: Filter TODO items by status.
• Date-based filters: --filter-start-from, --filter-start-to, --filter-start-after, --filter-start-before, --filter-start-range, --filter-end-from, --filter-end-to, --filter-end-after, --filter-end-before, --filter-end-range.
• --filter-hash <pattern>: Only include items with a hash starting with the pattern (use ! to invert).

You can automate tasks by placing executable scripts in the following directory:

• $XDG_CONFIG_HOME/calcurse/caldav/hooks/
• Or ~/.calcurse/caldav/hooks

Supported hook names:

• pre-sync: Executed before data files are synchronized.
• post-sync: Executed after data files are synchronized.

The calcurse repository is organized into the following directories:

• build-aux: Auxiliary files for the build process.
• contrib: Useful tools, including hooks and the CalDAV synchronization script.
• doc: Detailed documentation in plain text and HTML formats.
• po: Translations and internationalization (i18n) files.
• scripts: Official scripts, such as calcurse-upgrade.
• src: The core calcurse source code.
• test: The test suite and test cases.

calcurse uses a data directory and a configuration directory. By default, these are located at:

• Data: $XDG_DATA_HOME/calcurse (or $HOME/.local/share/calcurse)
• Config: $XDG_CONFIG_HOME/calcurse (or $HOME/.config/calcurse)
• If $HOME/.calcurse exists, it is used for both.

You can override these using -D <dir> (data) and -C <dir> (config).

Directory Structure

• apts: Contains all events and appointments.
• todo: Contains the todo list.
• notes/: Contains SHA1-hashed note files attached to items.
• conf: User configuration.
• keys: User-defined key bindings.
• hooks/: Scripts for event-based triggers.
• daemon.log: (Optional) Logs for background daemon activity.

All calcurse parameters can be configured through the Configuration menu. Press C to open the menu, which provides the following submenus:

• C: Color scheme configuration
• L: Layout configuration (position of the three panels)
• G: General options
• K: Key bindings configuration
• N: Notify-bar settings

The layout determines the position of the calendar, todo, and appointment panels. Use the L submenu in the Configuration menu to choose from eight different layouts.

To adjust the width of the sidebar (which contains the calendar and either the todo or appointment list), use the following option:

• appearance.sidebarwidth (default: 0): Width in percentage (0 is minimum).

To automate the process of exporting events, synchronizing with remotes via vdirsyncer, and importing the results, use the calcurse-vdirsyncer wrapper script located in the contrib directory.

Run calcurse-vdirsyncer -h to view available options and detailed usage instructions.

Key bindings can be redefined in the Keys configuration menu. The default keys follow a vim-like pattern, especially for displacement.

To define a new binding:

1. Highlight the action you wish to rebind.
2. Delete the existing binding if necessary.
3. Add the new binding by pressing the desired key.

Supported keys include:

• Lower-case and upper-case letters/numbers (e.g., a, Z, 0)
• CONTROL-key combinations
• escape, horizontal tab, and space
• Arrow keys (up, down, left, right)
• HOME and END keys

Note: Since version 3.0.0, displacement commands can be preceded by a number to repeat the command (e.g., 10k moves the cursor ten weeks forward using default bindings).

calcurse can be used in non-interactive mode to print specific information to the terminal and then exit. This is useful for shell scripts or displaying information at login.

Common non-interactive commands:

• -a, --appointment: Print appointments and events for the current day.
• -t, --todo: Print the TODO list. Use -t <priority> (1-9) for specific priorities, or -t 0 for completed tasks.
• -n, --next: Print the next appointment within the upcoming 24 hours.
• -r, --range <num>: Print events and appointments for the next num days.
• -Q, --query: Print all appointments and TODO items within a specified range (use --from and --to to define the range).