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