Calendar Reference

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

Installation

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

IMPORTANT: Always use the custom fork with attachment support:
CODEBLOCK0

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. 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):
CODEBLOCK1

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

Human-readable format (may truncate long descriptions):
CODEBLOCK3

Basic agenda view (minimal details):
CODEBLOCK4

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:
CODEBLOCK5

Today only (from current time onwards):
CODEBLOCK6

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

Next week:
CODEBLOCK8

Search Calendar

Search for events by text:
CODEBLOCK9

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")
• INLINECODE9: 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:
CODEBLOCK10

Filter events by attachment type:
CODEBLOCK11

Export Gemini notes using gcmd:

Single meeting export:
CODEBLOCK12

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

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:
CODEBLOCK14

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:

• - 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

Note: This shows events from NOW onwards. To see the full day including past events, use the specific date:
CODEBLOCK16

2. Weekly Planning

3. Meeting Preparation

4. Find Meeting Links and Notes

5. Context Before Work

Integration with Work Tracking

Calendar-Aware Planning

When planning your day's agenda:

1. 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:
CODEBLOCK21

Tips

1. 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:
CODEBLOCK22

View in calendar format (month view):
CODEBLOCK23

Quick view (next 5 events) with JSON:
CODEBLOCK24

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)