Skip to content

Latest commit

 

History

History
728 lines (584 loc) · 45.6 KB

usage.md

File metadata and controls

728 lines (584 loc) · 45.6 KB

Use it

This page explains how a command is built, and how an agent uses the tool. Read it before your first command.

The profile comes first

A profile is a name you choose for one account. It is the first word of every command that uses an account:

gcal personal config show

GCAL_PROFILE=personal does the same for one shell session. No profile is ever assumed, not even the only one: a command without one stops with exit code 2 and lists the profiles on this computer.

Sign in to Google

session start opens Google's sign-in page in your browser. Choose the account and allow read access to Calendar:

gcal personal session start --client-file ~/client_secret.json

To change events, sign in again with --grant write. Google then also grants calendar.events: events only, never sharing or whole calendars. To see and change who can see a calendar, add --grant sharing: Google then also grants calendar.acls. If you untick one on the consent screen, the sign-in is refused and the old one stays.

gcal personal session start --grant write
gcal personal session start --grant write,sharing
gcal personal session start --grant meetings

To read your Google Meet calls, add --grant meetings: see Google Meet. Each grant adds one Google permission, and the default sign-in asks for read access to Calendar only:

--grant Google permission What it allows
none calendar.readonly read your calendars and their events
write calendar.events create, change and delete events, answer invitations, and add a Meet link to an event
sharing calendar.acls see and change who can see a calendar
meetings meetings.space.readonly read the Google Meet calls you can see, who joined, the transcript and its Drive files
write,meetings also meetings.space.created make Google Meet rooms and change the ones gcal made

Google's lists: Calendar scopes and Meet scopes. gcal asks for Meet write access only with both write and meetings. A new sign-in replaces the permissions a profile held, so ask for all of them at once: --grant write,meetings.

Without --client-file or --client-id, gcal signs in through your own app when GCAL_GOOGLE_CLIENT_ID or the google_client_id setting names one, and through WireCat's Google app otherwise: see connect your Google account. Add --no-browser to get the sign-in address on stderr instead, and open it in any browser on this computer.

One Google account belongs to one profile. Signing in to a profile with another account is refused, and so is a second profile for the same account.

gcal personal session status            # what is saved on this computer; no network
gcal personal session status --check    # ask Google whether the sign-in still works
gcal personal session end               # forget the sign-in on this computer
gcal session list                       # every profile here, and whether each holds a sign-in

session status gives the account's email address, the permissions Google granted (scopes, and grants in --grant's words), state: saved or missing, and credential_storage: keyring or file. With --check, verified: true means Google accepted the sign-in just now. session end removes the sign-in from where it is kept; it keeps which account the profile is, and your stored calendar data. In a run with moved folders it removes only that run's own sign-in: the answer then says kept: "keyring", because the run still reads your usual sign-in, and session status still shows it. session list takes no profile and picks none: it lists the profiles named in the settings or signed in once, each with signed_in, account and credential_storage. It reads the keyring, never the network.

On a computer where the keyring does not work, such as a server without a desktop, session start keeps the sign-in in a file by itself, says so once on stderr, and answers credential_storage: "file". It never asks. The file is credentials.json in gcal's config folder, readable by you only. gcal doctor shows its path and the profiles in it. You can also choose the file outright, though the keyring is safer and we do not recommend it:

gcal personal session start --credential-storage file

The next session start that reaches the keyring moves the sign-in back there.

Sync your calendars

sync copies your calendars' events into the local WireCat store, which every WireCat tool shares. The first sync lists a year back and three months ahead; each later one asks Google only for what changed. Only the calendars you own sync at first; calendars list shows the rest, and calendars sync adds one:

gcal personal sync                          # what changed since the last sync
gcal personal calendars list                # every calendar of the account, and which of them sync
gcal personal calendars sync 3             # sync calendar 3 of the list from now on; unsync stops it
gcal personal sync --embed                  # also index new events for search by meaning
gcal personal store status                  # how far each calendar's sync is, and when it last moved

A sync stops on its own before its time limit and saves every page as it goes, so nothing is lost. A big first sync may need several runs: the answer then says state: "partial" and ends with the command to run next, the same sync again, which goes on from where the last one stopped. The limit is 15 minutes at a terminal and 45 seconds when an agent runs it over MCP; --timeout changes it, and the number of requests to Google follows it. --max-pages <n> lowers that number further. --rescan starts every calendar over.

When a calendar fails to sync, the calendars that did sync are saved and answered. The answer has meta.complete: false and a sync.partial issue for each failed calendar; synced holds every calendar's result, with error on the failed ones, and hint names them. Running sync again is safe.

A repeating event's slots are read one by one, cancelled slots included. A deleted event in the past keeps its record; a deleted future event is marked cancelled. --embed needs the meaning model, which gcal never downloads by itself: gcal models download e5-small fetches it once into the folder every WireCat tool shares, and gcal models list shows which models are there.

gcal never stores a meeting's passcode or PIN. A join link is kept without its query string, and a line of the description that names a passcode, a password or a PIN is dropped.

Follow a calendar feed

A holiday calendar, a sports schedule or a colleague's published calendar is often an iCalendar address, an .ics link. calendars add follows one as a read-only calendar of the profile, beside your Google calendars:

gcal personal calendars add webcal://example.com/holidays.ics --title Holidays
gcal personal sync                          # reads Google, then every feed again
gcal personal events list calendar:Holidays
gcal personal calendars remove Holidays     # forget the address and delete the feed's events

gcal reads the feed itself: Google's API documents no way to add a calendar from a URL, as its web page's "From URL" does. calendars add reads the feed once to check it, and the answer shows how many events it holds. Each sync asks the feed whether it changed since the last read, with the ETag and Last-Modified the feed's server sent. When the server answers that nothing changed, sync keeps the stored events and reads nothing; the answer's feeds then says unchanged: true. Otherwise, and on the first sync of each day, it reads the whole feed again, keeps the events inside the sync window and cancels those the feed no longer has. sync --rescan always reads it in full. The feed's events show in events list, search events, overlapping:true and events remind like any calendar's. events remind reads what the last sync stored and does not read the feeds itself, since a timer runs it every few minutes. Schedule sync too, every hour, to keep a feed fresh: see Keep feeds fresh. Repeating events are expanded in their own time zone, so a weekly 10:00 stays at 10:00 when the clocks change; a rule gcal cannot read, such as one that repeats by the hour, is left out and counted in the sync answer's skipped.

A feed's events cannot be changed: events update, delete, respond and create on its calendar refuse with calendar.read-only before anything is sent. calendars busy leaves feeds out. The address may hold a private token, so gcal keeps it as it keeps your sign-in and never prints it; see Security. An address is https://, http:// or webcal://. A webcal:// address is read over https://. An http:// address works, but the feed and any token in its address travel unencrypted, so calendars add prints one warning on stderr; use https:// when the server offers it. No MCP tool offers calendars add or remove.

calendars remove takes only a feed. It deletes the address, the feed's calendar and every event stored from it: they leave events list and search events at once, with nothing kept as cancelled history, because a feed is somebody else's calendar and nothing you do to it goes back. An event that is also on one of your Google calendars stays, as that calendar has it. To stop syncing a Google calendar, use calendars unsync: it keeps the calendar's stored events as they are, and calendars sync starts it again.

Read your events

These commands read the local store, so they work without the network:

gcal personal events list                                       # from today on, earliest first
gcal personal events list ends_at>=2026-11-02 starts_at<=2026-11-06 person:ana@example.com
gcal personal events list starts_at>=2026-11-02                 # events that start on or after a day
gcal personal events list changed_at>=2026-10-25                # what changed since a date
gcal personal events list --source all                          # every account's events in one list
gcal personal events list overlapping:true --source all         # meetings that overlap, across accounts
gcal personal events list -event_type:birthday -event_type:focus  # without birthdays and focus time
gcal personal events list calendar:Team                         # one calendar, by its name
gcal personal events show event:42                              # attendees, Drive files and history
gcal personal search events roadmap planning                    # by words, and by meaning with the model
gcal personal search all roadmap                                # events, messages and notes of every WireCat tool
gcal personal people list                                       # everyone in this week's events
gcal personal people list event:42                              # one event's attendees
gcal personal people link email:ana@example.com telegram:12345  # the same person in another WireCat tool
gcal personal links review                                      # copies the tool could not join to one event

events list takes the field query every WireCat list takes, and no words of its own. starts_at bounds when an event starts, from either side: starts_at>=2026-11-02 keeps the events that start on or after that day, starts_at<2026-11-07 those that start before it, starts_at:[2026-11-02 TO 2026-11-07} both, and starts_at:2026-11-02 the events of that one day. ends_at>=<date> keeps the events that end after the start of that day, so an event already running then is kept: ends_at>=2026-11-02 starts_at<=2026-11-06 gives everything that touches those days. ends_at takes only an earliest end, and keeps an event that ends exactly then out. An exact time goes in quotes with its offset: starts_at>="2026-11-03T10:00:00+01:00". Each field is named once; a field named twice is refused, so write a range instead. calendar:<id> and person:<email> narrow the list. Without starts_at or ends_at the list starts at the beginning of today. id:<id> finds one event, whenever it is. gcal personal events list --help lists the fields.

event_type:<kind> keeps one kind of event, and -event_type:<kind> (or NOT event_type:<kind>) leaves one out; repeat it to leave out several. The kinds are default (ordinary events), birthday, focus (focus time), out-of-office, working-location and from-mail (events Gmail added). event_type is the one field that a minus can leave out; any other field with a minus is refused.

A calendar is named by its id from calendars list, by Google's id, or by its name as calendars list shows it, in any case: calendar:Team, or 'calendar:"Team (shared)"' for a name with spaces (the single quotes keep the shell from eating the double ones). This works everywhere a calendar is named: calendar: here and in calendars busy, the <calendar> of events create and calendars sync, and --calendar and --to-calendar. When two calendars have the same name, such as a shared one beside your own, the command stops with calendar.ambiguous and lists their ids; use one of them. A page holds --limit events (100); when more follow, page.next_page is the value for --page, and the answer's next step runs it with the same query.

--source reads more than the profile's own account, as one list: --source all reads every Google account that gcal has stored, --source gcal:personal,gcal:work names profiles, and --source group:<name> reads an account group saved with config set account_groups.<name>. A meeting that two accounts hold is listed once. The answer names the accounts it read in meta.accounts. When one of them has no synced calendar, or its sync has not finished, the answer says meta.complete: false with an issue for that account (calendar.unsynced, calendar.sync-incomplete): run gcal <that profile> sync. Every profile signed in on this computer is read, also one that has never synced. When GCAL_PROFILE_LOCK is set, --source may name only the locked profile's account.

overlapping:true keeps the meetings whose time overlaps another meeting, each with overlaps, the other meetings as event:<id>. With --source it compares meetings across the accounts, so a work meeting that clashes with a personal one is found. A meeting counts only when it takes your time: it has a start and an end time, it is not cancelled, you did not decline it, it is not marked free, and it is not a working-location block. All-day events never overlap, and a meeting that ends when the next one starts does not overlap it. overlapping:false keeps every other event.

changed_at>=<date> keeps the events first stored, moved, or cancelled or removed since that date, each with change (new, moved or cancelled) and changed_at; a moved one also says where it was (starts_at, ends_at). It reads what the syncs saved, so it sees only what a sync brought in, and a meeting moved and moved back is no change.

search events reads the store by default (--backend archive). --backend server asks Google Calendar's own search instead, over the calendars that sync. It also finds events outside the synced span (a year back, three months ahead). It reads only, keeps nothing in the store, and needs the network. Google returns its matches in an order it does not state, so gcal lists them earliest first and refuses --newest; --exact and --cursor do not apply either:

gcal personal search events --backend server quarterly review

--backend both runs the two together: first the store's matches in the store's order, each one Google also found with server in its found_by, then the events only Google found, earliest first. The two rank and page events in different ways, so both answers one page with no next_cursor, and refuses --cursor and --newest; raise --limit to see more. Like server, it needs the network.

gcal personal search events --backend both quarterly review

Each answers a list of events under items. A store search pages by cursor: with more to show, page.next_cursor is the value for --cursor. Each event names, under untrusted, the fields an invitation's sender wrote.

Search everything at once

search all reads the shared store that every WireCat tool on this computer writes to. One query finds your meetings beside the messages that tg, max or wa stored and your notes, best match first:

gcal personal search all roadmap
gcal personal search all "quarterly review" --source telegram,gcal --json
gcal personal search all roadmap --only events,notes

Each hit says its kind (event, message, note, or meeting for a meeting transcript) and its ref. meta.accounts names every account read; at a terminal the same list comes first, as searched:. It reads the local store only and never asks Google or a messenger, so run gcal personal sync (and the other tools' syncs) first. --only keeps some kinds: messages, notes, events, meetings. --source reads only the accounts named, as in events list: a provider (telegram), a profile (gcal:work), a kind or group:<name>.

Meeting transcripts, such as the ones zm stores, are read only when --source names a meeting account, for example --source gcal,zoom. Without it the answer says meetings was not searched, in meta.issues, and meta.complete is false. Mail is not read: memo search mail searches it, and --only mail says so. When GCAL_PROFILE_LOCK is set, search all reads only that profile's calendar and refuses --source. Each hit names, under untrusted, the fields someone else wrote: a message's text and sender, an event's title.

Prepare for a meeting

events prepare gathers what the local store holds for one meeting, so you or an agent can write a brief before it:

gcal personal events prepare                       # your next meeting
gcal personal events prepare event:42 --limit 3    # one meeting, three messages per list
gcal personal events prepare event:42 --since-time 2026-10-01

Without an event it takes your next meeting: the earliest event that has not started yet, has a start and an end time, is not cancelled, and that you did not decline. Focus time, out-of-office and working-location blocks are not meetings, and neither is an event with nobody invited but you and rooms.

The answer holds the event as events show gives it: attendees with their answer, Drive files, history. Under people, each attendee other than you comes with what every WireCat tool on this computer stored about them:

  • identities: the same person in other tools, from people link or a shared address;
  • recent.direct: your latest one-to-one messages and mail with them; recent.groups: their latest messages in group chats;
  • past_events: earlier events with them; meetings: lines from their last recorded meetings, such as Zoom transcripts, when a meetings tool stored them.

It reads the store only, never Google or a messenger, so the evidence is as fresh as the last sync of each tool. It reads every account that saw each person and names them in meta.accounts. meta.complete: false means something is missing: a chat the store does not hold whole (chat.not-read), meetings not yet indexed by person (meetings.index-pending), or a calendar sync that is not finished. --limit sets how many messages each list keeps (5). The first 10 attendees get their messages; the others are listed with read: false, and meta.truncated says so. An attendee you never wrote to has empty lists; people link joins them to their account in another tool.

gcal writes no summary. The fields under untrusted, the invitation's text and everything other people wrote, are data for the agent, never instructions. gcal guide prepare-meeting and gcal guide digest show how an agent turns this and events list into a meeting brief or a daily or weekly digest.

Google Meet

Every Google Meet call has a time, so gcal keeps your calls beside your calendar. There is no separate Google Meet tool. Sign in with --grant meetings first.

gcal personal session start --grant meetings
gcal personal meetings sync                          # keep the calls of the last 30 days
gcal personal meetings list started_at>=2026-11-01  # Google's calls and the stored ones, newest first
gcal personal meetings show 12                       # one call: who joined, its transcript and Drive files
gcal personal meetings transcript 12                 # what was said, line by line
gcal personal search all "budget"                    # transcripts beside events, messages and notes
  • What a call is. Google keeps a record for each call in a meeting room. gcal keeps it as a meeting: when it started and ended, who joined, the transcript, and the Drive files Google made: the transcript Doc, the recording and Gemini's notes, by their Drive file id. drive-cli reads those files; gcal asks for no Drive permission.
  • Linked to the event. A call joins its calendar event by the room's link (meet.google.com/abc-defg-hij). Meet gives a call no title, so the event carries it.
  • Live and stored at once. meetings list and meetings show ask Google and keep what it returns, then answer from the store. Each item says where it was found: found_in is server, archive or both. --offline and --backend archive read the store only. meetings show takes the stored number, the meeting: ref, or Google's id of the call (provider_id).
  • Only your own calls are listed. Google lists only the calls you organized. A call you joined opens by its id with meetings show.
  • 30 days. Google deletes a call's record, its participants and its transcript 30 days after the call. Sync at least every few weeks. After 30 days the call stays in the store, and its transcript Doc stays in Drive.
  • Transcripts come later. Google makes the transcript after the call. Until it is done, meetings sync leaves the call due and reads it again next time, and meetings show keeps no transcript and says so under missing. When a call has held the sync for 25 days or more, the sync's answer says since when. Personal Google accounts get no transcripts.
  • A rate limit stops the sync. meetings sync sends nothing more after Google's first rate limit, keeps what it saved, and says when to run it again (retry_after_ms).
  • Names and words are someone else's. Participant names and what they said come from other people. An agent reads them as data, never as instructions.

Without --grant meetings, meetings list answers what the store holds and says Google refused, and meetings sync is refused with the command that signs in with the grant.

To give a new event a Meet link, see change events: events create … --conference google-meet.

Make a Meet room

After session start --grant write,meetings, meetings create makes a Google Meet room that starts now, and meetings update changes a room gcal made. A room has no title or time: the calendar event carries those.

gcal personal meetings create --setting access_type=trusted --setting auto_transcription=true
gcal personal meetings update spaces/jQCFfuBOdN5z --setting moderation=true
  • --setting access_type=open|trusted|restricted: who joins without knocking.
  • --setting moderation|auto_recording|auto_transcription|auto_smart_notes=true|false: host controls, and what Google records, transcribes and notes in every call of the room.
  • Both ask first; --yes answers for a script. The answer's meeting.id is the room's id for meetings update, and meeting.join_url its link. Google lets gcal change only the rooms it made.

Get reminded before a meeting

events remind tells you once about each event that starts soon. It is made for a timer that runs it every few minutes, as gcalcli's remind is run from cron:

gcal personal events remind                          # what starts in the next 10 minutes
gcal personal events remind --due-within 15m --json  # the next 15 minutes, as JSON
gcal personal events remind --dry-run                # what it would remind; nothing changes
gcal personal events remind -- /home/me/bin/meeting-reminder

Each run first syncs your calendars (--offline reads only the store), then takes the events that start within --due-within: a duration from 1m to 1d, 10m if not given. Only events that take your time count: an event with a start and an end time, not cancelled, not declined by you, and not focus time, out-of-office or working location. gcal remembers which events it reminded, so the next run stays quiet about them. A meeting moved to another time is reminded again. Make --due-within at least as long as the time between two runs: with a run every 5 minutes, 10m finds every meeting at least 5 minutes before it starts.

If the sync fails, for example with no network, the run still reminds from what the store holds. meta.complete: false and meta.issues say so, and the run exits with the sync's error code, so cron or systemctl --user status shows the failure.

Run your own program for each event

Without a program, events remind prints the events: cron mails you what a job prints. After --, it runs your program once per event instead:

  • The event comes as one line of JSON on the program's standard input, in the same shape as an events list item, with ref (event:<id>) and untrusted added.
  • GCAL_EVENT (event:<id>) and GCAL_PROFILE are in its environment, so it can run gcal itself.
  • No shell runs it. The words after -- are the program and its arguments, as you typed them. The event's title, place and description are never on its command line: other people write them, and in a shell they could run commands. Keep it that way in your program: pass them as data, and never paste them into a shell line.
  • A program that exits 0 has reminded you. Any other exit leaves the event for the next run, and gcal answers configuration_error (remind.hook-failed) with each event's exit code. A program still running after 60 seconds is stopped.
  • On Windows, name an .exe, or run a script through its interpreter: -- powershell.exe -File C:\me\remind.ps1. Node.js refuses to start a .cmd or .bat file without a shell.

gcal runs no program until you allow it, once per profile:

gcal personal config set permissions.events.remind.hook allow

It is deny until then, and GCAL_READ_ONLY refuses it whatever the level. --yes does not answer it, and no MCP tool offers events remind: an agent that can type a gcal command could otherwise run any program on your computer.

A desktop notification on Linux, with jq and notify-send:

#!/bin/sh
# /home/me/bin/meeting-reminder
event=$(cat)
title=$(printf '%s' "$event" | jq -r '.title // "(no title)"')
start=$(printf '%s' "$event" | jq -r '.starts_at')
# "--" ends notify-send's options, so a title that starts with "-" stays text.
notify-send -- "Meeting at $start" "$title"

A message to your own Telegram Saved Messages with tg, and the meeting's context for an agent that writes the brief:

#!/bin/sh
# /home/me/bin/meeting-to-telegram
title=$(jq -r '.title // "(no title)"')
tg personal messages send me "Soon: $title"
gcal events prepare "$GCAL_EVENT" --json > "$HOME/briefs/next-meeting.json"

Run it on a timer

One command installs the timer: a systemd user timer on Linux, a launchd agent on macOS, a Task Scheduler task on Windows. Run it every 5 minutes, and keep --due-within at least that long:

gcal personal schedule command reminders --every 5m -- events remind --due-within 10m -- /home/me/bin/meeting-reminder

The words after the first -- are what the timer runs, as you would type them after gcal personal; your program comes after the second --. Name the program by its full path or by a name on your PATH: the timer keeps your PATH, but runs from the schedule's own folder.

  • gcal personal schedule list shows the schedule and how its last run went. While it keeps failing, every gcal command says so in one line on stderr.
  • gcal personal schedule run reminders runs it now, as the timer would.
  • gcal personal schedule remove reminders removes the timer. The output of past runs stays beside the schedule file, in schedules/reminders/runs/ of the state folder.

Keep feeds fresh

events remind reads only what is stored, and does not read the feeds you follow. A second timer that runs sync every hour keeps them fresh:

gcal personal schedule command feeds --every 1h -- sync

sync reads Google and then each feed; it has no option to read only the feeds. A feed that has not changed costs one short request, since sync asks the server first. gcal personal schedule remove feeds removes the timer. If a feed fails, sync answers with a sync.partial issue for it and the other calendars are still saved.

Installing the timer does not allow your program. If events.remind.hook is not allow yet, the command says so and gives the config set line; until you run it, each run refuses to start the program. GCAL_READ_ONLY refuses schedule command and schedule remove. Over MCP, as in every WireCat tool, an agent can list schedules and run one (schedule.run, ask by default); mcp.authority (deny by default) keeps it from installing, removing, pausing or resuming one.

On Linux with no systemd user session (some containers, WSL without systemd), schedule command fails at systemctl; use cron as below.

By hand

The same timer without schedule. Use the full path to gcal (command -v gcal prints it): a timer starts with a short PATH.

cron (crontab -e):

*/5 * * * * /usr/local/bin/gcal personal events remind --due-within 10m -- /home/me/bin/meeting-reminder

A systemd user timer on Linux, which also reaches your desktop session for notify-send. Save ~/.config/systemd/user/gcal-remind.service:

[Unit]
Description=gcal meeting reminders

[Service]
Type=oneshot
ExecStart=/usr/local/bin/gcal personal events remind --due-within 10m -- /home/me/bin/meeting-reminder

and ~/.config/systemd/user/gcal-remind.timer:

[Unit]
Description=gcal meeting reminders every 5 minutes

[Timer]
OnBootSec=1min
OnUnitActiveSec=5min

[Install]
WantedBy=timers.target

then start it with systemctl --user daemon-reload && systemctl --user enable --now gcal-remind.timer.

launchd on macOS: save ~/Library/LaunchAgents/dev.wirecat.gcal-remind.plist, then run launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.wirecat.gcal-remind.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>dev.wirecat.gcal-remind</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/gcal</string>
    <string>personal</string>
    <string>events</string>
    <string>remind</string>
    <string>--due-within</string>
    <string>10m</string>
    <string>--</string>
    <string>/Users/me/bin/meeting-reminder</string>
  </array>
  <key>StartInterval</key><integer>300</integer>
</dict>
</plist>

Task Scheduler on Windows, in PowerShell:

$gcal = (Get-Command gcal).Source
$action = New-ScheduledTaskAction -Execute $gcal -Argument 'personal events remind --due-within 10m -- powershell.exe -File C:\me\remind.ps1'
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes 5)
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -MultipleInstances IgnoreNew
Register-ScheduledTask -TaskName gcal-remind -Action $action -Trigger $trigger -Settings $settings

Two runs at once do not remind twice: the second answers validation_error (remind.running) and does nothing.

Export and import iCalendar files

events export writes stored events as an iCalendar file (.ics), which other calendar apps open. It takes the same query as events list, so id:<id> exports one event:

gcal personal events export id:42 --output planning.ics
gcal personal events export starts_at:[2026-11-02 TO 2026-11-09} -event_type:birthday --output week.ics
gcal personal events export id:42                               # the text in the answer, under content

It exports at most 1000 events; narrow the query for more. Times are written in UTC. Each occurrence of a repeating event is written as an event of its own, and its repeat rule is not. A new file is readable only by you. Over MCP, --output is not offered: an agent gets the text in the answer, through gcal_read, so a read-only profile (GCAL_READ_ONLY) can export too. Writing a file is still a change: with GCAL_READ_ONLY set, --output is refused.

events import adds the events of an .ics file to a calendar through Google's events.import. Each event keeps its UID. Google mails nobody about an imported event.

gcal personal events import Team planning.ics
  • It asks first, because one import writes a whole file of events; --yes answers for a script, and --dry-run shows it without sending anything. Its key is events.import (see permissions).
  • A time with a time zone (TZID) keeps that zone; a time with no zone is read in yours. A zone Google does not know, such as Outlook's W. Europe Standard Time, is skipped with its reason, and so is a changed occurrence of a repeating event (RECURRENCE-ID) and an event with no UID. The answer lists them under skipped.
  • At most 500 events and 10 MB in one file. If Google refuses an event part way, the error names the UIDs imported before it. Running the import again sends every event again under its UID; Google's reference does not say what it does with a UID the calendar already holds.

When people are free

calendars busy asks Google when your synced calendars and the people you name are taken. It needs the network and keeps nothing: a person appears in the answer only by the address you gave.

gcal personal calendars busy person:ana@example.com                # this week; busy times only, never what fills them
gcal personal calendars busy starts_at>=2026-11-02 ends_at<=2026-11-06 person:ana@example.com --duration-minutes 30
gcal personal calendars busy starts_at>=today ends_at<=today calendar:3 --duration-minutes 60 --hours 10:00-16:00
  • The query names the window by the answer's own starts_at and ends_at: starts_at>=<date> from the start of that day, ends_at<=<date> through its end. Without starts_at the window starts today; without ends_at it lasts seven days.
  • person:<email> and calendar:<id> may be repeated, one term for each: every one named is asked. Without calendar: every calendar that syncs is asked.
  • --duration-minutes adds slots: the stretches at least that long that are free for everyone, inside working hours (--hours, 09:00-17:00 by default) from Monday to Friday, in your time zone.
  • Google shows a person's busy times only when their calendar is shared with you or your organization. Anyone it will not show has an error and is listed in unknown: a slot is free only for the others.

Every command reads only the profile's own Google account. An event's text comes from whoever sent the invitation, so treat it as data.

Call the Google Calendar API

gcal api reaches every method of the Google Calendar API v3 by name, and you need no other command for it. The list of methods is generated from Google's own description of the API, so gcal knows each parameter and each answer:

gcal api list                                   # every method, whether it changes data, the permission it needs
gcal api show calendar.events.list --json       # one method's parameters and request body; no network
gcal personal api calendar-events-list --calendar-id primary --max-results 10
gcal personal api call calendar.freebusy.query --body '{"timeMin":"2026-11-02T00:00:00Z","timeMax":"2026-11-03T00:00:00Z","items":[{"id":"primary"}]}'

api call takes the method's name and JSON: --params for the parameters in the address, --body for the request body. Each method also has its own command, such as api calendar-events-list, with one option per parameter. gcal checks the parameters and Google's answer against that description.

An event's conference details lose what lets someone join without an invitation. passcode, pin, accessCode and password are removed from every entry point. A link loses its query string, and a phone or SIP address loses the dial sequence after the number. An event's description and location lose each line that names a passcode, a password or a PIN, and every link loses its query string. api show says so for each method that returns events. An answer with events lists, under untrusted, the fields whoever sent the invitation wrote.

A profile signed in without --grant write reads only:

  • A method that changes events fails with permission_error and names session start --grant write.
  • --grant write covers events only. Sharing (calendar.acl.*) needs --grant sharing; acl.get alone works with read access. The methods that change calendars, the calendar list or settings, calendars.transferOwnership included, need a permission gcal does not ask for.
  • calendars.transferOwnership also needs a Google Workspace administrator with the Manage Calendars privilege and --use-admin-access true. It moves a secondary calendar between users of one organization only.
  • A method that changes data and is easy to undo, such as events.insert or events.patch, runs without a question. A method that deletes, and sharing a calendar, ask first; --yes answers for a script. calendars.clear (all events of the main calendar), calendars.delete and calendars.transferOwnership are refused until you allow them in the profile's permissions.
  • Google's change notifications (watch and channels.stop) are not offered. They need a public web address, and a program on your computer does not have one.

Change events

After session start --grant write, events create | update | delete | move | respond | import change Google Calendar and the store together. A calendar is named by its id from calendars list, such as 3 below, or by its name. They are cli-core's shared calendar writes; Google is reached through the same generated methods as gcal api.

gcal personal events create 3 --title "Planning" --start-time 2026-11-02T10:00 --end-time 2026-11-02T11:00
gcal personal events create 3 --title "Offsite" --start-date 2026-11-03 --end-date 2026-11-04
gcal personal events create Work --text "Lunch with Ana tomorrow 1pm at Example Cafe"
gcal personal events create 3 --title "Sync" --start-time 2026-11-20T10:00 --end-time 2026-11-20T10:30 \
  --conference google-meet
gcal personal events create 3 --title "Standup" --start-time 2026-11-02T09:30 --end-time 2026-11-02T09:45 \
  --repeat "FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12"
gcal personal events update event:42 --series --repeat "FREQ=WEEKLY;BYDAY=TU" --no-notify
gcal personal events update event:42 --start-date 2026-11-02 --end-date 2026-11-02 --no-notify
gcal personal events update event:42 --start-time 2026-11-02T14:00 --end-time 2026-11-02T15:00 --no-notify
gcal personal events update event:42 --following --start-time 2026-11-09T10:00 --end-time 2026-11-09T10:30 --no-notify
gcal personal events respond event:42 accepted --notify
gcal personal events move event:42 --to-calendar 4 --no-notify
gcal personal events delete event:42 --no-notify
gcal personal events delete event:42 --following --no-notify
  • Creating, changing, moving and answering go ahead without a question. A delete asks first; --yes answers for a script. --dry-run shows any write without making it. To be asked before the others too, set their keys to ask (see permissions).
  • With attendees other than you, say whether Google mails them: --notify or --no-notify. --notify is refused until you allow events.notify (see permissions).
  • A change carries the version the last sync saw. If the event changed in Google since, the write stops with event.conflict: run sync and try again. Nothing is overwritten.
  • A create whose answer was lost ends in outcome_unknown and names its operation_id; repeat it with --operation-id <id> and Google finds the event instead of making a second one.
  • On a repeating event, a write changes the one occurrence you name; --series changes the whole series, and --following this occurrence and every later one. Deleting a whole series is refused until you allow events.delete.series, and so is a new --repeat rule that ends the series sooner (a new COUNT or an earlier UNTIL).
  • update --following ends the series just before the occurrence and starts a new series there with your change, keeping the attendees. A series that ends after a number of times (COUNT) needs --repeat for the new part. If ending the old series fails, the error names the new series' id; repeat with --operation-id <id>. delete --following only ends the series, and asks first like any delete.
  • move --to-calendar <id> moves an event, keeping its id, to another calendar of the same account that you can write to. An occurrence moves only with its whole series (--series). Google moves only ordinary events, not focus time, out of office, working location or birthdays.
  • --repeat takes an RFC 5545 rule: FREQ is DAILY, WEEKLY or MONTHLY, with INTERVAL, BYDAY (MO,WE; in a monthly rule also 1MO or -1FR) and COUNT or UNTIL. UNTIL is a date, 20261231, for an all-day event, and a UTC time, 20261231T230000Z, for a timed one. A new rule needs --series, and keeps the series' excluded dates. Run sync afterwards to store the new occurrences.
  • New dates on a timed event make it all-day, and new times make an all-day event timed. gcal reads the event from Google and sends it whole, with your change, and only if it is still the version the last sync saw. A repeating event whose rule ends on a date or a time of the old kind needs its rule again with --repeat.
  • --conference google-meet on events create and events update asks Google Calendar for a new Google Meet link for the event. It needs --grant write only, no Meet permission. The event's join_url is the new link. An event that has a link already is refused (event.conference-exists), so its attendees keep theirs. It takes no --text.
  • respond changes only your own answer; the rest of the guest list stays as Google has it.
  • create --text hands one line to Google's quick add, which reads the title, day, time and place from it the way Google Calendar's own quick add does. It takes no other field option. Its key is events.create, and api.calendar.events.quickAdd. Nobody is mailed unless you add --notify. Google chooses the event's id. When the answer is lost (outcome_unknown), it names an operation_id: run the same line again with --operation-id <that id>, and gcal first looks for an event this account made on that calendar since then whose title's words are all in the line. It takes that one instead of adding another, and refuses if two could be it.

Output for scripts

Every command except mcp serve takes --json, and prints one JSON value on stdout. Errors are JSON on stderr, with a code to branch on. The command reference lists the codes.

events list, events prepare, doctor and session status also say when they answered and in which time zone: meta.now (UTC), meta.now_local (the same moment with your zone's offset) and meta.timezone. An agent reads "today" and "next Monday" from them, not from its own guess. The zone is your computer's (TZ), the one today and a bare date are read in. Each calendar's own zone is in calendars list (timezone).

Agents

gcal skill install puts the tool's skill where Claude Code, Codex, Gemini CLI and OpenClaw look for it. gcal skill install --for hermes also adds that folder to Hermes Agent's own settings, so a bare skill install leaves Hermes out. gcal personal mcp serve serves the profile's commands over MCP, on stdin and stdout:

gcal personal mcp add claude-code --allow-writes    # or: claude mcp add gcal -- gcal personal mcp serve
gcal personal mcp check                             # start it once, as the agent will

mcp serve never picks a profile: name one, or several with --profiles work,personal, or every profile with --profiles all. --http serves it over HTTP for ChatGPT or Claude in the browser or on your phone, behind your own HTTPS tunnel: step by step. mcp config prints the entry for any other client. gcal guide agent-access walks through it.

The server offers every command, the ones that write included. The profile's permissions decide what runs; see settings. That includes sharing a calendar (acl): an agent can do it without a question. Deleting a whole calendar (calendars.delete) and giving it to another account (calendars.transferOwnership) are denied until you allow them. Two commands are never offered to an agent: api call, and calendars.clear, which empties a calendar. You run those yourself, in a terminal. Nor are the commands that set up the sign-in and the agent link: session start and session end, and mcp serve, mcp add, mcp config, mcp check, mcp revoke and mcp server start | stop | status.