|
| 1 | +gcalcli |
| 2 | +======= |
| 3 | + |
| 4 | +*Google Calendar Command Line Interface* |
| 5 | + |
| 6 | +gcalcli is a Python application that allows you to access your Google |
| 7 | +Calendar(s) from a command line. It's easy to get your agenda, search for |
| 8 | +events, quickly add new events, and even import those annoying vCal invites |
| 9 | +from Microsoft Exchange. Additionally, gcalcli can be used as a reminder |
| 10 | +service to execute any application you want. |
| 11 | + |
| 12 | +*Check your OS Distribution for packages* |
| 13 | + |
| 14 | +Requirements |
| 15 | +------------ |
| 16 | + |
| 17 | + * [Python 2](http://www.python.org) |
| 18 | + * Google's [GData](http://code.google.com/p/gdata-python-client) Python 2 module |
| 19 | + * [dateutil](http://www.labix.org/python-dateutil) Python module |
| 20 | + * [vobject](http://gcalcli.googlecode.com/files/screenshot.png) Python module |
| 21 | + * A love for the command line! |
| 22 | + |
| 23 | +Features |
| 24 | +-------- |
| 25 | + |
| 26 | + * list your calendars |
| 27 | + * show an agenda using a specified start/end date and time |
| 28 | + * graphical calendar display with variable width |
| 29 | + * search for past and/or future calendar events |
| 30 | + * "quick add" new events to a specified calendar |
| 31 | + * import ics/vcal files to a specified calendar |
| 32 | + * run as a cron job and execute a command for reminders |
| 33 | + * work against specific calendars (by calendar type or calendar name regex) |
| 34 | + * config file support for specifying option defaults |
| 35 | + * colored output and unicode character support |
| 36 | + * easy within shell scripts, cron, screen, tmux, conky, etc |
| 37 | + |
| 38 | +Screenshots |
| 39 | +----------- |
| 40 | + |
| 41 | + |
| 42 | + |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +HowTo |
| 47 | +----- |
| 48 | + |
| 49 | +*Usage* |
| 50 | + |
| 51 | + gcalcli [options] command [command args] |
| 52 | + |
| 53 | + Options: |
| 54 | + |
| 55 | + --help this usage text |
| 56 | + |
| 57 | + --version version information |
| 58 | + |
| 59 | + --config <file> config file to read (default is '~/.gcalclirc') |
| 60 | + |
| 61 | + --user <username> google username |
| 62 | + |
| 63 | + --pw <password> password |
| 64 | + |
| 65 | + --https use HTTPS when communicating with Google |
| 66 | + |
| 67 | + --cals [all, 'calendars' to work with (default is all calendars) |
| 68 | + default, - default (your default main calendar) |
| 69 | + owner, - owner (your owned calendars) |
| 70 | + editor, - editor (editable calendar) |
| 71 | + contributor, - contributor (non-owner but able to edit) |
| 72 | + read, - read (read only calendars) |
| 73 | + freebusy] - freebusy (only free/busy info visible) |
| 74 | + |
| 75 | + --cal <name>[#color] 'calendar' to work with (default is all calendars) |
| 76 | + - you can specify a calendar by name or by substring |
| 77 | + which can match multiple calendars |
| 78 | + - you can use multiple '--cal' arguments on the |
| 79 | + command line |
| 80 | + - in the config file specify multiple calendars in |
| 81 | + quotes separated by commas as: |
| 82 | + cal: "foo", "bar", "my cal" |
| 83 | + - an optional color override can be specified per |
| 84 | + calendar using the ending hashtag: |
| 85 | + --cal "Eric Davis"#green --cal foo#red |
| 86 | + or via the config file: |
| 87 | + cal: "foo"#red, "bar"#yellow, "my cal"#green |
| 88 | + |
| 89 | + --24hr show all dates in 24 hour format |
| 90 | + |
| 91 | + --details show all event details (i.e. length, location, |
| 92 | + reminders, contents) |
| 93 | + |
| 94 | + --ignore-started ignore old or already started events |
| 95 | + - when used with the 'agenda' command, ignore events |
| 96 | + that have already started and are in-progress with |
| 97 | + respect to the specified [start] time |
| 98 | + - when used with the 'search' command, ignore events |
| 99 | + that have already occurred and only show future |
| 100 | + events |
| 101 | + |
| 102 | + --width the number of characters to use for each column in |
| 103 | + the 'calw' and 'calm' command outputs (default is 10) |
| 104 | + |
| 105 | + --mon week begins with Monday for 'calw' and 'calm' command |
| 106 | + outputs (default is Sunday) |
| 107 | + |
| 108 | + --nc don't use colors |
| 109 | + |
| 110 | + --cal-owner-color specify the colors used for the calendars and dates |
| 111 | + --cal-editor-color each of these argument requires a <color> argument |
| 112 | + --cal-contributor-color which must be one of [ default, black, brightblack, |
| 113 | + --cal-read-color red, brightred, green, brightgreen, yellow, |
| 114 | + --cal-freebusy-color brightyellow, blue, brightblue, magenta, |
| 115 | + --date-color brightmagenta, cyan, brightcyan, white, |
| 116 | + --border-color brightwhite ] |
| 117 | + |
| 118 | + Commands: |
| 119 | + |
| 120 | + list list all calendars |
| 121 | + |
| 122 | + search <text> search for events |
| 123 | + - only matches whole words |
| 124 | + |
| 125 | + agenda [start] [end] get an agenda for a time period |
| 126 | + - start time default is 12am today |
| 127 | + - end time default is 5 days from start |
| 128 | + - example time strings: |
| 129 | + '9/24/2007' |
| 130 | + 'Sep 24 2007 3:30pm' |
| 131 | + '2007-09-24T15:30' |
| 132 | + '2007-09-24T15:30-8:00' |
| 133 | + '20070924T15' |
| 134 | + '8am' |
| 135 | + |
| 136 | + calw <weeks> [start] get a week based agenda in a nice calendar format |
| 137 | + - weeks is the number of weeks to display |
| 138 | + - start time default is beginning of this week |
| 139 | + - note that all events for the week(s) are displayed |
| 140 | + |
| 141 | + calm [start] get a month agenda in a nice calendar format |
| 142 | + - start time default is the beginning of this month |
| 143 | + - note that all events for the month are displayed |
| 144 | + and only one month will be displayed |
| 145 | + |
| 146 | + quick <text> quick add an event to a calendar |
| 147 | + - if a --cal is not specified then the event is |
| 148 | + added to the default calendar |
| 149 | + - example: |
| 150 | + 'Dinner with Eric 7pm tomorrow' |
| 151 | + '5pm 10/31 Trick or Treat' |
| 152 | + |
| 153 | + import [file] import an ics/vcal file to a calendar |
| 154 | + - if a --cal is not specified then the event is |
| 155 | + added to the default calendar |
| 156 | + - if a file is not specified then the data is read |
| 157 | + from standard input |
| 158 | + |
| 159 | + remind <mins> <command> execute command if event occurs within <mins> |
| 160 | + minutes time ('%s' in <command> is replaced with |
| 161 | + event start time and title text) |
| 162 | + - <mins> default is 10 |
| 163 | + - default command: |
| 164 | + 'gxmessage -display :0 -center \ |
| 165 | + -title "Ding, Ding, Ding!" %s' |
| 166 | + |
| 167 | +*Login Information* |
| 168 | + |
| 169 | +You can provide gcalcli with your Google Calendar login information via one of |
| 170 | +the following: |
| 171 | + |
| 172 | + * on the command line using the --user and --pw options |
| 173 | + * the config file |
| 174 | + * or interactively when prompted |
| 175 | + |
| 176 | +In any case make sure you protect the information. |
| 177 | + |
| 178 | +*HTTP Proxy Support* |
| 179 | + |
| 180 | +gcalcli will automatically work with an HTTP Proxy simply by setting up some |
| 181 | +environment variables used by the gdata Python module: |
| 182 | + |
| 183 | + http_proxy |
| 184 | + https_proxy |
| 185 | + proxy-username or proxy_username |
| 186 | + proxy-password or proxy_password |
| 187 | + |
| 188 | +Note that these environment variables must be lowercase. |
| 189 | + |
| 190 | +*Config File* |
| 191 | + |
| 192 | +gcalcli is able to read default configuration information from a config file. |
| 193 | +This file is location, by default, at '~/.gcalclirc' and must be formatted as |
| 194 | +follows: |
| 195 | + |
| 196 | + [gcalcli] |
| 197 | + <config-option>: <value> |
| 198 | + <config-option>: <value> |
| 199 | + ... |
| 200 | + |
| 201 | +The available config items are the same as those that can be specified on the |
| 202 | +command line. Note that any value specified on the command line overrides the |
| 203 | +config file. |
| 204 | + |
| 205 | + user: <username> |
| 206 | + pw: <password> |
| 207 | + cals: <type> |
| 208 | + cal: <name>[#color], <name>[#color], ... |
| 209 | + 24hr: <true|false> |
| 210 | + details: <true|false> |
| 211 | + ignore-started: <true|false> |
| 212 | + width: <width> |
| 213 | + mon: <true|false> |
| 214 | + nd: <true|false> |
| 215 | + cal-owner-color: <color> |
| 216 | + cal-editor-color: <color> |
| 217 | + cal-contributor-color: <color> |
| 218 | + cal-read-color: <color> |
| 219 | + cal-freebusy-color: <color> |
| 220 | + date-color: <color> |
| 221 | + border-color: <color> |
| 222 | + |
| 223 | +*Event Popup Reminders Using Cron* |
| 224 | + |
| 225 | +Run gcalcli using cron and generate xmessage-like popups for reminders. |
| 226 | + |
| 227 | + % crontab -e |
| 228 | + |
| 229 | +Then add the following line: |
| 230 | + |
| 231 | + */10 * * * * gcalcli remind |
| 232 | + |
| 233 | +*Agenda On Your Root Desktop* |
| 234 | + |
| 235 | +Put your agenda on your desktop using Conky. Add the following to your |
| 236 | +.conkyrc: |
| 237 | + |
| 238 | + ${execi 300 gcalcli --nc agenda} |
| 239 | + |
| 240 | +To also get a graphical calendar that shows the next three weeks add: |
| 241 | + |
| 242 | + ${execi 300 gcalcli --nc --cals=owner calw 3} |
| 243 | + |
| 244 | +*Agenda Integration With GNU Screen* |
| 245 | + |
| 246 | +Put your next event in your 'screen' hardstatus line. First add a cron job |
| 247 | +that will dump you agenda to a text file: |
| 248 | + |
| 249 | + % crontab -e |
| 250 | + |
| 251 | +Then add the following line: |
| 252 | + |
| 253 | + */5 * * * * gcalcli --nc --ignore-started agenda "`date`" > /tmp/gcalcli_agenda.txt |
| 254 | + |
| 255 | +Next create a simple shell script that will extract the first agenda line. |
| 256 | +Let's call this script 'screen_agenda': |
| 257 | + |
| 258 | + #!/bin/bash |
| 259 | + head -2 /tmp/gcalcli_agenda.txt | tail -1 |
| 260 | + |
| 261 | +Next configure screen's hardstatus line to gather data from a backtick command. |
| 262 | +Of course your hardstatus line is most likely very different than this (Mine |
| 263 | +is!): |
| 264 | + |
| 265 | + backtick 1 60 60 screen_agenda |
| 266 | + hardstatus "[ %1` ]" |
| 267 | + |
| 268 | +*Agenda Integration With Tmux* |
| 269 | + |
| 270 | +Put your next event in the left of your 'tmux' status line. Add the following |
| 271 | +to your tmux.conf file: |
| 272 | + |
| 273 | + set-option -g status-interval 60 |
| 274 | + set-option -g status-left "#[fg=blue,bright]#(gcalcli | head -2 | tail -1)#[default]" |
| 275 | + |
0 commit comments