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:

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

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

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

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

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:

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

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

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:

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