Gog

OpenClicky compatibility guardrails

• Follow ../_shared/OpenClickySkillCompatibilityPolicy.md before acting.
• Verify required local commands, tools, keys, or bridge endpoints before promising execution.
• Treat sends, publishes, deploys, deletes, moves, merges, playlist/library changes, cloud writes, and app-control clicks as external writes unless this skill narrows them further.
• Stop and report the exact missing setup step for unavailable tools, auth, or macOS permissions; do not loop or silently switch to browser automation.

gog

Use gog as OpenClicky's primary local Google Workspace CLI for Gmail, Calendar, Drive, Docs, Sheets/spreadsheets, Google Workspace automations, Chat, Contacts, Tasks, People, Forms, Slides, Apps Script, Groups, Admin, and auth/account inspection.

Prefer gog over browser automation for normal Google Workspace requests. Do not open or automate Gmail, Calendar, Drive, Docs, or Sheets in the browser unless gog cannot cover the requested action, the user explicitly asks for visible browser UI, or the user is already signed into a visible Google web app and the local connector is unavailable.

Do not use gog for Google Cloud/GCP, Google Ads, generic Google Search, or public web research. Those are not Google Workspace surfaces.

Local sources

• CLI: gog
• Homebrew path: /opt/homebrew/bin/gog
• Config: ~/Library/Application Support/gogcli/config.json
• Credentials: ~/Library/Application Support/gogcli/credentials.json
• File keyring tokens: ~/Library/Application Support/gogcli/keyring/

Treat gog credentials and keyring data as user-local secrets. Do not print tokens, export tokens, commit credentials, or ask the user to paste OAuth secrets.

Auth

Inspect auth before assuming Google Workspace is blocked:

gog --json auth status
gog --json auth list --check

If the file-keyring backend asks for a passphrase, stop and report that gogcli needs its local keyring passphrase available to OpenClicky as GOG_KEYRING_PASSWORD, usually in ~/.config/openclicky/secrets.env, or the user should migrate gogcli to the macOS Keychain backend. Do not spin or keep retrying.

If no usable account is authenticated, stop the gog route. Do not run gog auth add, gog auth credentials, or OAuth setup from an agent task unless the user explicitly asks for setup help. Google sign-in/setup belongs in OpenClicky Settings -> Google.

Do not claim OAuth client credentials are missing until you have checked both:

gog auth status --json
gog auth credentials list --json

If Google OAuth says the app is "Clicky", that comes from the local gogcli OAuth client stored at ~/Library/Application Support/gogcli/credentials.json. OpenClicky is using the same local gogcli store, not a separate hosted login. The fix is to replace gogcli's OAuth client with an OpenClicky-owned Desktop OAuth client, then re-auth when the user explicitly wants setup.

gog auth status may not report credentials correctly in every local state; credentials list is the more direct check.

Use --json for scriptable output and --dry-run for write planning where supported.

Live command rule

Use the installed gog help as the source of truth. Do not rely on stale command examples from older gogcli builds. If a command fails with "expected one of", immediately run the parent help, e.g. gog gmail messages -h, then retry with one of the listed subcommands.

Important gog 0.12 command shapes:

• Thread search: gog gmail search <query> ...
• Message search: gog gmail messages search <query> ...
• Message get: gog gmail get <messageId>
• Thread get: gog gmail thread get <threadId>
• Labels: gog gmail labels list
• Calendar events list: gog calendar events (not calendar events list)
• Calendar event get: gog calendar event <calendarId> <eventId>
• Drive search/list: gog drive search <query> ..., gog drive ls
• Contacts search/list: gog contacts search <query> ..., gog contacts list

Common reads

gog --json gmail search "newer_than:7d" --max 10 --account auto
gog --json gmail messages search "from:example@example.com newer_than:30d" --max 10 --account auto
gog --json gmail get MESSAGE_ID --account auto
gog --json gmail thread get THREAD_ID --account auto
gog --json gmail labels list --account auto
gog --json calendar events --today --account auto
gog --json calendar events --days 7 --account auto
gog --json calendar search "project sync" --account auto
gog --json drive search "name contains 'deck'" --account auto
gog --json drive ls --account auto
gog --json contacts search "Name" --account auto

For large results, use max/filters first. Summarize results instead of dumping huge JSON.

Gmail send safety

Default to read-only behavior. If the user asks to send email:

1. Draft first.
2. Show account, recipient, subject, body summary, and attachments.
3. Require explicit approval of that exact draft.
4. Only then send if the account already has Gmail send permission.
5. If send permission is missing, stop and say OpenClicky's Google connection needs Gmail send permission in Settings. Do not run OAuth from the agent.
6. Never report Gmail send success from exit code or a generic success boolean alone. Confirm the returned message/thread id, or read back the sent message when the command exposes enough information.

Keep GOG_GMAIL_NO_SEND=1 as the default guard where it is set. Bypass it only for one exact approved send command:

env -u GOG_GMAIL_NO_SEND gog --json gmail send --account "$GOG_ACCOUNT" --to "recipient@example.com" --subject "Subject" --body-file /path/to/approved-body.txt

Write safety

Do not send email, create/update/delete Drive files, change calendar events, share Drive files, post Chat messages, modify contacts, or change Workspace admin state unless the user explicitly asks. For writes, summarize the target account and intended mutation first unless the user already gave a concrete command.

After writes, verify by re-reading, exporting, or listing the changed item when possible. For Docs, confirm the intended body is present, not just that a title exists. For Sheets, confirm headers, row count, column count, and at least one representative cell. When replacing content that may be shorter than the old sheet contents, clear the old range first when gog exposes that command, or write to a fresh tab/file.

Fallbacks

• If gog is not installed or not authenticated, say exactly what is missing and stop the Google API route.
• Use browser/Computer Use only for a visible UI task, a gog coverage gap, or an already-open signed-in Google web app when the local connector is unavailable.
• Do not loop on the same blocked Google command.

Smoke commands

gog --version
gog --json auth status
gog auth credentials list --json

Mutation safety boundary

Use gog for Google Workspace read/search/list/get routes first. Edits, calendar creates/updates, label changes, contact changes, and task mutations the user explicitly asked for execute directly — the request is the approval. Require explicit approval immediately before execution ONLY for mail sends, chat posts, shares/permission changes, deletes, overwriting content the user did not ask you to replace, and spending money.

If the local command shape differs from this document, use installed gog -h output as source of truth and update the skill later rather than repeating stale commands.