gc

A fast Google Calendar CLI written in Go.

Mainly for Agents to use but Humans are welcome too.

Notes

• Not all Google Calendar API functions are implemented, just the most useful.
• Queries all calendars by default. Use --calendar to target specific ones by name or ID.
• Warns about scheduling conflicts when creating events.

Setup

1. Create OAuth2 credentials in Google Cloud Console (Desktop application type).
2. Save the credentials file: ~/.config/gc/credentials.json
3. Build: sh go build -o gc .
4. Authenticate: sh gc auth

Usage

All commands support --json for machine-readable output.

View events

gc today                                # Today's events
gc week                                 # Next 7 days, grouped by day
gc next                                 # Next 5 upcoming events
gc next -n 10                           # Next 10 upcoming events
gc events --from 2025-03-01 --to 2025-03-07   # Date range
gc events --from 2025-03-01             # From date to +7 days
gc search team standup                  # Search by text
gc show abc123                          # Full event details

Manage events

gc add "Team standup" --start 9:00AM --end 9:30AM
gc add "All-day offsite" --date 2025-03-15
gc add "Lunch" --start "2025-03-01 12:00" --end "2025-03-01 13:00" --location "Cafe"
gc add "Review" --start 10:00AM --attendees alice@co.com,bob@co.com

gc update abc123 --summary "New title"
gc update abc123 --start 10:00AM --end 11:00AM
gc update abc123 --location "Room 42"

gc delete abc123

Calendars

gc calendars                            # List all calendars
gc --calendar Family week               # Events from "Family" calendar only
gc --calendar Work,Family today         # Multiple calendars by name

Global flags

--json                                  # JSON output
--calendar <name|id|"all">              # Target calendar(s) (default: all)
--timezone America/New_York             # Override timezone

Agent reference

gc agent                                # Full CLI reference in one shot (no auth required)

Prints a compact, structured plain-text reference covering all commands, flags, date/time formats, calendar name resolution, and output behavior. Designed to be consumed by LLM agents in a single context load.

Development

go test ./...       # Run all tests
go build -o gc .    # Build binary