gcalcli

What this skill does

# 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_t