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
  • 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
• Development
  • Running Tests Locally
  • Continuous Integration
  • Code Quality
  • Generate README
• References
• License

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" ...)

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".

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

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

There is a [settings] key called location-icons that may be set to an array denoting all emoji that indicate a location event. The first icon in the array will be used as the default. The default emoji included are ["🗺 ", "🌎"] with the map icon first

Install the gem: gem install calendar-assistant.

Usage:
  calendar-assistant setup

Options:
  -h, -?, [--help], [--no-help]              
          [--debug], [--no-debug]            # how dare you suggest there are bugs
          [--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`

Usage:
  calendar-assistant authorize PROFILE_NAME

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

Description:
  Create and authorize a named profile (e.g., "work", "home", "[email protected]") 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:
  calendar-assistant authorize PROFILE_NAME                       # create (or validate) a profil...
  calendar-assistant availability [DATE | DATERANGE | TIMERANGE]  # Show your availability for a ...
  calendar-assistant config                                       # Dump your configuration param...
  calendar-assistant help [COMMAND]                               # Describe available commands o...
  calendar-assistant join [TIME]                                  # Open the URL for a video call...
  calendar-assistant lint [DATE | DATERANGE | TIMERANGE]          # Lint your events for a date o...
  calendar-assistant location [DATE | DATERANGE]                  # Show your location for a date...
  calendar-assistant location-set LOCATION [DATE | DATERANGE]     # Set your location to LOCATION...
  calendar-assistant setup                                        # Link your local calendar-assi...
  calendar-assistant show [DATE | DATERANGE | TIMERANGE]          # Show your events for a date o...
  calendar-assistant version                                      # Display the version of calend...

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

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)
          [--local-store=FILENAME]           # Load events from a local file instead of Google Calendar
          [--must-be=one two three]          # array of event predicates that must be true
          [--must-not-be=one two three]      # array of event predicates that must not be true
  -h, -?, [--help], [--no-help]              
          [--debug], [--no-debug]            # how dare you suggest there are bugs
          [--formatting], [--no-formatting]  # Enable Text Formatting
                                             # Default: true

Description:
  This command may utilize --must-be or --must-not-be. Both options may include a space separated array
  of the following predicates accepted declined awaiting tentative all_day past current future
  private public explicitly_visible visible_guestlist 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

Some examples:

$ calendar-assistant join
[email protected]

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
[email protected]

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

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=ATTENDEE1[,ATTENDEE2[,...]]]  # [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)
          [--local-store=FILENAME]               # Load events from a local file instead of Google Calendar
          [--must-be=one two three]              # array of event predicates that must be true
          [--must-not-be=one two three]          # array of event predicates that must not be true
  -h, -?, [--help], [--no-help]                  
          [--debug], [--no-debug]                # how dare you suggest there are bugs
          [--formatting], [--no-formatting]      # Enable Text Formatting
                                                 # Default: true

Description:
  This command may utilize --must-be or --must-not-be. Both options may include a space separated array
  of the following predicates accepted declined awaiting tentative all_day past current future
  private public explicitly_visible visible_guestlist 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

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

$ calendar-assistant avail 2018-11-05..2018-11-07
[email protected]
- 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 [email protected],[email protected]
[email protected], [email protected]
- 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
[email protected]
- 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)

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

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

Options:
  -p, [--profile=PROFILE]                    # the profile you'd like to use (if different from default)
          [--local-store=FILENAME]           # Load events from a local file instead of Google Calendar
          [--must-be=one two three]          # array of event predicates that must be true
          [--must-not-be=one two three]      # array of event predicates that must not be true
  -h, -?, [--help], [--no-help]              
          [--debug], [--no-debug]            # how dare you suggest there are bugs
          [--formatting], [--no-formatting]  # Enable Text Formatting
                                             # Default: true

Description:
  This command may utilize --must-be or --must-not-be. Both options may include a space separated array
  of the following predicates accepted declined awaiting tentative all_day past current future
  private public explicitly_visible visible_guestlist 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

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)

Usage:
  calendar-assistant location [DATE | DATERANGE]

Options:
  -p, [--profile=PROFILE]                    # the profile you'd like to use (if different from default)
          [--local-store=FILENAME]           # Load events from a local file instead of Google Calendar
          [--must-be=one two three]          # array of event predicates that must be true
          [--must-not-be=one two three]      # array of event predicates that must not be true
  -h, -?, [--help], [--no-help]              
          [--debug], [--no-debug]            # how dare you suggest there are bugs
          [--formatting], [--no-formatting]  # Enable Text Formatting
                                             # Default: true

Description:
  This command may utilize --must-be or --must-not-be. Both options may include a space separated array
  of the following predicates accepted declined awaiting tentative all_day past current future
  private public explicitly_visible visible_guestlist 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

For example:

$ calendar-assistant location "2018-09-24...2018-09-28"
[email protected] (all times in America/New_York)

2018-09-24 - 2018-09-28   | 🗺  Gondolin (not-busy)
2018-09-28                | 🗺  Rivendell (not-busy)

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)
          [--local-store=FILENAME]               # Load events from a local file instead of Google Calendar
  -a, [--attendees=ATTENDEE1[,ATTENDEE2[,...]]]  # [default 'me'] people (email IDs) to whom this command will be applied
          [--must-be=one two three]              # array of event predicates that must be true
          [--must-not-be=one two three]          # array of event predicates that must not be true
  -h, -?, [--help], [--no-help]                  
          [--debug], [--no-debug]                # how dare you suggest there are bugs
          [--formatting], [--no-formatting]      # Enable Text Formatting
                                                 # Default: true

Description:
  This command may utilize --must-be or --must-not-be. Both options may include a space separated array
  of the following predicates accepted declined awaiting tentative all_day past current future
  private public explicitly_visible visible_guestlist 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

For example: display all events scheduled for tomorrow:

$ calendar-assistant show 2018-10-01
[email protected] (all times in America/New_York)

2018-10-01  03:30 - 05:00 | Repurpose end-to-end convergence
2018-10-01  07:30 - 08:30 | Iterate clicks-and-mortar vortals
2018-10-01  07:30 - 08:30 | Grow viral portals
2018-10-01  10:30 - 10:55 | Enable rich roi (1:1, recurring)
2018-10-01  11:00 - 11:30 | Leverage rich e-services (recurring)
2018-10-01  11:30 - 12:00 | Grow leading-edge communities (1:1, recurring)
2018-10-01  11:50 - 12:00 | Cultivate revolutionary experiences (awaiting)
2018-10-01  12:00 - 12:30 | Incentivize ubiquitous mindshare (self)
2018-10-01  12:15 - 12:30 | Disintermediate next-generation niches
2018-10-01  12:30 - 13:30 | Drive viral communities
2018-10-01  12:30 - 13:30 | Synergize integrated supply-chains (awaiting, recurring)
2018-10-01  13:30 - 14:50 | Transform revolutionary users (self)
2018-10-01  13:30 - 14:30 | Enable interactive networks
2018-10-01  15:00 - 15:30 | Evolve global applications (1:1)
2018-10-01  16:00 - 17:00 | Implement b2c architectures (1:1, recurring)
2018-10-01  16:45 - 17:00 | Enable rich niches (recurring)
2018-10-01  17:00 - 17:30 | Implement frictionless e-markets (recurring)
2018-10-01  17:30 - 17:55 | Streamline world-class portals (1:1, recurring)
2018-10-01  18:00 - 20:30 | Recontextualize rich paradigms
2018-10-01  18:30 - 19:00 | Synergize dot-com functionalities
2018-10-01  19:00 - 19:30 | Revolutionize transparent e-markets (awaiting)
2018-10-01                | 🗺  Country Round (not-busy)

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

$ calendar-assistant show -c 2018-10-01
[email protected] (all times in America/New_York)

2018-10-01  10:30 - 10:55 | Enable rich roi (1:1, recurring)
2018-10-01  11:00 - 11:30 | Leverage rich e-services (recurring)
2018-10-01  11:30 - 12:00 | Grow leading-edge communities (1:1, recurring)
2018-10-01  11:50 - 12:00 | Cultivate revolutionary experiences (awaiting)
2018-10-01  12:30 - 13:30 | Synergize integrated supply-chains (awaiting, recurring)
2018-10-01  15:00 - 15:30 | Evolve global applications (1:1)
2018-10-01  16:00 - 17:00 | Implement b2c architectures (1:1, recurring)
2018-10-01  16:45 - 17:00 | Enable rich niches (recurring)
2018-10-01  17:00 - 17:30 | Implement frictionless e-markets (recurring)
2018-10-01  17:30 - 17:55 | Streamline world-class portals (1:1, recurring)
2018-10-01  19:00 - 19:30 | Revolutionize transparent e-markets (awaiting)

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

Options:
  -p, [--profile=PROFILE]                        # the profile you'd like to use (if different from default)
          [--local-store=FILENAME]               # Load events from a local file instead of Google Calendar
  -a, [--attendees=ATTENDEE1[,ATTENDEE2[,...]]]  # [default 'me'] people (email IDs) to whom this command will be applied
          [--must-be=one two three]              # array of event predicates that must be true
          [--must-not-be=one two three]          # array of event predicates that must not be true
  -h, -?, [--help], [--no-help]                  
          [--debug], [--no-debug]                # how dare you suggest there are bugs
          [--formatting], [--no-formatting]      # Enable Text Formatting
                                                 # Default: true

Description:
  This command may utilize --must-be or --must-not-be. Both options may include a space separated array
  of the following predicates accepted declined awaiting tentative all_day past current future
  private public explicitly_visible visible_guestlist 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

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

$ calendar-assistant lint 2018-10-01
[email protected]
- looking for events that need attention
- all times in America/New_York

2018-10-01  11:50 - 12:00 | Cultivate revolutionary experiences (awaiting)
                                    attendees: 👍 [email protected], 🤷 [email protected]
2018-10-01  12:30 - 13:30 | Synergize integrated supply-chains (awaiting, recurring)
                                    attendees: 👍 [email protected], 🤷 [email protected]
2018-10-01  19:00 - 19:30 | Revolutionize transparent e-markets (awaiting)
                                    attendees: 👍 [email protected], 🤷 [email protected]

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
          [--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-icons = ["🌎","🗺 "]
meeting-length = "30m"
profile = "work"
start-of-day = "9am"

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

CI is running in a Concourse pipeline at https://ci.nokogiri.org.

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

• 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

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

See files LICENSE and NOTICE in this repository.