caldavctl

PyPI - Version PyPI - Python Version

Table of Contents

• Installation
• Configuration
• Usage
• License

Installation

To install:

pipx install caldavctl

Completion

Optionally enable completion:

• bash, add this to ~/.bashrc:

  eval "$(_CALDAVCTL_COMPLETE=bash_source caldavctl)"
  

• zsh, add this to ~/.zshrc:

  eval "$(_CALDAVCTL_COMPLETE=zsh_source caldavctl)"
  

• fish, add this to ~/.config/fish/completions/foo-bar.fish:

  _CALDAVCTL_COMPLETE=fish_source caldavctl | source
  

Configuration

caldavctl is configured in $HOME/.config/caldavctl/config.toml and on windows C:\Users\<user name>\AppData\Local\caldavctl\caldavctl\config.toml:

[server.server_01_nickname]
username="your user"
password="your pass"
url="https://oneserver.org/cal"
[server.server_02_nickname]
username="your user"
password="your pass"
url="https://anotherserver.org/cal"
[default]
server="server_01_nickname"
calendar="Default"
timezone="Asia/Tokyo"

Make sure to make this file readable only by the user owner of the file otherwise the configuration will not be read:

$ chmod go-rwx $HOME/.config/caldavctl/config.toml

On windows this check is not made, however it's good practice to make sure the configuration is only readable by the user running caldavctl.

To be able to edit events, on windows, make sure you create an environment variable called VISUAL pointing to an editor of your choice. For instance:

set VISUAL=nvim

or

set VISUAL=notepad

Usage

caldavctl uses sub commands to expose its functionality:

$ caldavctl --help
Usage: caldavctl [options] COMMAND [ARGS]...
caldavctl - command line CalDAV client
Options:
-c, --config <file> Configuration file
--name <nickname> Server nickname
--username <username> Username on the CalDAV server
--passwd <passwd> Password on the CalDAV server
--url <url> Calendar CalDAV url
--timezone <timezone> Your time zone
--server <nickname> Default server (use nickname)
--calendar <uid> Default calendar id
--version caldavctl version
--help Show this message and exit.
Commands:
br Backup or restore a calendar
calendar Commands that deal with the calendars on the server
event Event management
ics iCalendar file operations
todo Todo management
utils Utility commands

Notes:

• The options to the main command override the configuration file;
• By default the configuration file is $HOME/.config/caldavctl/config.toml;

To get help about a sub-command do:

$ caldavctl <sub-command> --help

For example:

$ caldavctl event --help
Usage: caldavctl event [OPTIONS] COMMAND [ARGS]...
 Event management
Options:
 --help Show this message and exit.
Commands:
 create Create new event
 delete Delete an event on the server
 list List events from the server list.

This holds true for sub-sub-commands:

$ caldavctl todo list --help
Usage: caldavctl todo list [options]
List todos from the default server and default calendar
caldavctl uses templates to display the list command output by default. If
not specified otherwise it uses the `todo.txt` template. The used template
can be specified using the -tf/--template-file option. First we check the
current directory for the existence of the file. If it's not found we check
the `<share>/caldavctl/templates` directory.
Currently we have the following templates:
 * todo.txt - output with colors (default)
 * todo-nocolor.txt
 * todo.html
If the --json flag is used, the list command will output JSON. This output
does not go through the template system, and any template options will be
ignored when using --json.
Options:
-sd, --show-description Show the todo's description.
-si, --show-uid Show the todo's UID.
-a, --all Show all todos, including completed todos.
-tf, --template-file <file> Template used to format the output
--json Output JSON instead of using a template
--help Show this message and exit.

The create event command

The create event command uses a simple key: value format to define the elements of an event. If the --edit option is used without specifying a file, an example file is opened on your editor.

The $VISUAL environment variable is checked first to determine which editor to use. If it is not set, $EDITOR is used. If neither is defined, the default editor is vi.

Here's a minimal event:

DTSTART: 2025年02月02日 09:00
DURATION: PT30M
SUMMARY: Just an example!

Read the documentation about the event definition format in docs/caldav_event_config_format.md.

Templates

Certain command have their output formatted with a template. See, for example:

caldavctl event list --help

If you want to create your own templates read docs/caldav_templates.md.

License

caldavctl is distributed under the terms of the GPL-3.0-or-later license.