gcalcliInteract with Google Calendar via gcalcli
Install via ClawdBot CLI:
clawdbot install gargravish/gcalcliThis document provides details on using gcalcli to view and manage calendar events.
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" gcalcliThis custom version includes attachments in TSV and JSON output, which is essential for accessing meeting notes and other event attachments.
First time running gcalcli, it will:
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 smcdonal@redhat.com --details all --jsonAlternative: 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 smcdonal@redhat.com --details all --tsvHuman-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 smcdonal@redhat.com --details allBasic 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 smcdonal@redhat.comImportant: 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 smcdonal@redhat.com "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 smcdonal@redhat.com "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 smcdonal@redhat.com "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 smcdonal@redhat.com "monday" "friday"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 smcdonal@redhat.com "MCP Server"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 DocCommon attachment types:
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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com --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:
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 smcdonal@redhat.com --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 smcdonal@redhat.com --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)jq or PythonCheck what's on today's schedule (shows 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 smcdonal@redhat.com --json "today"Note: This shows events from NOW onwards. To see the full day including past events, use the specific date:
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json "2025-10-07" "2025-10-07"See upcoming week to plan deep work time:
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json "monday" "friday"Check details for upcoming meetings:
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --details all --json "today" "tomorrow"Get conference links and meeting notes for a meeting:
# 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 smcdonal@redhat.com --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 smcdonal@redhat.com --details all --tsv | grep "Meeting Name"Before working on a feature, check if there are relevant sync meetings:
uvx gcalcli search --calendar smcdonal@redhat.com "ANSTRAT-1673"When planning your day's agenda:
ANSTRAT-1673 Scenario:
Pre-Meeting Prep:
# 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 smcdonal@redhat.com --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 smcdonal@redhat.com --json "ANSTRAT"uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" for attachment support--json flag: Default to JSON format for structured data with attachmentsjq for parsing: JSON output works perfectly with jq for filtering and extracting datajq to filter for Gemini notes, then export with gcmdgcalcli search to find relevant meetings, then filter attachments array"today" shows from NOW onwards, not the full day. Use specific dates for complete day view.--calendar flagsList all calendars:
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli listView in calendar format (month view):
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli calmQuick view (next 5 events) with JSON:
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json | jq '.[0:5]'Generated Mar 1, 2026
Individuals can use this skill to automatically fetch their upcoming calendar events, including meeting notes and attachments, to prepare for the day. It helps in organizing schedules and accessing important documents like meeting recordings or shared agendas directly from the command line.
Managers or team leads can analyze meeting patterns by extracting event data in JSON or TSV format to track frequency, attendance, and attachment types like notes or recordings. This aids in optimizing meeting efficiency and resource allocation across projects.
Researchers or analysts can search for specific events, such as those with Gemini notes, to gather insights from past meetings. By exporting notes in bulk, they can compile data for reports or studies, leveraging structured outputs for qualitative analysis.
Organizations can integrate this skill into automated workflows to generate daily or weekly calendar summaries. It can filter events by attachments like recordings or chat transcripts, providing structured reports for compliance or archival purposes.
Developers can embed this skill into custom applications or scripts to pull calendar data programmatically. Using the JSON output, they can build dashboards or sync events with other tools, enhancing productivity through automation and data interoperability.
Offer a basic version for free with limited calendar access and attachments, then charge for advanced features like bulk exports, analytics dashboards, and integration with other productivity apps. Revenue comes from subscription tiers targeting professionals and teams.
Provide tailored solutions for businesses needing specific calendar integrations, such as custom scripts for data extraction or training on using the skill effectively. Revenue is generated through project-based fees and ongoing support contracts.
Aggregate anonymized calendar data from users to offer insights into meeting trends and productivity metrics. Monetize by selling aggregated reports to organizations or through premium access to detailed analytics tools for individual users.
💬 Integration Tip
Use the JSON output format for easy parsing in scripts, and leverage jq for filtering attachments like Gemini notes to automate data extraction and reporting.
Interact with Google Calendar via the Google Calendar API – list upcoming events, create new events, update or delete them. Use this skill when you need programmatic access to your calendar from OpenClaw.
Read, search, and manage Outlook emails and calendar via Microsoft Graph API. Use when the user asks about emails, inbox, Outlook, Microsoft mail, calendar events, or scheduling.
Google Calendar via gcalcli: today-only agenda by default, bounded meaning-first lookup via agenda scans, and fast create/delete with verification--optimized for low tool calls and minimal output.
This skill should be used when interacting with Apple Calendar on macOS. Use it for listing calendars, viewing events, creating/updating/deleting calendar events, and checking availability/free-busy times. Triggers on requests like "check my calendar", "schedule a meeting", "what's on my schedule", "am I free tomorrow", or any calendar-related operations.
Access and manage Google Calendar events with gogcli for cross-calendar agendas, keyword search, and filtered outputs avoiding unwanted calendars like holidays.
Daily morning rollup of important emails and calendar events at 8am with AI-generated summaries