diff options
Diffstat (limited to 'assets/2026-02-01-gcalcli-setup.org')
| -rw-r--r-- | assets/2026-02-01-gcalcli-setup.org | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/assets/2026-02-01-gcalcli-setup.org b/assets/2026-02-01-gcalcli-setup.org new file mode 100644 index 0000000..38b13d4 --- /dev/null +++ b/assets/2026-02-01-gcalcli-setup.org @@ -0,0 +1,192 @@ +#+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= |