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:**
```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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com
```

### 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 smcdonal@redhat.com "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 smcdonal@redhat.com "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 smcdonal@redhat.com "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 smcdonal@redhat.com "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 smcdonal@redhat.com "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 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:**
```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 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:
```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 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):**
```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 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:
- 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 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)
```

## 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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 smcdonal@redhat.com --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 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"
```

### 5. Context Before Work
Before working on a feature, check if there are relevant sync meetings:
```bash
uvx gcalcli search --calendar smcdonal@redhat.com "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 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"
```

## 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 smcdonal@redhat.com --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)