flycal-cli

A command-line tool to access and search Google Calendar events. Connect your Google account, choose a default calendar, and search events with flexible date ranges and text filters.

• Ruby 3.1 or later
• A Google Cloud project with Calendar API enabled

gem install flycal-cli

Or add to your Gemfile:

gem "flycal-cli"

Then run bundle install.

Before using flycal, you need OAuth credentials from Google Cloud Console:

1. Go to Google Cloud Console - Credentials
2. Create a project or select an existing one
3. Enable the Google Calendar API (APIs & Services → Library → search for "Google Calendar API")
4. Create Desktop app credentials (OAuth 2.0 Client IDs)
5. Add this URI as an authorized redirect:

   http://127.0.0.1:9292/oauth2callback
   

6. Download the JSON file and save it as ~/.flycal/credentials.json

Connect to your Google account. Opens a browser for OAuth authentication when not yet connected.

flycal login

If already connected, the command reports the current status and suggests running flycal calendars to set the default calendar.

Disconnect from your Google account and remove stored tokens.

flycal logout

List available calendars and set the default one. Uses an interactive scrollable menu (arrow keys to navigate, type to filter).

flycal calendars

The default calendar is used by the search command when no calendar is specified.

Search for events in your calendar(s). Supports flexible date ranges and text filtering.

flycal search
flycal search --in 30days --description placeholder
flycal search -f 2025-03-01 -t 2025-03-31 -c "Work"
flycal search -i 2months -d placeholder

Options:

• --from / -f — Start date/time. Default: midnight of current day. Format: 2025-01-01 or 2025-01-01T09:00
• --to / -t — End date/time. Default: 23:59 of the 30th day from today. Format: same as --from
• --in / -i — Duration from --from, overrides --to. Format: 30days, 48hours, 2months, 1year (no space). With space use quotes: --in "30 days"
• --calendar / -c — Calendar name or ID. Default: calendar set via flycal calendars
• --description / -d — Filter events by text. Matches events where the string appears in title or description (case-insensitive, contains)

Time range behavior:

• If neither --from nor --to is given: searches from today at midnight to 23:59 of the 30th day from today
• If --in is given: --to is ignored; the end time is computed from --from plus the duration
• Examples: --in 30days, --in 48hours, --in 1months, --in 1year

Output:

Each event is printed as: Calendar | Start | End | Title

The summary shows:

• From and To dates used
• Number of events found
• Total time occupied (hours, minutes, and working days based on 8-hour days)

For time frames longer than 7 days, a weekly breakdown is added (week number, start/end dates, hours, working days per week). For time frames longer than 30 days, a monthly breakdown is shown instead (month number, month name, hours, working days per month).

Data is stored in ~/.flycal/:

1. Create an account at rubygems.org if needed
2. Update flycal-cli.gemspec with your author, email, and homepage
3. Build and push:

gem build flycal-cli.gemspec
gem push flycal-cli-0.1.0.gem

1. Update the version in lib/flycal_cli/version.rb
2. Build and push:

gem build flycal-cli.gemspec
gem push flycal-cli-X.Y.Z.gem

3. Optionally tag and push:

git tag vX.Y.Z
git push origin vX.Y.Z

With bundler/gem_tasks in your Rakefile:

bundle exec rake release

This builds the gem, pushes to RubyGems, and can handle git tagging and pushing.

MIT