| Name | caldavctl JSON |
| Version |
0.0.24
JSON |
| download |
| home_page | None |
| Summary | Command line utility to interact with CalDAV servers |
| upload_time | 2025-11-04 19:26:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
caldav
cli
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# caldavctl
[](https://pypi.org/project/caldavctl)
[](https://pypi.org/project/caldavctl)
-----
## Table of Contents
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [License](#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`:
```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:
```bash
$ 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:
```bash
$ 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:
```bash
$ caldavctl <sub-command> --help
```
For example:
```bash
$ 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:
```bash
$ 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](docs/caldav_event_config_format.md).
### Templates
Certain command have their output formatted with a template. See, for example:
```bash
caldavctl event list --help
```
If you want to create your own templates read [docs/caldav_templates.md](docs/caldav_templates.md).
## License
`caldavctl` is distributed under the terms of the [GPL-3.0-or-later](https://spdx.org/licenses/GPL-3.0-or-later.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "caldavctl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "caldav, cli",
"author": null,
"author_email": "Helder Guerreiro <helder@paxjulia.org>",
"download_url": "https://files.pythonhosted.org/packages/17/07/a5d56dd1849d134e82c65b71257c378c2ed6a7a5bf841eba005d6403a9c3/caldavctl-0.0.24.tar.gz",
"platform": null,
"description": "# caldavctl\n\n[](https://pypi.org/project/caldavctl)\n[](https://pypi.org/project/caldavctl)\n\n-----\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [License](#license)\n\n## Installation\n\nTo install:\n\n pipx install caldavctl\n\n### Completion\n\nOptionally enable completion:\n\n* bash, add this to `~/.bashrc`:\n\n ```\n eval \"$(_CALDAVCTL_COMPLETE=bash_source caldavctl)\"\n ```\n\n* zsh, add this to `~/.zshrc`:\n\n ```\n eval \"$(_CALDAVCTL_COMPLETE=zsh_source caldavctl)\"\n ```\n\n* fish, add this to `~/.config/fish/completions/foo-bar.fish`:\n\n ```\n _CALDAVCTL_COMPLETE=fish_source caldavctl | source\n ```\n\n## Configuration\n\n`caldavctl` is configured in `$HOME/.config/caldavctl/config.toml` and on\nwindows `C:\\Users\\<user name>\\AppData\\Local\\caldavctl\\caldavctl\\config.toml`:\n\n```toml\n[server.server_01_nickname]\nusername=\"your user\"\npassword=\"your pass\"\nurl=\"https://oneserver.org/cal\"\n\n[server.server_02_nickname]\nusername=\"your user\"\npassword=\"your pass\"\nurl=\"https://anotherserver.org/cal\"\n\n[default]\nserver=\"server_01_nickname\"\ncalendar=\"Default\"\ntimezone=\"Asia/Tokyo\"\n```\n\nMake sure to make this file readable only by the user owner of the file\notherwise the configuration will not be read:\n\n```bash\n$ chmod go-rwx $HOME/.config/caldavctl/config.toml\n```\n\n**On windows this check is not made**, however it's good practice to make sure the\nconfiguration is only readable by the user running caldavctl.\n\nTo be able to edit events, on windows, make sure you create an environment\nvariable called `VISUAL` pointing to an editor of your choice. For instance:\n\n```\nset VISUAL=nvim\n```\n\nor\n\n```\nset VISUAL=notepad\n```\n\n## Usage\n\n`caldavctl` uses sub commands to expose its functionality:\n\n```bash\n$ caldavctl --help\nUsage: caldavctl [options] COMMAND [ARGS]...\n\ncaldavctl - command line CalDAV client\n\nOptions:\n-c, --config <file> Configuration file\n--name <nickname> Server nickname\n--username <username> Username on the CalDAV server\n--passwd <passwd> Password on the CalDAV server\n--url <url> Calendar CalDAV url\n--timezone <timezone> Your time zone\n--server <nickname> Default server (use nickname)\n--calendar <uid> Default calendar id\n--version caldavctl version\n--help Show this message and exit.\n\nCommands:\nbr Backup or restore a calendar\ncalendar Commands that deal with the calendars on the server\nevent Event management\nics iCalendar file operations\ntodo Todo management\nutils Utility commands\n```\nNotes:\n\n* The options to the main command override the configuration file;\n* By default the configuration file is `$HOME/.config/caldavctl/config.toml`;\n\nTo get help about a sub-command do:\n\n```bash\n$ caldavctl <sub-command> --help\n```\n\nFor example:\n\n```bash\n$ caldavctl event --help\nUsage: caldavctl event [OPTIONS] COMMAND [ARGS]...\n\n Event management\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create Create new event\n delete Delete an event on the server\n list List events from the server list.\n```\n\nThis holds true for sub-sub-commands:\n\n```bash\n$ caldavctl todo list --help\nUsage: caldavctl todo list [options]\n\nList todos from the default server and default calendar\n\ncaldavctl uses templates to display the list command output by default. If\nnot specified otherwise it uses the `todo.txt` template. The used template\ncan be specified using the -tf/--template-file option. First we check the\ncurrent directory for the existence of the file. If it's not found we check\nthe `<share>/caldavctl/templates` directory.\n\nCurrently we have the following templates:\n\n * todo.txt - output with colors (default)\n * todo-nocolor.txt\n * todo.html\n\nIf the --json flag is used, the list command will output JSON. This output\ndoes not go through the template system, and any template options will be\nignored when using --json.\n\nOptions:\n-sd, --show-description Show the todo's description.\n-si, --show-uid Show the todo's UID.\n-a, --all Show all todos, including completed todos.\n-tf, --template-file <file> Template used to format the output\n--json Output JSON instead of using a template\n--help Show this message and exit.\n```\n\n### The create event command\n\nThe `create event` command uses a simple `key: value` format to define the\nelements of an event. If the `--edit` option is used without specifying a file,\nan example file is opened on your editor.\n\nThe `$VISUAL` environment variable is checked first to determine which editor\nto use. If it is not set, `$EDITOR` is used. If neither is defined, the default\neditor is `vi`.\n\nHere's a minimal event:\n\n```\nDTSTART: 2025-02-02 09:00\nDURATION: PT30M\nSUMMARY: Just an example!\n```\nRead the documentation about the event definition format in [docs/caldav_event_config_format.md](docs/caldav_event_config_format.md).\n\n### Templates\n\nCertain command have their output formatted with a template. See, for example:\n\n```bash\ncaldavctl event list --help\n```\nIf you want to create your own templates read [docs/caldav_templates.md](docs/caldav_templates.md).\n\n## License\n\n`caldavctl` is distributed under the terms of the [GPL-3.0-or-later](https://spdx.org/licenses/GPL-3.0-or-later.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Command line utility to interact with CalDAV servers",
"version": "0.0.24",
"project_urls": {
"Documentation": "https://codeberg.org/hgg/caldavctl#readme",
"Issues": "https://codeberg.org/hgg/caldavctl/issues",
"Source": "https://codeberg.org/hgg/caldavctl"
},
"split_keywords": [
"caldav",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f8c9245766029c44c2dc75d080618b60877bd0f24978050fc7a1c3e185f67961",
"md5": "a426d8fbeff1444e25093f3a6f17286b",
"sha256": "d7ff1e9e26bbeb62523ac949595ca7ab60e6950c544b0cdc620212ed7063889d"
},
"downloads": -1,
"filename": "caldavctl-0.0.24-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a426d8fbeff1444e25093f3a6f17286b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 45089,
"upload_time": "2025-11-04T19:26:20",
"upload_time_iso_8601": "2025-11-04T19:26:20.026462Z",
"url": "https://files.pythonhosted.org/packages/f8/c9/245766029c44c2dc75d080618b60877bd0f24978050fc7a1c3e185f67961/caldavctl-0.0.24-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1707a5d56dd1849d134e82c65b71257c378c2ed6a7a5bf841eba005d6403a9c3",
"md5": "b116513bed44eefe57bf314e693a0bb8",
"sha256": "d0b9082ec8ec13f979d342beb548c4479cee0ab70976d76c664a764f04c78a3e"
},
"downloads": -1,
"filename": "caldavctl-0.0.24.tar.gz",
"has_sig": false,
"md5_digest": "b116513bed44eefe57bf314e693a0bb8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 39152,
"upload_time": "2025-11-04T19:26:21",
"upload_time_iso_8601": "2025-11-04T19:26:21.125633Z",
"url": "https://files.pythonhosted.org/packages/17/07/a5d56dd1849d134e82c65b71257c378c2ed6a7a5bf841eba005d6403a9c3/caldavctl-0.0.24.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-04 19:26:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "hgg",
"codeberg_project": "caldavctl#readme",
"lcname": "caldavctl"
}
