chore(assets): archive processed inbox itemsHEADmain

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=