#+TITLE: gcalcli Setup for Calendar CLI Workflows
#+DATE: 2026-02-01

* Overview

gcalcli is a Python CLI tool for managing Google Calendar from the command line. This enables calendar CRUD operations (create, read, edit, delete) via scripts and Claude Code workflows.

* Installation

#+begin_src bash
pipx install gcalcli
#+end_src

* Authentication

gcalcli requires your own Google Cloud OAuth credentials.

** Prerequisites

- Google Cloud project with Calendar API enabled
- OAuth 2.0 credentials (Desktop application type)
- Credentials stored in =~/.authinfo.gpg= (already configured for org-gcal)

** Setup Steps

1. Extract credentials from authinfo:
   #+begin_src bash
   gpg -d ~/.authinfo.gpg | grep org-gcal
   # Format: machine org-gcal login CLIENT_ID password CLIENT_SECRET
   #+end_src

2. Initialize gcalcli with your client ID:
   #+begin_src bash
   gcalcli --client-id=YOUR_CLIENT_ID.apps.googleusercontent.com init
   #+end_src

3. When prompted, enter the client secret from authinfo

4. Complete OAuth flow in browser (will open automatically)

5. Token is stored in =~/.local/share/gcalcli/oauth=

** Verify Setup

#+begin_src bash
gcalcli list          # List available calendars
gcalcli agenda        # View upcoming events
#+end_src

* Test Calendar

Create a calendar named "Test Calendar" in Google Calendar for running automated tests. This keeps test events separate from real data.

* Workflows Created

Four calendar workflows in =~/projects/homelab/docs/workflows/=:

| Workflow                   | Triggers                                    |
|----------------------------+---------------------------------------------|
| add-calendar-event.org     | "create event", "add appointment"           |
| read-calendar-events.org   | "what's on my calendar", "show schedule"    |
| edit-calendar-event.org    | "edit meeting", "reschedule"                |
| delete-calendar-event.org  | "delete meeting", "cancel appointment"      |

* Test Suite

Test files in =~/projects/homelab/docs/scripts/tests/=:

| Test File                      | Purpose                          |
|--------------------------------+----------------------------------|
| test-gcalcli-setup.sh          | Verify installation and auth     |
| test-gcalcli-add-event.sh      | Event creation tests             |
| test-gcalcli-read-events.sh    | Read/query tests                 |
| test-gcalcli-edit-event.sh     | Edit workflow tests              |
| test-gcalcli-delete-event.sh   | Deletion tests                   |
| test-gcalcli-integration.sh    | Full CRUD lifecycle              |

Run tests:
#+begin_src bash
bash ~/projects/homelab/docs/scripts/tests/test-gcalcli-setup.sh
bash ~/projects/homelab/docs/scripts/tests/test-gcalcli-integration.sh
#+end_src

* Configuration

** Config File Location

=~/.config/gcalcli/config.toml=

** Edit Config

#+begin_src bash
gcalcli config edit
#+end_src

** Example Configuration

#+begin_src toml
[gcalcli]
# Default calendar for operations
default-calendar = "Personal"

# Calendars to ignore in listings
ignore-calendars = ["Holidays in United States", "Birthdays"]

# Week starts on Monday (default: Sunday)
week-start = "monday"

# Default event duration in minutes
default-duration = 60

# Color output
use-color = true
#+end_src

** OAuth Token Location

=~/.local/share/gcalcli/oauth=

This file contains the OAuth refresh token. If authentication breaks, delete this file and run =gcalcli init= again.

** Environment Variables

#+begin_src bash
# Override config file location
export GCALCLI_CONFIG=~/.config/gcalcli/config.toml

# Disable color output
export GCALCLI_NOCOLOR=1
#+end_src

** Calendar-Specific Defaults

Use =--calendar= flag to override default:

#+begin_src bash
gcalcli --calendar "Work" agenda
gcalcli --calendar "Test Calendar" add --title "Test" --when "tomorrow 3pm" --duration 30 --noprompt
#+end_src

** Reminder Defaults

Default reminders can be set per-calendar in Google Calendar settings. gcalcli respects these unless overridden with =--reminder= flags.

Workflow default: =--reminder 5 --reminder 0= (5 minutes before, at event time)

* Key Commands

#+begin_src bash
# List calendars
gcalcli list

# View agenda
gcalcli agenda
gcalcli agenda "today" "next week"

# Calendar views
gcalcli calw    # Weekly
gcalcli calm    # Monthly

# Add event
gcalcli add --title "Meeting" --when "tomorrow 3pm" --duration 60 --noprompt

# Quick add (natural language)
gcalcli quick "Dinner with Bob 7pm Friday"

# Search
gcalcli search "meeting"

# Delete
gcalcli delete "Event Title" --iamaexpert
#+end_src

* archsetup Integration

Consider adding to archsetup:

1. =pipx install gcalcli= in package installation
2. gcalcli init instructions in post-install docs
3. OAuth credentials setup reminder

* Dependencies

- pipx (for installation)
- Google Cloud project with Calendar API enabled
- OAuth credentials in =~/.authinfo.gpg=

* Reference

- gcalcli GitHub: https://github.com/insanum/gcalcli
- Auth docs: https://github.com/insanum/gcalcli/blob/HEAD/docs/api-auth.md
- Homelab research: =~/projects/homelab/docs/calendar-api-research.org=