Introduction
# 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:** ```bash 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):** ```bash 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):** ```bash 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):** ```bash 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):** ```bash 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:** ```bash 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):** ```bash 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):** ```bash 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:** ```bash 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:** ```bash 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:** ```bash # 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:** ```bash # 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: ```bash # 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):** ```bash # 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:** ```bash # 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
### --tsv (Tab-Separated Values) - One event per line - Tab-separated fields: - id - start_date, start_time - end_date, end_time - html_link - hangout_link - conference details - title - location - description (full, no truncation) - calendar - email - attachments (pipe-separated: title|url|title|url...) - action - Ideal for parsing with standard Unix tools (grep, awk, cut) - No ANSI color codes or formatting
### Default Format - Human-readable colored output - Shows time, title, basic details - May truncate long descriptions with "..." indicator
### --details all - Includes full descriptions - Shows all attendees with response status - Conference/meeting links - Location information - Attachments (in human-readable format)
## Use Cases
### 1. Morning Review Check what's on today's schedule (shows from current time onwards): ```bash 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 "today" ```
Note: This shows events from NOW onwards. To see the full day including past events, use the specific date: ```bash 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 "2025-10-07" "2025-10-07" ```
### 2. Weekly Planning See upcoming week to plan deep work time: ```bash 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 "monday" "friday" ```
### 3. Meeting Preparation Check details for upcoming meetings: ```bash 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 "today" "tomorrow" ```
### 4. Find Meeting Links and Notes Get conference links and meeting notes for a meeting: ```bash # Using JSON (recommended for accessing 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 | jq '.[] | select(.title | contains("Meeting Name"))'
# Using TSV 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 | grep "Meeting Name" ```
### 5. Context Before Work Before working on a feature, check if there are relevant sync meetings: ```bash uvx gcalcli search --calendar [email protected] "ANSTRAT-1673" ```
## Integration with Work Tracking
### Calendar-Aware Planning
When planning your day's agenda: 1. Check calendar for upcoming related meetings 2. Note if meetings happen before important deadlines (e.g., sync 2 days before release) 3. Plan work to prepare for discussions 4. Identify good time blocks for focused work (between meetings)
### Examples
**ANSTRAT-1673 Scenario:** - Oct 8: Sync meeting with Demetrius Lima - Oct 10: Expected llama-stack release - Action: Check calendar to confirm timing, prepare talking points
**Pre-Meeting Prep:** ```bash # See what's coming up this week 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] --json "monday" "friday"
# Check specific meeting details 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] --json "ANSTRAT" ```
## Tips
1. **Always use custom fork with constraint**: Use `uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0"` for attachment support 2. **Always use `--json` flag**: Default to JSON format for structured data with attachments 3. **Use `jq` for parsing**: JSON output works perfectly with `jq` for filtering and extracting data 4. **Check calendar at session start**: Part of standard workflow 5. **Time-box focused work**: Look for gaps between meetings 6. **Prepare for syncs**: Check calendar 1-2 days before important meetings 7. **Access meeting notes**: Use `jq` to filter for Gemini notes, then export with gcmd 8. **Search before export**: Use `gcalcli search` to find relevant meetings, then filter attachments array 9. **Understand time ranges**: `"today"` shows from NOW onwards, not the full day. Use specific dates for complete day view.
## Limitations
- Read-only (no event creation/modification via CLI documented here) - Requires OAuth authentication - May need periodic re-authentication - Multiple calendars require separate `--calendar` flags
## Additional Commands
**List all calendars:** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli list ```
**View in calendar format (month view):** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli calm ```
**Quick view (next 5 events) with JSON:** ```bash 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 '.[0:5]' ```
## Reference
- Official gcalcli documentation: https://github.com/insanum/gcalcli - Custom fork with attachment support: https://github.com/shanemcd/gcalcli/tree/attachments-in-tsv-and-json - Uses Google Calendar API v3 - Supports multiple output formats (JSON, TSV, text)