Connect Google Calendar¶

This guide stores a read-only Google Calendar grant for Bob. Bob talks to Google only through gog (≥ v0.44.0) under an isolated --client bob-gcal token bucket, so removing Bob's grant never touches Gmail. Tests and this page use you@example.com; do not paste a live client secret into a log or ticket.

list and sync arrive in a later release. This page gets you to bob gcal doctor all-clear and a calendar id list for config.

Before you start¶

Install the CLI, install gog ≥ v0.44.0 on PATH, and point Bob at your vault. Add a gcal: block to ~/.config/bob/config.yml (or $BOB_CONFIG_FILE):

gcal:
  account: you@example.com
  root: meet
  calendars:
    - id: primary
  timeout_secs: 60

account is optional when gog already holds exactly one Google account. A missing gcal: block uses those defaults.

1. Create a Desktop-app client¶

In Google Cloud Console:

1. Enable the Calendar API at calendar-json.googleapis.com.
2. Set the OAuth consent screen to External and In production. Unverified is fine for personal use. Leave the screen in Testing and tokens expire in 7 days (invalid_grant); publish, then run bob gcal login again.
3. Create an OAuth client of type Desktop app and download the JSON.
4. Run bob gcal login -c PATH with that file.

If gog already stores another client, bob gcal login on a TTY offers Reuse gog client 'default' for Calendar? [Y/n] instead of -c.

2. Sign in¶

bob gcal login -c ~/Downloads/client_secret.json
bob gcal doctor -b /path/to/vault

login opens a browser for read-only Calendar consent (calendar.readonly). Over SSH, the browser cannot open: rerun with bob gcal login -m and paste the redirect URL. When SSH_CONNECTION is set without -m, login prints that hint and continues.

A valid grant is idempotent: login reports already connected and only re-lists calendars.

Confirm every doctor check is ok or an explained skip. Exit 2 with the four-step checklist means no bob-gcal client is stored. Exit 1 on doctor is a failed check; the fix: line names the next command.

3. Copy calendar ids into config¶

bob gcal calendars

The table shows id, name, access role, colour, whether Bob will sync it, and the mapped root. Put those ids under gcal.calendars. primary matches the account's primary calendar.

4. Preview, then run the first sync¶

bob gcal sync -d
bob gcal sync

The preview prints the exact unified diff of the plan and writes nothing. The write adds a ## Events section above ## Pomodoros, one row per accepted event in time order, plus a () — MEET placeholder carrying a link per unended meeting. Meetings that already ended arrive as [ ] rows with no link; later meetings arrive [*] and linked. Run bob gcal sync again to confirm the second run is byte-identical and appends nothing, then bob gcal doctor to see the last sync check go green.

5. Remove the grant¶

bob gcal logout -y

That removes only the bob-gcal token. Then revoke Bob's Calendar access at myaccount.google.com/permissions. Without -y, logout asks for confirmation on a TTY.

If it goes wrong¶

Exit 2 is setup (clap, config, missing gog, no client, not logged in). Exit 1 is runtime (network, timeout, token, or a doctor failure).

Related¶

• Bob Gcal
• bob gcal
• Configuration