gcalcli-calendar

Use

gcalcli

to read/search/manage Google Calendar with minimal tool calls and minimal output.

Rules

CLI flag placement (critical)

Global flags (
```
--nocolor
```
,
```
--calendar
```
) go BEFORE the subcommand.
Subcommand-specific flags go AFTER the subcommand name.

Example:

gcalcli --nocolor delete --iamaexpert "query" start end

— NOT

gcalcli --nocolor --iamaexpert delete ...

This applies to ALL subcommand flags:
```
--iamaexpert
```
(delete),
```
--noprompt
```
/
```
--allday
```
(add),
```
--use-legacy-import
```
(import), etc.

Output & language

Don't print CLI commands/flags/tool details unless the user explicitly asks (e.g. "show commands used", "/debug", "/commands").
If asked for commands: print ALL executed commands in order (including retries) and nothing else.
Don't mix languages within one reply.
Be concise. No scope unless nothing found.

Dates & formatting

Human-friendly dates by default. ISO only if explicitly requested.
Don't quote event titles unless needed to disambiguate.

Calendar scope

Trust gcalcli config (default/ignore calendars). Don't broaden scope unless user asks "across all calendars" or results are clearly wrong.

Agenda (today-only by default)

If user asks "agenda" without a period, return today only.
Expand only if explicitly asked (tomorrow / next N days / date range).

Weekday requests (no mental math)

If user says "on Monday/Tuesday/..." without a date:

fetch next 14 days agenda once,
pick matching day/event from tool output,
proceed (or disambiguate if multiple).

Finding events: prefer deterministic agenda scan (meaning-first)

When locating events to cancel/delete/edit:

Prefer
```
agenda
```
over
```
search
```
.
Use a bounded window and match events by meaning (semantic match) rather than exact text.
Default locate windows:
- If user gives an exact date: scan that day only.
- If user gives a weekday: scan next 14 days.
- If user gives only meaning words ("train", "lecture", etc.) with no date: scan next 30 days first.
- If still not found: expand to 180 days and say so only if still empty.

Use gcalcli

search

only as a fallback when:

the time window would be too large to scan via agenda (token-heavy), or
the user explicitly asked to "search".

Search (bounded)

Default search window: next ~180 days (unless user specified otherwise).
If no matches: say "No matches in next ~6 months (<from>-><to>)" and offer to expand.
Show scope only when nothing is found.

Tool efficiency

Default: use
```
--nocolor
```
to reduce formatting noise and tokens.
Use
```
--tsv
```
only if you must parse/dedupe/sort.

Actions policy (optimized for conversational speed)

This skill is designed for personal assistant use where the user expects fast, low-friction calendar management. The confirmation policy below is an intentional UX choice — see README.md for rationale and safety guards.

Unambiguous actions: execute immediately

For cancel/delete/edit actions, skip confirmation when ALL of these hold:

The user explicitly requested the action (e.g. "delete my dentist appointment").
Exactly one event matches in a tight time window.
The match is unambiguous (single clear result on an exact date, or user specified date+time).

Ambiguous actions: always ask first

If multiple candidates match, or the match is uncertain:

Ask a short disambiguation question listing the candidates (1-3 lines) and wait for the user's choice.

Create events: overlap check MUST be cross-calendar (non-ignored scope)

When creating an event:

Always run a best-effort overlap check across ALL non-ignored calendars by scanning agenda WITHOUT
```
--calendar
```
.
- This ensures overlaps are detected even if the new event is created into a specific calendar.
If overlap exists with busy events:
- Ask for confirmation before creating.
If no overlap:
- Create immediately.

Choose the right create method

add
— default for one-off events. Supports
```
--allday
```
,
```
--reminder
```
,
```
--noprompt
```
. Does NOT support recurrence or free/busy (transparency).
import
via stdin — use ONLY when you need recurrence (RRULE) or free/busy (TRANSP:TRANSPARENT). Pipe ICS content via stdin; NEVER write temp .ics files (working directory is unreliable in exec sandbox).
quick
— avoid unless user explicitly asks for natural-language add. Less deterministic.

Deletes must be verified

Use non-interactive delete with
```
--iamaexpert
```
(a
```
delete
```
subcommand flag — goes AFTER
```
delete
```
). This is gcalcli's built-in flag for non-interactive/scripted deletion.
Always verify via agenda in the same tight window after deletion.
If verification still shows the event, do one retry with
```
--refresh
```
.
Never claim success unless verification confirms the event is gone.

Canonical commands

Agenda (deterministic listing)

Today:
```
gcalcli --nocolor agenda today tomorrow
```
Next 14d (weekday resolution):
```
gcalcli --nocolor agenda today +14d
```
Next 30d (meaning-first locate):
```
gcalcli --nocolor agenda today +30d
```
Custom:
```
gcalcli --nocolor agenda <start> <end>
```

Search (fallback / explicit request)

Default (~6 months):

gcalcli --nocolor search "<query>" today +180d

Custom:

gcalcli --nocolor search "<query>" <start> <end>

Create —

add

(one-off events)

Overlap preflight (tight, cross-calendar):
- ```
gcalcli --nocolor agenda <start> <end>
```
- IMPORTANT: do NOT add
```
--calendar
```
  here; overlaps must be checked across all non-ignored calendars.

Timed event:

gcalcli --nocolor --calendar "<Cal>" add --noprompt --title "<Title>" --when "<Start>" --duration <minutes>

All-day event:

gcalcli --nocolor --calendar "<Cal>" add --noprompt --allday --title "<Title>" --when "<Date>"

With reminders (repeatable flag):
- ```
--reminder "20160 popup"
```
  → 14 days before (20160 = 14×24×60)
- ```
--reminder "10080 popup"
```
  → 7 days before
- ```
--reminder "0 popup"
```
  → at event start
- Time unit suffixes:
```
w
```
  (weeks),
```
d
```
  (days),
```
h
```
  (hours),
```
m
```
  (minutes). No suffix = minutes.
- Method:
```
popup
```
  (default),
```
email
```
  ,
```
sms
```
  .

Create —

import

via stdin (recurrence / free/busy)

Use ONLY when

add

can't cover the need (recurring events, TRANSP, etc.). Pipe ICS directly via stdin — never write temp files.

echo 'BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
DTSTART;VALUE=DATE:20260308
SUMMARY:Event Title
RRULE:FREQ=YEARLY
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR' | gcalcli import --calendar "<Cal>"

DTSTART;VALUE=DATE:YYYYMMDD

for all-day;

DTSTART:YYYYMMDDTHHmmSS

for timed.

```
RRULE:FREQ=YEARLY
```
— yearly recurrence. Also:
```
DAILY
```
,
```
WEEKLY
```
,
```
MONTHLY
```
.
```
TRANSP:TRANSPARENT
```
— free;
```
TRANSP:OPAQUE
```
— busy (default).
One import call = one event (one VEVENT block). For multiple events, run separate piped imports.
Add
```
--reminder "TIME"
```
flag(s) to set reminders (overrides any VALARM in ICS).
All import-specific flags (
```
--use-legacy-import
```
,
```
--verbose
```
, etc.) go AFTER
```
import
```
.

Delete (with post-delete verification)

Locate via agenda (preferred):

gcalcli --nocolor agenda <dayStart> <dayEnd>

(exact date)

```
gcalcli --nocolor agenda today +14d
```
(weekday)
```
gcalcli --nocolor agenda today +30d
```
(meaning only)

Delete (non-interactive, bounded):

gcalcli --nocolor delete --iamaexpert "<query>" <start> <end>

Verify (same window):

gcalcli --nocolor agenda <dayStart> <dayEnd>

Optional one retry if still present:

gcalcli --nocolor --refresh agenda <dayStart> <dayEnd>

Edit / Modify existing events

```
gcalcli edit
```
is interactive — cannot be used in non-interactive exec.
To change properties not editable in-place: delete + recreate the event.
- Locate → delete (with
```
--iamaexpert
```
  ) → create with updated properties → verify.
For bulk property changes (e.g. setting all events to free): iterate delete+recreate per event.

Google Calendar (via gcalcli)

AI Skill Market Insights

Be Part of the 0+ Developer Community

gcalcli-calendar

Rules

CLI flag placement (critical)

Output & language

Dates & formatting

Calendar scope

Agenda (today-only by default)

Weekday requests (no mental math)

Finding events: prefer deterministic agenda scan (meaning-first)

Search (bounded)

Tool efficiency

Actions policy (optimized for conversational speed)

Unambiguous actions: execute immediately

Ambiguous actions: always ask first

Create events: overlap check MUST be cross-calendar (non-ignored scope)

Choose the right create method

Deletes must be verified

Canonical commands

Agenda (deterministic listing)

Search (fallback / explicit request)

Create —
`add`
(one-off events)

Create —
`import`
via stdin (recurrence / free/busy)

Delete (with post-delete verification)

Edit / Modify existing events

Quick Start

Manual Installation

TEAR & SHARE

Tags

README

OpenClaw WhatsApp

Gotify

Reflect Notes

Farcaster Agent

Channels

Learn

Compare

Company