gccli

name	gccli
description	Google Calendar CLI for listing calendars, viewing/creating/updating events, and checking availability.

Google Calendar CLI

Command-line interface for Google Calendar operations.

Installation

npm install -g @mariozechner/gccli

Setup

Google Cloud Console (one-time)

1. Create a new project (or select existing)
2. Enable the Google Calendar API
3. Set app name in OAuth branding
4. Add test users (all Gmail addresses you want to use)
5. Create OAuth client:
   • Click "Create Client"
   • Application type: "Desktop app"
   • Download the JSON file

Configure gccli

First check if already configured:

gccli accounts list

If no accounts, guide the user through setup:

1. Ask if they have a Google Cloud project with Calendar API enabled
2. If not, walk them through the Google Cloud Console steps above
3. Have them download the OAuth credentials JSON
4. Run: gccli accounts credentials ~/path/to/credentials.json
5. Run: gccli accounts add <email> (use --manual for browserless OAuth)

Usage

Run gccli --help for full command reference.

Common operations:

• gccli <email> calendars - List all calendars
• gccli <email> events <calendarId> [--from <dt>] [--to <dt>] - List events
• gccli <email> event <calendarId> <eventId> - Get event details
• gccli <email> create <calendarId> --summary <s> --start <dt> --end <dt> - Create event
• gccli <email> freebusy <calendarIds> --from <dt> --to <dt> - Check availability

Use primary as calendarId for the main calendar.

Accepting Calendar Invites (RSVP) — DEFAULT

gccli has no native RSVP command, so accepting invites is done by copying the event to the calendar account.

When the user asks to accept calendar invite(s), do the following by default:

1. Find the invite email(s) with gmcli (e.g. gmcli <email> search "subject:Invitation" or filename:ics).
2. Read the thread (gmcli <email> thread <threadId>) to extract:
   • Event summary/title
   • Start date/time
   • End date/time
   • Description and location (if relevant)
3. Create a copy of the event on 's calendar:

   gccli <your-account> create primary \
     --summary "<event title>" \
     --start "<start datetime>" \
     --end "<end datetime>" \
     [--description "<description>"] \
     [--location "<location>"]
   

4. Confirm the event was created successfully.

Notes:

• This creates a copy of the event on the calendar; it does NOT send an "Accepted" RSVP to the organizer.
• For recurring events, copy only the next occurrence or the series pattern as needed.
• The account must be configured with gccli accounts list.

Date/Time Format

• Timed events: YYYY-MM-DDTHH:MM:SSZ (UTC) or YYYY-MM-DDTHH:MM:SS (local)
• All-day events: YYYY-MM-DD with --all-day flag

Data Storage

• ~/.gccli/credentials.json - OAuth client credentials
• ~/.gccli/accounts.json - Account tokens