Calendar Assistant

A command-line tool to help you manage your Google Calendar.

easily join the videoconference for your current meeting
see yours and others' "availability" suitable for an email response
set up all-day events to let people know where you are (for frequent travelers)
see views on your calendar events for a date or time range
book (and re-book) one-on-ones and other meetings automatically

Features
- Pretty Display in Your Terminal
- Human-Friendly Date and Time Specification
- Human-Friendly Duration Specification
- Filter Events by property
- Preferences
Setup
- Installation
- Set up a Google Cloud Project with API access
- Authorize access to your Google Calendar
Commands
- join: Join a video call attached to a meeting
- availability: Find people's availability for meetings
- location-set: Tell people where you are in the world
- location: View where you're going to be in the world
- show: View your calendar events
- lint: Calendar events that require action
- config: View your configuration parameters
- interactive: Interactive Console
Development
- Running Tests Locally
- Continuous Integration
- Code Quality
- Generate README
References
License

Features

Pretty Display in Your Terminal

Events are nicely formatted, with faint strikeouts for events you've declined, and some additional attributes listed when present (e.g., "awaiting", "self", "not-busy", "1:1" ...)

Human-Friendly Date and Time Specification

All dates and times are interpreted by Chronic and so can be fuzzy terms like "tomorrow", "tuesday", "next thursday", and "two days from now" as well as specific dates and times.

For a date range or a datetime range, split the start and end with .. or ... (with or without spaces) like:

"tomorrow ... three days from now"
"2018-09-24..2018-09-27".

Also note that every command will adopt an intelligent default, which is generally "today" or "now".

Human-Friendly Duration Specification

Some duration-related preferences are interpreted by ChronicDuration and so can be terms like "10m", "30 minutes", "four hours", etc.

Filter Events by property

Commands that return events like show, join, availability, location or lint can be filtered using the option --must-be or --must-not-be. These options expect a comma separated list of one of the following properties.

Response
- accepted
- declined
- awaiting
- tentative
Temporal
- all_day
- past
- current
- future
Visibility
- private
- public
- explicitly_visible
- visible_guestlist
Attributes
- location_event
- self
- one_on_one
- busy
- commitment
- recurring
- abandoned
- anyone_can_add_self
- attendees_omitted
- end_time_unspecified
- guests_can_invite_others
- guests_can_modify
- guests_can_see_other_guests
- private_copy
- locked
- needs_action

Preferences

All tokens and preferences will be stored in ~/.calendar-assistant which is in TOML format for easy editing.

The location of .calendar-assistant defaults to the user's home directory. This location may be overridden by setting the environment variable CA_HOME

Nickname

Some commands, like location-set, will refer to you by nickname if you configure it (the alternative might be to not specify your name, or use your email id).

Set nickname to a string that would uniquely and briefly identify you to others, like "Mike D" or "JK".

Location Emoji

There is a [settings] key called location-icon that may be set to an emoji denoting a location event. By default CalendarAssistant will use "🌎", but you can change this.

Command-Specific Preferences

If there are user preferences you'd like to set for just a single command (e.g., making public location events created via location-set), you can create a nested section in your TOML settings file, like so:

[settings]
visibility = "default"
nickname = "uniquely-me"

[settings.location_set]
visibility = "public"
calendars = ["teamcalendar@group.calendar.google.com","teamcalendar2@group.calendar.google.com"]

Setup

Installation

Install the gem: gem install calendar-assistant.

Set up a Google Cloud Project with API access

Usage:
  calendar-assistant setup

Options:
  -h, -?, [--help], [--no-help]          
          [--debug], [--no-debug]        # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]  # Enable Text Formatting
                                         # Default: true

Description:
  This command will walk you through setting up a Google Cloud Project, enabling the Google Calendar API, and saving
  the credentials necessary to access the API on behalf of users.

  If you already have downloaded client credentials, you don't need to run this command. Instead, rename the downloaded
  JSON file to `/home/user/.calendar-assistant.client`

Authorize access to your Google Calendar

Usage:
  calendar-assistant authorize PROFILE_NAME

Options:
  -h, -?, [--help], [--no-help]          
          [--debug], [--no-debug]        # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]  # Enable Text Formatting
                                         # Default: true

Description:
  Create and authorize a named profile (e.g., "work", "home", "flastname@company.tld") to access your calendar.

  When setting up a profile, you'll be asked to visit a URL to authenticate, grant authorization, and generate and
  persist an access token.

  In order for this to work, you'll need to have set up your API client credentials. Run `calendar-assistant help
  setup` for instructions.

Commands

Commands:
  calendar-assistant authorize PROFILE_NAME                       # create (or validate) a profile named NAME with ca...
  calendar-assistant availability [DATE | DATERANGE | TIMERANGE]  # Show your availability for a date or range of dat...
  calendar-assistant config                                       # Dump your configuration parameters (merge of defa...
  calendar-assistant help [COMMAND]                               # Describe available commands or one specific command
  calendar-assistant interactive                                  # interactive console for calendar assistant
  calendar-assistant join [TIME]                                  # Open the URL for a video call attached to your me...
  calendar-assistant lint [DATE | DATERANGE | TIMERANGE]          # Lint your events for a date or range of dates (de...
  calendar-assistant location [DATE | DATERANGE]                  # Show your location for a date or range of dates (...
  calendar-assistant location-set LOCATION [DATE | DATERANGE]     # Set your location to LOCATION for a date or range...
  calendar-assistant setup                                        # Link your local calendar-assistant installation t...
  calendar-assistant show [DATE | DATERANGE | TIMERANGE]          # Show your events for a date or range of dates (de...
  calendar-assistant version                                      # Display the version of calendar-assistant

Options:
  -h, -?, [--help], [--no-help]          
          [--debug], [--no-debug]        # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]  # Enable Text Formatting
                                         # Default: true

`join`: Join a video call attached to a meeting

Usage:
  calendar-assistant join [TIME]

Options:
          [--join], [--no-join]                    # launch a browser to join the video call URL
                                                   # Default: true
  -p, [--profile=PROFILE]                          # the profile you'd like to use (if different from default)
  -l, [--local-store=FILENAME]                     # Load events from a local file instead of Google Calendar
  -b, [--must-be=PROPERTY1[,PROPERTY2[,...]]]      # Event properties that must be true (see README)
  -n, [--must-not-be=PROPERTY1[,PROPERTY2[,...]]]  # Event properties that must be false (see README)
  -h, -?, [--help], [--no-help]                    
          [--debug], [--no-debug]                  # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]            # Enable Text Formatting
                                                   # Default: true

Open the URL for a video call attached to your meeting at time TIME (default 'now')

Some examples:

$ calendar-assistant join
me@example.com

2018-10-01  11:30 - 12:00 | Facilitate customized web-readiness  (1:1, recurring)

https://pivotal.zoom.us/j/ABC90210 # ... and opens the videoconference URL


$ calendar-assistant join work 11:30 --no-join
me@example.com

2018-10-01  11:30 - 12:00 | Facilitate customized web-readiness  (1:1, recurring)

https://pivotal.zoom.us/j/ABC90210 # ... and does not open the URL

`availability`: Find people's availability for meetings

This is useful for emailing people your availability. It only considers accepted meetings when determining busy/free.

Usage:
  calendar-assistant availability [DATE | DATERANGE | TIMERANGE]

Options:
  -l, [--meeting-length=LENGTH]                               # [default 30m] find chunks of available time at least as long as LENGTH (which is a ChronicDuration string like '30m' or '2h')
  -s, [--start-of-day=TIME]                                   # [default 9am] find chunks of available time after TIME (which is a BusinessTime string like '9am' or '14:30')
  -e, [--end-of-day=TIME]                                     # [default 6pm] find chunks of available time before TIME (which is a BusinessTime string like '9am' or '14:30')
  -a, --attendees, [--calendars=CALENDAR1[,CALENDAR2[,...]]]  # [default 'me'] people (email IDs) to whom this command will be applied
  -p, [--profile=PROFILE]                                     # the profile you'd like to use (if different from default)
  -l, [--local-store=FILENAME]                                # Load events from a local file instead of Google Calendar
  -b, [--must-be=PROPERTY1[,PROPERTY2[,...]]]                 # Event properties that must be true (see README)
  -n, [--must-not-be=PROPERTY1[,PROPERTY2[,...]]]             # Event properties that must be false (see README)
  -h, -?, [--help], [--no-help]                               
          [--debug], [--no-debug]                             # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]                       # Enable Text Formatting
                                                              # Default: true

Show your availability for a date or range of dates (default 'today')

For example: show me my available time over a chunk of time:

$ calendar-assistant avail 2018-11-05..2018-11-07
me@example.com
- looking for blocks at least 30 mins long
- between 9am and 6pm in America/New_York

Availability on Monday, November 5:

 •  9:00am - 10:00am EST (1h)
 •  1:30pm -  2:30pm EST (1h)
 •  3:30pm -  5:00pm EST (1h 30m)
 •  5:30pm -  6:00pm EST (30m)

Availability on Tuesday, November 6:

 •  9:00am -  4:30pm EST (7h 30m)
 •  4:50pm -  6:00pm EST (1h 10m)

Availability on Wednesday, November 7:

 •  9:00am -  2:30pm EST (5h 30m)
 •  5:30pm -  6:00pm EST (30m)

You can also find times when multiple people are available:

$ calendar-assistant avail 2018-11-05..2018-11-07 -a me@example.com,other@example.com
me@example.com, other@example.com
- looking for blocks at least 30 mins long
- between 9am and 6pm in America/New_York
- between 9am and 6pm in America/Los_Angeles

Availability on Monday, November 5:

 •  4:30pm -  5:00pm EST /  1:30pm -  2:00pm PST (30m)

Availability on Tuesday, November 6:

 • 12:00pm -  4:30pm EST /  9:00am -  1:30pm PST (4h 30m)
 •  4:50pm -  6:00pm EST /  1:50pm -  3:00pm PST (1h 10m)

Availability on Wednesday, November 7:

 • 12:00pm -  2:30pm EST /  9:00am - 11:30am PST (2h 30m)

You can also set start and end times for the search, which is useful when looking for overlap with another time zone:

$ calendar-assistant avail 2018-11-05..2018-11-07 -s 12pm -e 7pm
me@example.com
- looking for blocks at least 30 mins long
- between 12pm and 7pm in America/New_York

Availability on Monday, November 5:

 •  1:30pm -  2:30pm EST (1h)
 •  3:30pm -  5:00pm EST (1h 30m)
 •  5:30pm -  7:00pm EST (1h 30m)

Availability on Tuesday, November 6:

 • 12:00pm -  4:30pm EST (4h 30m)
 •  4:50pm -  7:00pm EST (2h 10m)

Availability on Wednesday, November 7:

 • 12:00pm -  2:30pm EST (2h 30m)
 •  5:30pm -  7:00pm EST (1h 30m)

`location-set`: Tell people where you are in the world

Declare your location as an all-day non-busy event:

Usage:
  calendar-assistant location-set LOCATION [DATE | DATERANGE]

Options:
          [--force]                                           # will manage location across multiple calendars whether a nickname is set or not
          [--visibility=VISIBILITY]                           # [default is 'default'] Set the visibility of the event. Values are 'public', 'private', 'default'.
  -p, [--profile=PROFILE]                                     # the profile you'd like to use (if different from default)
  -l, [--local-store=FILENAME]                                # Load events from a local file instead of Google Calendar
  -b, [--must-be=PROPERTY1[,PROPERTY2[,...]]]                 # Event properties that must be true (see README)
  -n, [--must-not-be=PROPERTY1[,PROPERTY2[,...]]]             # Event properties that must be false (see README)
  -a, --attendees, [--calendars=CALENDAR1[,CALENDAR2[,...]]]  # [default 'me'] people (email IDs) to whom this command will be applied
  -h, -?, [--help], [--no-help]                               
          [--debug], [--no-debug]                             # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]                       # Enable Text Formatting
                                                              # Default: true

Set your location to LOCATION for a date or range of dates (default 'today')

Note that you can only be in one place at a time, so existing location events may be modified or deleted when new overlapping events are created.

Some examples:

# create an event titled `🗺 WFH` for today
$ calendar-assistant location set -p home WFH
Created:
2018-09-03                | 🗺  WFH (not-busy, self)

# create an event titled `🗺 OOO` for tomorrow
$ calendar-assistant location-set OOO tomorrow
Created:
2018-09-04                | 🗺  OOO (not-busy, self)

# create an event titled `🗺 Spring One` on the days of that conference
$ calendar-assistant location-set "Spring One" 2018-09-24...2018-09-27
Created:
2018-09-24 - 2018-09-27   | 🗺  Spring One (not-busy, self)

# create a vacation event for next week
$ calendar-assistant location-set "Vacation!" "next monday ... next week friday"
Created:
2018-09-10 - 2018-09-14   | 🗺  Vacation! (not-busy, self)

`location`: View where you're going to be in the world

Usage:
  calendar-assistant location [DATE | DATERANGE]

Options:
  -p, [--profile=PROFILE]                          # the profile you'd like to use (if different from default)
  -l, [--local-store=FILENAME]                     # Load events from a local file instead of Google Calendar
  -b, [--must-be=PROPERTY1[,PROPERTY2[,...]]]      # Event properties that must be true (see README)
  -n, [--must-not-be=PROPERTY1[,PROPERTY2[,...]]]  # Event properties that must be false (see README)
  -h, -?, [--help], [--no-help]                    
          [--debug], [--no-debug]                  # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]            # Enable Text Formatting
                                                   # Default: true

Show your location for a date or range of dates (default 'today')

For example:

$ calendar-assistant location "2018-09-24...2018-09-28"
me@example.com (all times in America/New_York)

2018-09-24 - 2018-09-28   | 🌎 Iron Hills (not-busy)
2018-09-28                | 🌎 Country Round (not-busy)

`show`: View your calendar events

Usage:
  calendar-assistant show [DATE | DATERANGE | TIMERANGE]

Options:
  -c, [--commitments], [--no-commitments]                     # only show events that you've accepted with another person
  -p, [--profile=PROFILE]                                     # the profile you'd like to use (if different from default)
  -l, [--local-store=FILENAME]                                # Load events from a local file instead of Google Calendar
  -a, --attendees, [--calendars=CALENDAR1[,CALENDAR2[,...]]]  # [default 'me'] people (email IDs) to whom this command will be applied
  -b, [--must-be=PROPERTY1[,PROPERTY2[,...]]]                 # Event properties that must be true (see README)
  -n, [--must-not-be=PROPERTY1[,PROPERTY2[,...]]]             # Event properties that must be false (see README)
  -h, -?, [--help], [--no-help]                               
          [--debug], [--no-debug]                             # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]                       # Enable Text Formatting
                                                              # Default: true

Show your events for a date or range of dates (default 'today')

For example: display all events scheduled for tomorrow:

$ calendar-assistant show 2018-10-01
me@example.com (all times in America/New_York)

2018-10-01  03:30 - 05:00 | Facilitate 24/365 web services
2018-10-01  07:30 - 08:30 | Reintermediate magnetic communities
2018-10-01  07:30 - 08:30 | Revolutionize bricks-and-clicks synergies
2018-10-01  10:30 - 10:55 | Whiteboard clicks-and-mortar metrics (1:1, recurring)
2018-10-01  11:00 - 11:30 | Architect holistic models (recurring)
2018-10-01  11:30 - 12:00 | Reinvent bleeding-edge e-services (1:1, recurring)
2018-10-01  11:50 - 12:00 | Synergize e-business systems (awaiting)
2018-10-01  12:00 - 12:30 | Reinvent e-business e-tailers (self)
2018-10-01  12:15 - 12:30 | Maximize clicks-and-mortar convergence
2018-10-01  12:30 - 13:30 | Disintermediate end-to-end bandwidth
2018-10-01  12:30 - 13:30 | Iterate innovative networks (awaiting, recurring)
2018-10-01  13:30 - 14:50 | Engage holistic users (self)
2018-10-01  13:30 - 14:30 | Enable e-business e-services
2018-10-01  15:00 - 15:30 | Innovate impactful technologies (1:1)
2018-10-01  16:00 - 17:00 | Iterate dynamic networks (1:1, recurring)
2018-10-01  16:45 - 17:00 | Deploy robust content (recurring)
2018-10-01  17:00 - 17:30 | Synthesize viral methodologies (recurring)
2018-10-01  17:30 - 17:55 | Scale collaborative methodologies (1:1, recurring)
2018-10-01  18:00 - 20:30 | Seize rich experiences
2018-10-01  18:30 - 19:00 | Engineer one-to-one e-business
2018-10-01  19:00 - 19:30 | Recontextualize collaborative content (awaiting)
2018-10-01                | 🌎 Grey Mountains (not-busy)

Display only the commitments I have to other people using the -c option:

$ calendar-assistant show -c 2018-10-01
me@example.com (all times in America/New_York)

2018-10-01  10:30 - 10:55 | Whiteboard clicks-and-mortar metrics (1:1, recurring)
2018-10-01  11:00 - 11:30 | Architect holistic models (recurring)
2018-10-01  11:30 - 12:00 | Reinvent bleeding-edge e-services (1:1, recurring)
2018-10-01  11:50 - 12:00 | Synergize e-business systems (awaiting)
2018-10-01  12:30 - 13:30 | Iterate innovative networks (awaiting, recurring)
2018-10-01  15:00 - 15:30 | Innovate impactful technologies (1:1)
2018-10-01  16:00 - 17:00 | Iterate dynamic networks (1:1, recurring)
2018-10-01  16:45 - 17:00 | Deploy robust content (recurring)
2018-10-01  17:00 - 17:30 | Synthesize viral methodologies (recurring)
2018-10-01  17:30 - 17:55 | Scale collaborative methodologies (1:1, recurring)
2018-10-01  19:00 - 19:30 | Recontextualize collaborative content (awaiting)

`lint`: Calendar events that require action

Usage:
  calendar-assistant lint [DATE | DATERANGE | TIMERANGE]

Options:
  -p, [--profile=PROFILE]                                     # the profile you'd like to use (if different from default)
  -l, [--local-store=FILENAME]                                # Load events from a local file instead of Google Calendar
  -a, --attendees, [--calendars=CALENDAR1[,CALENDAR2[,...]]]  # [default 'me'] people (email IDs) to whom this command will be applied
  -b, [--must-be=PROPERTY1[,PROPERTY2[,...]]]                 # Event properties that must be true (see README)
  -n, [--must-not-be=PROPERTY1[,PROPERTY2[,...]]]             # Event properties that must be false (see README)
  -h, -?, [--help], [--no-help]                               
          [--debug], [--no-debug]                             # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]                       # Enable Text Formatting
                                                              # Default: true

Lint your events for a date or range of dates (default 'today')

For example: display all events that require action scheduled for tomorrow:

$ calendar-assistant lint 2018-10-01
me@example.com
- looking for events that need attention
- all times in America/New_York

2018-10-01  11:50 - 12:00 | Synergize e-business systems (awaiting)
                                    attendees: 👍 three@example.com, 🤷 four@example.com
2018-10-01  12:30 - 13:30 | Iterate innovative networks (awaiting, recurring)
                                    attendees: 👍 three@example.com, 🤷 four@example.com
2018-10-01  19:00 - 19:30 | Recontextualize collaborative content (awaiting)
                                    attendees: 👍 three@example.com, 🤷 four@example.com

`config`: View your configuration parameters

Calendar Assistant has intelligent defaults, which can be overridden in the TOML file ~/.calendar-assistant, and further overridden via command-line parameters. Sometimes it's nice to be able to see what defaults Calendar Assistant is using:

Usage:
  calendar-assistant config

Options:
  -h, -?, [--help], [--no-help]          
          [--debug], [--no-debug]        # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]  # Enable Text Formatting
                                         # Default: true

Dump your configuration parameters (merge of defaults and overrides from /home/user/.calendar-assistant)

The output is TOML, which is suitable for dumping into ~/.calendar-assistant and editing.

$ calendar-assistant config
[settings]
end-of-day = "6pm"
location-icon = "🌎"
meeting-length = "30m"
start-of-day = "9am"

`interactive`: Interactive Console

Usage:
  calendar-assistant interactive

Options:
  -h, -?, [--help], [--no-help]          
          [--debug], [--no-debug]        # how dare you suggest there are bugs
  -f, [--formatting], [--no-formatting]  # Enable Text Formatting
                                         # Default: true

interactive console for calendar assistant

For example, check the version of calendar assistant

calendar-assistant> version
0.0.0

Development

Running Tests Locally

gem install bundler
bundle install

bundle exec rake spec     # Run all tests except feature tests
bundle exec rake features # Run only feature tests
bundle exec rake          # Default task runs both feature and non feature tests

Note: Feature tests are excluded by default in .rspec

Continuous Integration

CI is running in Github Actions.

Code Quality

We're running Code Climate to monitor code quality and test coverage.

Generate README

Note that doing this requires npm to be installed
Generation will use a fixture file rather than connecting to a remote calendar. Fixtures can be updated/regenerated in generate-fixtures script

./generate-readme

References

Google Calendar Concepts: https://developers.google.com/calendar/concepts/

Google Calendar API Reference: https://developers.google.com/calendar/v3/reference/

Google Calendar Ruby Client Docs: https://www.rubydoc.info/github/google/google-api-ruby-client/Google/Apis/CalendarV3

License

See files LICENSE and NOTICE in this repository.