Command-line interface to calendars
Repo PyCalendar/plann, read from GitHub 1 min ago. PyCalendar has not joined Take My Repo.
PyCalendar/plann is a public repo on GitHub by PyCalendar. Command-line interface to calendars. It declares the GPL-3.0 license on GitHub. It is written mainly in Python, has 86 stars and last changed on 2026-11-21. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
Plann is a command-line CalDAV client, making it possible to add calendar events, browse an agenda and do task management.
This is the "next generation" version of my old calendar-cli project.
Perhaps this work is moot ... or perhaps just 20 years too late. Considering the recent progress of AI and chatbots, probably soon all calendar queries can be done in natural language.
There is a "competing" project at https://github.com/geier/khal - you may want to check it out - it's more mature but probably more complex. khal uses a "vdir" backend; a local directory with icalendar files. It is designed to operate offline (while some other tool can optionally synchronise this with a remote server). The philosophy behind plann and calendar-cli is the opposite: interact directly with a caldav server; no synchronisation, no local storage, just client-side operations.
Based on user feedback I decided to fork calendar-cli into plann. The discussion was held in a github issue in the calendar-cli project. calendar-cli is the old, mature, production-ready, stable API interface, it will hang around for some time to come, maybe I will spend some time bugfixing it, and I will for sure be accepting pull requests in a long time to come - at least if they primarily address bugfixes. plann is the new interface, I believe it can do all that calendar-cli is doing as of version 1.0.
The commands and options will be described further down, however examples often beat documentation. There is one example directory with some usage examples, and eventually I will also try to write up some test code that can serve as examples.
plann depends on several python libraries, e.g. icalendar, caldav, etc.
plannsudo make installInstalls plann under ~/.local/ (no root required):
plannmake installAn editable install, so changes in the working tree take effect without reinstalling:
plannmake dev (installs with pip install -e ".[dev]", including the test dependencies)plannThe package ships completion scripts for bash, zsh and fish. For a system-wide install under /usr (e.g. a distribution package) they work with no shell configuration - bash needs the bash-completion package installed, though. For bash, a --user, venv, pipx or uv tool install also works out of the box with bash-completion 2.12 or newer, and fish picks up a --user install. Elsewhere, point the shell at the install prefix:
fpath=(<prefix>/share/zsh/site-functions $fpath) before compinitset -a fish_complete_path <prefix>/share/fish/vendor_completions.dsource <prefix>/share/bash-completion/completions/plann#calendar-cli at irc.oftc.net (I'm not available 24/7 there), eventually support@plann.no, eventually the issue tracker at https://github.com/pycalendar/plann/issues
Before reaching out, please make sure all the dependencies are installed, and that you've installed the latest version of the caldav python library. If you're using the master branch of plann, you should also be using the master branch of the caldav python library.
GUIs and Web-UIs are nice for some purposes, but I really find the command line unbeatable when it comes to:
When I started writing calendar-cli, the predecessor to plann, all I could find was cadaver and the CalDAVClientLibrary. Both of those seems to be a bit shortcoming; they seem to miss the iCalendar parsing/generation, and there are things that simply cannot be done through those tools.
See also USER_GUIDE.md
plann [global options] [command] [command options] [subcommand] [subcommand options] [subcommand arguments] ...
I'm intending to make it easier by allowing plann to be symlinked to the various commands and also to allow the options to be placed wherever.
Only long options will be available in the early versions; I don't want to pollute the short option space before the CLI is reasonably well-defined.
Always consult --help for up-to-date and complete listings of options. The list below will only contain the most important options and may not be up-to-date and may contain features not implemented yet.
The caldav URL should be something like i.e. http://some.davical.server/caldav.php/ - it is only supposed to relay the server location, not the user or calendar. Things will most likely work if you give http://some.davical.server/caldav.php/pycalendar/work-calendar/ - but it will ignore the calendar part of it, and use first calendar it can find - which perhaps may be tobixen/family-calendar/. Use http://some.davical.server/caldav.php/ as the caldav URL, and /pycalendar/family-calendar as the calendar-url.
The list may not be complete. --help should give a more complete overview.
Supported since calendar_cli (predecessor to plann) v0.12:
Some of those may already be implemented, all should eventually work in some future version of plann:
Alternatively, endtime or duration can be given through options
This is a string containing variables enclosed in curly braces, like "uid: {uid}". Full documentation of the available variables will be given in version 1.0.
Particularly the uid can be useful, as one may want to use the uid for things like deleting events and postponing tasks.
In the examples folder there is a task management script which will use the --todo-template to create a new shell script for postponing all overdue tasks. This shell script can then be edited interactively and run.
With the todo-command, there are quite some options available (i.e. --categories, --limit, --todo-uid, etc) to select or filter tasks. Those are used by the commands list, edit, postpone, complete and delete. A typical use-case scenario is to first use the "list" command, tweak the filtering options to get a list containing the tasks one wants to operate with, and then use either edit, postpone, complete or delete.
The file TASK_MANAGEMENT.md contains some thoughts on how to organize tasks.
plann shares its configuration file with the caldav library and other calendar tools. Unless --config-file names one, it uses the first that exists of $XDG_CONFIG_HOME/pycal/calendar.yaml (by default ~/.config/pycal/calendar.yaml), ~/.config/caldav/calendar.conf, ~/.config/caldav/calendar.yaml, ~/.config/caldav/calendar.json, ~/.config/calendar.conf, /etc/calendar.conf and /etc/caldav/calendar.conf; CALENDARING_CONFIG_FILE or CALDAV_CONFIG_FILE may name another. plann configure creates ~/.config/pycal/calendar.yaml when none exists. plann supports both json and yaml.
(I considered .ini, but I was told that it's actually not a standard. I'd like any calendar application to be able to access the file, hence calendar.conf and not plann.conf)
The file may look like this:
{ "default":
{ "caldav_url": "http://foo.bar.example.com/caldav/",
"caldav_user": "luser",
"caldav_pass": "insecure"
}
}The file can be written by hand, or created and updated interactively with plann configure (experimental/under-tested - here be dragons).
The connection settings (caldav_url, caldav_user, caldav_pass, caldav_proxy, ...) may refer to environment variables as ${VAR}, or as ${VAR:-default} with a fallback value. This keeps secrets such as the password out of the file:
{ "default":
{ "caldav_url": "http://foo.bar.example.com/caldav/",
"caldav_user": "luser",
"caldav_pass": "${CALDAV_PASSWORD}"
}
}Instead of a password in the file or the environment, caldav_password_command may name a program (as a list of the program and its arguments) whose output is the password, and caldav_password_keyring a service name to look up in the system keyring:
default: caldav_url: http://foo.bar.example.com/caldav/ caldav_user: luser caldav_password_command: [pass, show, dav/work]
The command is only run when the config file is writable by nobody but its owner (chmod 600); plann configure writes the file with your umask, so check it after configuring. A section may also be written as kind: caldav with plain keys (url, username, password_command, ...). The file format is shared with the caldav library and other tools, and is specified in calendaring-config.
A features key may be given to enable server-specific compatibility workarounds, referring to a server profile in the caldav library's compatibility_hints module (e.g. "features": "ecloud"). For servers with a known profile, caldav_url may even be omitted - the caldav library will derive the URL from the profile.
A configuration with multiple sections may look like this:
{
"default":
{ "caldav_url": "http://foo.bar.example.com/caldav/",
"caldav_user": "luser",
"caldav_pass": "insecure"
},
"baz":
{ "caldav_url": "http://foo.baz.example.com/caldav/",
"caldav_user": "luser2",
"caldav_pass": "insecure2"
}
}Sections may also include calendar urls or ids, and sections may inherit other sections:
{
"default":
{ "caldav_url": "http://foo.bar.example.com/caldav/",
"caldav_user": "luser",
"caldav_pass": "insecure"
},
"baz":
{ "caldav_url": "http://foo.baz.example.com/caldav/",
"caldav_user": "luser2",
"caldav_pass": "insecure2"
}
},
"bazimportant":
{ "inherits": "baz",
"calendar_url": "important"
}plann will accept a parameter calendar_name, which should match with the display name of the calendar.
YAML seems to have more traction than JSON when it comes to configuration that is supposed to be read and edited by humans, hence plann will accept configuration files in yaml as well as json.
Since plann may operate at many calendars at one time, I decided to add the keyword "contains" to have one config section refer to multiple other config sections.
Example:
--- work-calendar: caldav_url: "http://acme.example.com/caldav/" caldav_user: drjekyll caldav_pass: pencilin calendar_url: mycalendar work-appointments: inherits: work-calendar calendar_url: mypatients private-calendar: caldav_url: "https://ecloud.global/remote.php/dav/" caldav_user: mrhyde caldav_pass: hunter2 calendar_name: goodgames brothel-appointments: inherits: private-calendar calendar_name: badgames work: contains: [ 'work-calendar', 'work-appointments' ] private: contains: [ 'private-calendar', 'brothel-appointments' ]
Add a calendar item "testevent" at 2013-10-01:
./plann --calendar-url=http://calendar.bekkenstenveien53c.oslo.no/caldav.php/tobias/calendar/ --caldav-server=http://calendar.bekkenstenveien53c.oslo.no/caldav.php --caldav-user=myusername --caldav-pass=mypassphrase add event testevent 2013-10-01
Add a todo item "change oil":
./plann --calendar-url=http://calendar.bekkenstenveien53c.oslo.no/caldav.php/tobias/calendar/ --caldav-server=http://calendar.bekkenstenveien53c.oslo.no/caldav.php --caldav-user=myusername --caldav-pass=mypassphrase add todo "change oil"
See USAGE.MD for further instructions on how to use plann.
See NEXT_LEVEL.md for the direction the project is heading.
PyCalendar/plann is a public repo on GitHub by PyCalendar. Command-line interface to calendars.
It declares the GPL-3.0 license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-21. GitHub counts 32 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Simple command-line CalDav client, for adding and browsing calendar items, todo list items
Handling of non-standard X-WR-TIMEZONE icalendar property in Python and Command Line (use for Google Calendar)
Find out what happens when in ICS calendar files - query RFC 5545 files for events, journals, TODOs and more
Django models for storing and exporting RFC 5545 iCalendar data.
pre-commit to automatically add all AI prompts to your commit message