Google Calendar CLI

Command-line interface for Google Calendar operations.

Installation

npm install -g @mariozechner/gccli

Setup

Google Cloud Console (one-time)

• Create a new project (or select existing)

• Enable the Google Calendar API

• Set app name in OAuth branding

• Add test users (all Gmail addresses you want to use)

• 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:

• Ask if they have a Google Cloud project with Calendar API enabled

• If not, walk them through the Google Cloud Console steps above

• Have them download the OAuth credentials JSON

• Run: gccli accounts credentials ~/path/to/credentials.json

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

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