gcal-cli

Tiny command-line tool for viewing and managing your Google Calendar events- useful in conjunction with LLM clis.

Features

• List upcoming events: Get a quick look at your schedule.
• Find events: Search for events by keyword.
• Add events: Create new timed or all-day events.
• Update events: Patch an event's summary, time, location, etc.
• Delete events: Remove an event by its ID.
• Quick Add: Create events using natural language (e.g., "Lunch with Alex tomorrow at 1pm").

Setup

1. Install Dependencies:

   pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib python-dateutil

2. Enable the Google Calendar API:

   • Go to the Google Cloud Console.
   • Create a new project if you don't have one.
   • Configure the OAuth consent screen. For personal use, you can select "External" and add your own Google account as a test user.
   • Create an "OAuth client ID" of type "Desktop app".
   • Download the JSON credentials and save the file as client_secret.json in the same directory as the script.

3. First-time Authorization:

   The first time you run the script, it will open a browser window to ask for permission to access your calendar. It will save an authentication token in token.json for future runs.

   python gcal_cli.py list

Usage Examples

• List the next 10 events:

  python gcal_cli.py list --max-results 10

• Add a timed event:

  python gcal_cli.py add --summary "Team sync" --start "2025-11-12 14:00" --end "2025-11-12 14:30" --location "Zoom"

• Add an all-day event:

  python gcal_cli.py add --summary "Hackathon" --start "2025-11-15" --end "2025-11-16"

• Find upcoming events matching a query:

  python gcal_cli.py find --q "sync"

• Update an event's title (use the ID from list or find):

  python gcal_cli.py patch --id "abcdef1234567890" --summary "Updated title"

• Delete an event:

  python gcal_cli.py delete --id "abcdef1234567890"

• Quick add an event with natural language:

  python gcal_cli.py quickadd --text "Lunch with Alex tomorrow 12pm-1pm"

Configuration

Timezone

The script defaults to the America/New_York timezone. You can override this by setting the GCAL_CLI_TZ environment variable.

export GCAL_CLI_TZ="Europe/London"
python gcal_cli.py list