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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
#+TITLE: Read Calendar Events Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-02-01
* Overview
Workflow for viewing and querying calendar events via gcalcli.
* Triggers
- "what's on my calendar"
- "show me appointments"
- "summarize my schedule"
- "what do I have today"
- "calendar for this week"
- "any meetings tomorrow"
* Prerequisites
- gcalcli installed and authenticated
- Test with =gcalcli list= to verify authentication
* CRITICAL: Cross-Calendar Visibility
gcalcli only sees Google calendars. To see ALL of Craig's calendars (Google, DeepSat work, Proton), you MUST query the emacs org calendar files:
#+begin_src bash
grep "2026-02-18" ~/.emacs.d/data/gcal.org # Google calendar
grep "2026-02-18" ~/.emacs.d/data/dcal.org # DeepSat work calendar
grep "2026-02-18" ~/.emacs.d/data/pcal.org # Proton calendar
#+end_src
| File | Calendar |
|----------+---------------------------|
| gcal.org | Craig (Google) |
| dcal.org | Craig DeepSat (work) |
| pcal.org | Craig Proton |
*ALWAYS check all three files* when checking availability or showing the schedule. gcalcli alone will miss work and Proton events, causing an incomplete picture.
To *create* events, use gcalcli with =--calendar "Craig"= (Google). The org files are read-only views.
* Workflow Steps
** 1. Parse Time Range
Interpret the user's request to determine date range:
| Request | Interpretation |
|--------------------+-------------------------------|
| "today" | Today only |
| "tomorrow" | Tomorrow only |
| "this week" | Next 7 days |
| "next week" | 7-14 days from now |
| "this month" | Rest of current month |
| "April 2026" | That entire month |
| "next Tuesday" | That specific day |
| "the 15th" | The 15th of current month |
*No fixed default* - interpret from context. If unclear, ask.
** 2. Determine Calendar Scope
Options:
- All calendars (default)
- Specific calendar: use =--calendar "Name"=
** 3. Query Calendar
#+begin_src bash
# Agenda view (list format)
gcalcli agenda "start_date" "end_date"
# Weekly calendar view
gcalcli calw
# Monthly calendar view
gcalcli calm
#+end_src
** 4. Format Results
Present events in a readable format:
#+begin_example
=== Tuesday, February 4, 2026 ===
9:00 AM - 10:00 AM Team Standup
Location: Conference Room A
2:00 PM - 3:00 PM Dentist Appointment
Location: Downtown Dental
=== Wednesday, February 5, 2026 ===
(No events)
=== Thursday, February 6, 2026 ===
10:00 AM - 11:30 AM Project Review
Location: Zoom
#+end_example
** 5. Summarize
Provide a brief summary:
- Total number of events
- Busy days vs free days
- Any all-day events
- Conflicts (if any)
* gcalcli Command Reference
** Agenda View
#+begin_src bash
# Default agenda (next few days)
gcalcli agenda
# Today only
gcalcli agenda "today" "today 11:59pm"
# This week
gcalcli agenda "today" "+7 days"
# Specific date range
gcalcli agenda "2026-03-01" "2026-03-31"
# Specific calendar
gcalcli --calendar "Work" agenda "today" "+7 days"
#+end_src
** Calendar Views
#+begin_src bash
# Weekly calendar (visual)
gcalcli calw
# Monthly calendar (visual)
gcalcli calm
# Multiple weeks
gcalcli calw 2 # Next 2 weeks
#+end_src
** Search
#+begin_src bash
# Search by title
gcalcli search "meeting"
# Search specific calendar
gcalcli --calendar "Work" search "standup"
#+end_src
* Output Formats
gcalcli supports different output formats:
| Option | Description |
|------------------+--------------------------------|
| (default) | Colored terminal output |
| --nocolor | Plain text |
| --tsv | Tab-separated values |
* Time Range Examples
| User Says | gcalcli Command |
|------------------------+----------------------------------------------|
| "today" | agenda "today" "today 11:59pm" |
| "tomorrow" | agenda "tomorrow" "tomorrow 11:59pm" |
| "this week" | agenda "today" "+7 days" |
| "next week" | agenda "+7 days" "+14 days" |
| "February" | agenda "2026-02-01" "2026-02-28" |
| "next 3 days" | agenda "today" "+3 days" |
| "rest of the month" | agenda "today" "2026-02-28" |
* Calendars
| Calendar | Access | Notes |
|---------------------------+--------+--------------------------------|
| Craig | owner | Default personal calendar |
| Christine | owner | Christine's calendar |
| Todoist | owner | Todoist integration |
| Craig Jennings (TripIt) | reader | View only |
| Holidays in United States | reader | View only |
| Craig Proton | reader | View only (no API access) |
* Handling No Events
If the date range has no events:
- Confirm the range was correct
- Mention the calendar is free
- Offer to check a different range
Example: "No events found for tomorrow (Feb 3). Your calendar is free that day."
* Error Handling
** No Events Found
Not an error - calendar may simply be free.
** Authentication Error
Run =gcalcli init= to re-authenticate.
** Invalid Date Range
Use explicit dates: =YYYY-MM-DD=
* Related
- [[file:add-calendar-event.org][Add Calendar Event]] - create events
- [[file:edit-calendar-event.org][Edit Calendar Event]] - modify events
- [[file:delete-calendar-event.org][Delete Calendar Event]] - remove events
- [[file:../calendar-api-research.org][Calendar API Research]] - gcalcli reference
|
