gccli

Minimal Google Calendar CLI for listing calendars, managing events, and checking availability.

Install

npm install -g @mariozechner/gccli

Setup

Before adding an account, you need OAuth2 credentials from Google Cloud Console:

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 with gccli)
5. Create OAuth client:
   • Click "Create Client"
   • Application type: "Desktop app"
   • Download the JSON file

Then:

gccli accounts credentials ~/path/to/credentials.json
gccli accounts add [email protected]

Usage

gccli accounts <action>                Account management
gccli <email> <command> [options]      Calendar operations

Commands

accounts

gccli accounts credentials <file.json>   # Set OAuth credentials (once)
gccli accounts list                      # List configured accounts
gccli accounts add <email>               # Add account (opens browser)
gccli accounts add <email> --manual      # Add account (browserless, paste redirect URL)
gccli accounts remove <email>            # Remove account

calendars

List all calendars for an account.

gccli <email> calendars

Returns: ID, name, access role.

events

List events from a calendar.

gccli <email> events <calendarId> [options]

Options:

• --from <datetime> - Start time (ISO 8601, default: now)
• --to <datetime> - End time (ISO 8601, default: 1 week from now)
• --max <n> - Max results (default: 10)
• --page <token> - Page token for pagination
• --query <q> - Free text search

Examples:

gccli [email protected] events primary
gccli [email protected] events primary --from 2024-01-01T00:00:00Z --max 50
gccli [email protected] events primary --query "meeting"

event

Get details for a specific event.

gccli <email> event <calendarId> <eventId>

create

Create a new event.

gccli <email> create <calendarId> --summary <s> --start <dt> --end <dt> [options]

Options:

• --summary <s> - Event title (required)
• --start <datetime> - Start time (required, ISO 8601)
• --end <datetime> - End time (required, ISO 8601)
• --description <d> - Event description
• --location <l> - Event location
• --attendees <emails> - Attendees (comma-separated)
• --all-day - Create all-day event (use YYYY-MM-DD for start/end)

Examples:

gccli [email protected] create primary --summary "Meeting" --start 2024-01-15T10:00:00 --end 2024-01-15T11:00:00
gccli [email protected] create primary --summary "Vacation" --start 2024-01-20 --end 2024-01-25 --all-day
gccli [email protected] create primary --summary "Team Sync" --start 2024-01-15T14:00:00 --end 2024-01-15T15:00:00 --attendees [email protected],[email protected]

update

Update an existing event.

gccli <email> update <calendarId> <eventId> [options]

Options: same as create (all optional).

Example:

gccli [email protected] update primary abc123 --summary "Updated Meeting" --location "Room 2"

delete

Delete an event.

gccli <email> delete <calendarId> <eventId>

freebusy

Check free/busy status for calendars.

gccli <email> freebusy <calendarIds> --from <dt> --to <dt>

Calendar IDs are comma-separated.

Example:

gccli [email protected] freebusy primary,[email protected] --from 2024-01-15T00:00:00Z --to 2024-01-16T00:00:00Z

acl

List access control rules for a calendar.

gccli <email> acl <calendarId>

Returns: scope type, scope value, role.

Example:

gccli [email protected] acl primary

Data Storage

All data is stored in ~/.gccli/:

• credentials.json - OAuth client credentials
• accounts.json - Account tokens

Development

npm install
npm run build
npm run check

Publishing

# Update version in package.json and CHANGELOG.md
npm run build
npm publish --access public
git tag v<version>
git push --tags

License

MIT