Google Calendar CLI

Google Calendar management via the gog CLI tool. Create, list, update, and delete calendar events with color support, OAuth authentication, and scripting capabilities. Use when working with Google Calendar events, scheduling meetings, checking availability, or managing calendar entries from the command line.

Manage Google Calendar events efficiently using the gog command-line tool.

Prerequisites

Install gog

brew install steipete/tap/gogcli

Authentication Setup

# Set up OAuth credentials
gog auth credentials /path/to/client_secret.json

# Add your Google account with calendar access
gog auth add [e-mail] --services calendar

# Verify authentication
gog auth list

Quick Start

List Events

# List events from primary calendar (today's events)
gog calendar events primary --from "2026-01-01T00:00:00Z" --to "2026-01-01T23:59:59Z"

# List events for next 7 days
gog calendar events primary --from "$(date -u +%Y-%m-%dT00:00:00Z)" --to "$(date -u -v+7d +%Y-%m-%dT23:59:59Z)"

Create Event

# Create a basic event
gog calendar create primary --summary "Team Meeting" --from "2026-01-15T14:00:00+01:00" --to "2026-01-15T15:00:00+01:00"

# Create with color
gog calendar create primary --summary "Important Deadline" --from "2026-01-20T00:00:00+01:00" --to "2026-01-20T23:59:59+01:00" --event-color 11

Update Event

# Update event title and color
gog calendar update primary <eventId> --summary "Updated Meeting Title" --event-color 4

Event Colors

Color ID	Hex Code	Typical Use
1	#a4bdfc	Meetings, Work
2	#7ae7bf	Personal, Health
3	#dbadff	Social, Events
4	#ff887c	Deadlines, Urgent
5	#fbd75b	Reminders
6	#ffb878	Travel
7	#46d6db	Fun, Leisure
8	#e1e1e1	General
9	#5484ed	Work Projects
10	#51b749	Completed, Done
11	#dc2127	Critical, High Priority

# View all colors
gog calendar colors

Common Workflows

Find Available Time Slots

# List all events to visualize availability
gog calendar events primary --from "2026-01-15T00:00:00Z" --to "2026-01-21T23:59:59Z" --json

Schedule Recurring Concept

Note: gog CLI doesn't support direct recurring events, but you can script them:

# Create multiple events via scripting (example)
for i in {1..5}; do
  DATE=$(date -v+${i}d +%Y-%m-%d)
  gog calendar create primary --summary "Daily Standup" \
    --from "${DATE}T09:00:00+01:00" --to "${DATE}T09:30:00+01:00" \
    --event-color 1
done

Bulk Operations

# Set default account to avoid repetition
export GOG_ACCOUNT=[e-mail]

# Then run commands without --account
gog calendar events primary --from "..." --to "..."

Tips for Effective Use

1. Use ISO 8601 timestamps: Always include timezone offset
2. JSON output for scripting: Add --json flag for machine-readable output
3. Batch with --no-input: Use --no-input for automated scripts
4. Primary calendar shortcut: Use "primary" as the calendar ID for your main calendar

Example Script: Weekly Agenda Check

#!/bin/bash
# Get this week's events
START=$(date -u -v-Monday +%Y-%m-%dT00:00:00Z)
END=$(date -u -v+Sunday +%Y-%m-%dT23:59:59Z)
gog calendar events primary --from "$START" --to "$END" --json