caldavctl 0.0.20

Command line utility to interact with CalDAV servers

caldavctl

---

Table of Contents

• Installation
• Configuration
• Usage
• License

⚠️WARNING - This software is in the early stages of development, use at your own risk.

Installation

To install:

pipx install caldavctl

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

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:

[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

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

Usage

caldavctl uses sub commands to expose its functionality:

$ caldavctl --help
Usage: caldavctl [OPTIONS] COMMAND [ARGS]...

  caldavctl - command line CalDAV client

Options:
  -c, --config TEXT  Configuration file
  --name TEXT        Server nickname
  --username TEXT    Username on the CalDAV server
  --passwd TEXT      Password on the CalDAV server
  --url TEXT         Calendar CalDAV url
  --timezone TEXT    Your time zone
  --server TEXT      Default server (use nickname)
  --calendar TEXT    Default calendar id
  --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
  journal   Journal management
  todo      Todo management

Notes:

• The options to the main command override the configuration file;
• By default the configuration file is $HOME/.config/caldavctl/config.toml;
• Currently the journal sub-command is only a place holder;

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

Options:
  -d, --description  Show the event's description.
  -a, --all          Show all todos, including completed todos.
  --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:

# Mandatory
DTSTART: 2025-02-02 09:00
DTEND: 2025-02-02 09:45

# Recommended
SUMMARY:

# Optional
LOCATION:
CATEGORIES:
TIMEZONE:
PRIORITY: 5
ALARM: P0D
DESCRIPTION: [[ ]]

# NOTES:
#
#   * Date and time:
#       * The dates must be in iso format, for instance: 2024-12-29 13:45;
#       * The timezone used is the one defined by default or the one defined in
#         the "TIMEZONE" key;
#   * Categories: the categories are a comma separated list;
#   * Priority: 1 - highest priority, 9 - lowest priority
#   * Description: The description can be multi line, just make sure it's
#     delimited by [[ ]].
#   * Alarms:
#       * By default an alarm is defined the moment the event begins;
#       * The alarms are defined using:
#           ALARM: <trigger> [<description>]
#       * The trigger is defined according to:
#           https://datatracker.ietf.org/doc/html/rfc5545#autoid-38
#       * For example, to trigger an alarm 30 minutes before the event start, use:
#           ALARM: -PT30M
#       * The alarm description is optional

The start and end dates are, by default the next day from 9 to 9:45.

License

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