diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 40 |
1 files changed, 29 insertions, 11 deletions
@@ -3,9 +3,13 @@ calendar-cli Simple command-line CalDav client, for adding and browsing calendar items, todo list items, etc. As of version 0.11 it's even becoming a full-fledged task management tool. +Other tools +----------- + +There is another project out there, "Command-line Interface for Google Calendar", previously located at pypi under the calendar-cli name. It has now been renamed to gcalendar-cli to avoid name conflict, and is available at https://pypi.python.org/pypi/gcalendar-cli/ + 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. It's using a "vsyncdir" backend - if I've understood it correctly, that involves building a local copy of the calendar. The philosophy behind calendar-cli is slightly different, calendar-cli is supposed to be a simple cli-based caldav+ical client. No synchronization, no local storage. -*NOTE*: As of 2015-10, someone has uploaded a "Command-line Interface for Google Calendar" to pypi with the same name - https://pypi.python.org/pypi/calendar-cli/ - this is a different project! Support ------- @@ -17,7 +21,7 @@ Rationale GUIs and Web-UIs are nice for some purposes, but I really find the command line unbeatable when it comes to: -* Minor stuff that are repeated often. Writing something like "todo add make a calendar-cli system" or "cal add 'tomorrow 15:40+2h' doctor appointment" is just very much faster than navigating into some web calendar interface and add an item there. +* Minor stuff that are repeated often. Writing something like "todo add make a calendar-cli system" or "calendar add 'tomorrow 15:40+2h' doctor appointment" is just very much faster than navigating into some web calendar interface and add an item there. * Things that are outside the scope of the UI. Here is one of many tasks I'd like to do: "go through the work calendar, find all new calendar events that are outside office hours, check up with the personal calendar if there are potential conflicts, add some information at the personal calendar if appropriate", and vice versa - it has to be handled very manually if doing it through any normal calendar application as far as I know, but if having some simple CLI or python library I could easily make some interactive script that would help me doing the operation above. I've been looking a bit around, all I could find was cadaver and 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. @@ -41,11 +45,14 @@ not be up-to-date and may contain features not implemented yet. * --interactive: stop and query the user rather often * --caldav-url, --caldav-user, --caldav-pass: how to connect to the CalDAV server. Fits better into a configuration file. -* --config-file: use a specific configuration file (default: $HOME/.calendar-cli.conf) +* --calendar-url: url to the calendar one wants to use. +* --config-file: use a specific configuration file (default: $HOME/.config/calendar.conf) * --config-section: use a specific section from the config file (i.e. to select a different caldav-server to connect to) * --icalendar: Write or read icalendar to/from stdout/stdin * --nocaldav: don't connect to a caldav server +The caldav URL is supposed to 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. It's a common mistake to use something like http://some.davical.server/caldav.php/tobixen/work-calendar/ - it will also work, but it will ignore the calendar part of it, and use first calendar it can find - perhaps tobixen/family-calendar/. Use http://some.davical.server/caldav.php/ as the caldav URL, and tobixen/family-calendar as the calendar-url. + ### Commands * calendar - access/modify a calendar @@ -80,15 +87,29 @@ Configuration file is by default located in $HOME/.config/calendar.conf and shou The file may look like this: ```json -{ "default": - { "caldav_url": "http://foo.bar.example.com/caldav/", +{ "default": + { "caldav_url": "http://foo.bar.example.com/caldav/", + "caldav_user": "luser", + "caldav_pass": "insecure" + } +} +``` +A configuration with multiple sections may look like this: + +```json +{ "default": + { "caldav_url": "http://foo.bar.example.com/caldav/", "caldav_user": "luser", "caldav_pass": "insecure" + }, + "caldav_url": "http://foo.baz.example.com/caldav/", + "caldav_user": "luser2", + "caldav_pass": "insecure2" } } ``` -Optionally, in addition (or even instead) of "default", other "sections" can be created and selected through the --config-section option. The rationale is to allow configuration for multiple CalDAV-servers to remain in the same configuration file. Later versions will eventually be capable of copying events, or putting events into several calendars. +Optionally, in addition (or even instead) of "default", other "sections" can be created and selected through the --config-section option. The rationale is to allow configuration for multiple CalDAV-servers, or multiple calendars on the same CalDAV-server to remain in the same configuration file. Later versions will eventually be capable of copying events, or putting events into several calendars. Remember to `chmod og-r ~/.config/calendar.conf` or `chmod 0600 ~/.config/calendar.conf` @@ -96,7 +117,7 @@ Remember to `chmod og-r ~/.config/calendar.conf` or `chmod 0600 ~/.config/calend Add a calendar item "testevent" at 2013-10-01: - ./calendar-cli.py calendar --calendar-url=http://calendar.bekkenstenveien53c.oslo.no/caldav.php/tobias/calendar/ add 2013-10-01 testevent + ./calendar-cli.py --calendar-url=http://calendar.bekkenstenveien53c.oslo.no/caldav.php/tobias/calendar/ calendar add 2013-10-01 testevent (assumes that `caldav-url`, `calldav-pass` and `caldav-user` has been added into configuration file. Those may also be added as command line options) @@ -123,6 +144,7 @@ Changelog * 2015-03-30: version 0.8 - has a interactive configuration mode for those not feeling comfortable with hand-crafting the config in json syntax * 2015-03-30: version 0.9 - now it's possible to set a duration when adding events to the calendar. * 2015-05-02: version 0.10 - added support for todo subcommand +* 2016-01-23: version 0.11 - more work on tasks, some bugfixes, pulled in new command line options from Florian Tham and Zachary Palmer Roadmap ------- @@ -132,7 +154,3 @@ This is being moved out to the issues section in github. * Allow specification of event duration and/or event end time through options * Fix easy-to-use symlinks (or alternatively wrapper scripts) * Make some nosetests - -Donations ---------- -Donations are not expected, but as long as this is a one-man hobby project at least it's not problematic to receive donations. Send millibitcoins to 139xWFKwX9WejtRR1HP917qJGnRkZ6kn4M eventually. Donations may motivate me to work on specific feature requests or issues. |