blob: 38b13d422a95a91dee9977c45b6ca8725cdc001b (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
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=
|
