--- name: gcalcli description: Interact with Google Calendar via gcalcli ---

Calendar Reference

This document provides details on using gcalcli to view and manage calendar events.

Installation

gcalcli is a Python CLI for Google Calendar that works with uvx for one-time execution.

IMPORTANT: Always use the custom fork with attachment support:

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli

This custom version includes attachments in TSV and JSON output, which is essential for accessing meeting notes and other event attachments.

Authentication

First time running gcalcli, it will:

1. Open a browser for Google OAuth authentication
2. Cache credentials for future use
3. Request calendar read permissions

Common Commands

View Upcoming Agenda

Recommended: JSON format with full details (structured data with attachments):

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --details all --json

Alternative: TSV format (tab-separated, parseable):

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --details all --tsv

Human-readable format (may truncate long descriptions):

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --details all

Basic agenda view (minimal details):

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected]

Date Ranges

Important: gcalcli agenda shows events from NOW onwards by default.

When you run gcalcli agenda "today" at 2pm, it shows events from 2pm onwards for today and into the future. Past events from earlier today won't appear.

Specific date range:

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "tomorrow" "2 weeks"

Today only (from current time onwards):

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "today"

See earlier today's events (use absolute dates):

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "2025-10-07" "2025-10-07"

Next week:

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "monday" "friday"

Search Calendar

Search for events by text:

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search --calendar [email protected] "MCP Server"

Access Meeting Attachments and Gemini Notes

IMPORTANT: The custom gcalcli fork includes attachments array in JSON/TSV output.

Each event's attachments array contains objects with:

• attachment_title: Title of the attachment (e.g., "Notes by Gemini", "Recording", "Chat")
• attachment_url: Direct link to Google Drive file or Google Doc

Common attachment types:

• "Notes by Gemini": AI-generated meeting notes from Google Meet
• Recording: Meeting recordings (video files)
• Chat: Meeting chat transcripts
• Shared docs: Agendas, planning docs, presentations

Search for events with Gemini notes:

# Find all events with Gemini notes
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP" --calendar [email protected] --details all --json | jq '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | {title, attachments: [.attachments[] | select(.attachment_title | contains("Notes by Gemini"))]}'

# Get just the titles and Gemini note URLs
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP" --calendar [email protected] --details all --json | jq -r '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | "\(.title): \(.attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url)"'

Filter events by attachment type:

# Events with recordings
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --json | jq '.[] | select(.attachments[]? | .attachment_title | contains("Recording"))'

# Events with any attachments
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --json | jq '.[] | select(.attachments | length > 0)'

Export Gemini notes using gcmd:

Single meeting export:

# 1. Find meeting with Gemini notes
GEMINI_URL=$(uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP proposals" --calendar [email protected] --json | jq -r '.[0].attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url' | head -1)

# 2. Export to markdown using gcmd
cd /var/home/shanemcd/github/shanemcd/gcmd
uv run gcmd export "$GEMINI_URL" -o ~/Downloads/

Bulk export ALL Gemini notes from search results (parallel):

# Extract Gemini note URLs and export in parallel (8 concurrent processes)
cd /var/home/shanemcd/github/shanemcd/gcmd
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP" --calendar [email protected] --details all --json "2 months ago" "today" | jq -r '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | .attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url' | sort -u | xargs -P 8 -I {} sh -c 'uv run gcmd export "{}" -o ~/Downloads/meeting-notes/'

This efficiently:

• Searches calendar for meetings matching your query
• Filters to only meetings with Gemini notes
• Exports all notes in parallel (8 at a time) to organized directory
• Uses direct pipeline (no intermediate files)
• Deduplicates URLs with sort -u

Common workflow - Review recent meeting notes:

# Search for recent meetings on a topic
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "ANSTRAT-1567" --calendar [email protected] --json

# Filter to show only events with Gemini notes
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "ANSTRAT-1567" --calendar [email protected] --json | jq '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | {title, date: .s, gemini_notes: [.attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url]}'

# Export the most recent Gemini notes for review
# (extract URL, then use gcmd export)

Output Formats

--json (JSON Format) RECOMMENDED

• Structured JSON output with complete event data
• Includes attachments array with title and fileUrl for each attachment
• All event fields preserved
• Easy to parse programmatically with jq or Python
• No truncation of any fields
• Best for accessing meeting notes and attachments

...