Menu
gog CLI: safe Google Workspace automation, JSON, auth, scoped reads/writes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
| name | gog |
| description | gog CLI: safe Google Workspace automation, JSON, auth, scoped reads/writes. |
Use gog when built-in Google connectors are missing a feature, when shell
automation needs stable JSON, or when you need to inspect local Google auth
state before acting.
gog --version
gog auth list --check --json --no-input
gog auth doctor --check --json --no-input
gog schema --json
gog has no separate agent mode. Its machine output, non-interactive behavior,
stable exit codes, command guards, and untrusted-content wrapping apply across
the CLI. Root help summarizes the human contract; schema exposes command
syntax, stable exit codes, and effective safety state for automation.
For JSON output projection, --fields is accepted as an alias for --select on
commands that do not define their own API field-mask --fields; commands with a
local field-mask flag keep that command-specific meaning.
Pick the account explicitly for API work:
gog --account user@example.com gmail search 'newer_than:7d' --json --wrap-untrusted
Prefer --json --wrap-untrusted for agent parsing when reading Google content.
Human hints and progress should stay on stderr; stdout is for data.
GOG_KEYRING_PASSWORD is provided by a shell startup file or service
environment, use the matching shell/entrypoint so gog can unlock the file
keyring non-interactively. Do not print the value.GOG_KEYRING_BACKEND=file, GOG_KEYRING_PASSWORD, and HOME must be
present in the process that launches gog.--no-input in automation so auth/keyring prompts fail clearly.--dry-run first where commands support it.--force; do not add it unless the user asked
for that exact mutation.--gmail-no-send or GOG_GMAIL_NO_SEND=1 unless sending mail is the
requested task.docs/safety-profiles.md.Runtime command guards:
gog --enable-commands gmail.search,gmail.get --gmail-no-send \
--account user@example.com gmail search 'from:example@example.com' --json
gog --enable-commands drive.ls,docs.cat --disable-commands drive.delete \
--account user@example.com drive ls --max 10 --json
OAuth setup is partly interactive. An agent can inspect and diagnose it, but a human normally completes browser consent:
gog auth credentials list
gog auth add user@example.com --services all-user --force-consent
gog auth remove user@example.com
Default for existing human/user OAuth reauth: preserve broad service access.
Before reauth, run gog auth list --check --json --no-input and inspect the
account's existing services. When replacing an expired or revoked token, do
not silently reduce scope; prefer --services all-user --force-consent unless
the user explicitly asks for narrower scopes.
Use narrow services only for throwaway/test accounts, service-specific bot
accounts, explicit user requests, or scoped security experiments. Safety should
normally be enforced at command time with --enable-commands,
--disable-commands, --gmail-no-send, dry-runs, and account selection, not by
under-scoping durable user auth.
Service accounts are Workspace-only and mainly fit Admin, Groups, Keep, and
domain-wide delegation flows; they do not solve consumer @gmail.com OAuth.
For OpenClaw/systemd setups, run the diagnostic through the actual agent entrypoint after restarting the service:
openclaw agent --agent main --message \
'Run: gog auth doctor --check --no-input && gog gmail search "newer_than:1d" --max 1 --json'
If this fails with keyring.password while the same gog auth doctor works in
the shell, fix the service or agent environment before reauthenticating.
Remote Mac OAuth pattern:
gog auth add user@example.com --services all-user --force-consent --timeout 15m.open -a "Google Chrome".zsh -lc and paste it into tmux without printing it.zsh -lc 'gog auth list --check --json --no-input'.gog --account user@example.com gmail search 'newer_than:3d' --max 10 --json --wrap-untrusted
gog --account user@example.com gmail get <messageId> --sanitize-content --json --wrap-untrusted
gog --account user@example.com gmail thread get <threadId> --sanitize-content --json --wrap-untrusted
gog --account user@example.com calendar events --today --json --wrap-untrusted
gog --account user@example.com drive ls --max 20 --json --wrap-untrusted
gog --account user@example.com docs cat <documentId> --json --wrap-untrusted
gog --account user@example.com sheets get <spreadsheetId> Sheet1!A1:D20 --json --wrap-untrusted
gog --account user@example.com sheets batch-update <spreadsheetId> --data-json @updates.json --json
gog --account user@example.com contacts list --max 20 --json --wrap-untrusted
For Gmail body inspection, prefer --sanitize-content unless the user
explicitly needs raw payloads.
Before writes, identify the account, object id, and exact mutation. Prefer
commands that support --dry-run, and clean up disposable live-test objects.
gog --account user@example.com docs write <documentId> --append --text '...'
gog --account user@example.com docs write <documentId> --tab "Data" --markdown --replace --file data.md
gog --account user@example.com docs update <documentId> --tab "Data" --markdown --file block.md
gog --account user@example.com docs update <documentId> --tab "Data" --replace-range START:END --text 'replacement'
gog --account user@example.com docs update <documentId> --tab "Data" --markdown --replace-range START:END --file block.md
gog --account user@example.com sheets update <spreadsheetId> Sheet1!A1 --values-json '[["hello"]]'
gog --account user@example.com sheets batch-update <spreadsheetId> --data-json @updates.json
gog --account user@example.com drive upload ./file.txt --parent <folderId> --json
For Google Docs tab work:
docs list-tabs <documentId> --json to discover tab titles/IDs before targeting a tab.docs write --markdown --replace --tab <tab> for whole-tab formatted replacement.docs update --markdown --tab <tab> for formatted insertion/append without replacing the whole tab.docs update --replace-range START:END for precise plain-text replacement; add --markdown to replace that exact range with formatted markdown.START:END is a Google Docs UTF-16 API range. Resolve it from docs cat --raw, docs raw, or another documents.get readback; do not guess indexes.--replace-range and --index are mutually exclusive.When testing creation commands, name artifacts with a clear temporary prefix and delete or trash them after verification.
gmail batch delete permanently deletes messages and requires the broader
https://mail.google.com/ OAuth scope. Prefer gmail trash; when permanent
deletion is required, follow the exact reauthorization command printed by gog.
For larger Sheets writes, prefer sheets batch-update over loops of
sheets update; it sends multiple value ranges in one Sheets API request and
accepts inline JSON or @file input.
For normal Gmail replies, use the first-class commands instead of rebuilding
reply MIME through gmail send:
gog --account user@example.com gmail reply <messageId> --body-file reply.txt
gog --account user@example.com gmail reply-all <messageId> --body-file reply.txt \
--bcc introducer@example.com --remove former-participant@example.com
They inherit the subject, quote by default, preserve display names and inline
images, and treat --to/--cc/--bcc as additive placement or moves. Use
--no-quote to omit the original.
Use generated command docs and schema instead of guessing flags:
gog <service> --help
gog <service> <command> --help
gog schema <service> <command> --json
Docs:
docs/index.mddocs/commands/README.mddocs/safety-profiles.mdRepo paths:
cmd/gog/internal/cmd/internal/googleauth/, internal/authclient/, internal/secrets/docs/commands/Check whether the current branch or worktree is ready to merge, including dirty state, mergeability, conflicts, overlap with other branches/worktrees, lint/tests/CI, stale docs, config/example drift, and live config follow-up.
Create the save-to-md session doc before staging, git add all, commit with Claude co-authorship trailer, and push to current/new feature branch — including project version bump and changelog update when applicable. Use when the user says "quick push", "push my changes", "commit and push", "ship this", "push to a new branch", or any request to wrap up local work and get it on the remote. Accepts optional `--no-bump` argument to skip the version bump.
Run the PR Review Toolkit flow from Codex for the current branch or pull request. Use when the user asks for a comprehensive PR review, asks to run /pr-review-toolkit:review-pr, needs mandatory review waves inside work-it, or wants focused checks for code quality, tests, comments, silent failures, type design, docs/config drift, or simplification.
Use when the user asks to "work it", execute a plan in a worktree, create a progress-tracked PR, or run a mandatory review-and-fix loop over all touched files until lint, tests, CI, and reviews are green.
Use this BEFORE creating a git worktree or implementing any plan. Tailored to our workflow — prefer it over superpowers:using-git-worktrees and every other worktree skill. Triggers - creating or adding a worktree; starting lavra-work, lavra-work-ralph, lavra-work-teams, executing-plans, subagent-driven-development, or work-it; whenever a Claude, Codex, or Gemini plan mode is entered or a plan is accepted; or before implementing anything in a fresh branch. Creates the worktree under .worktrees/ in the repo and makes it identical to and as warm as the main checkout - copying secrets and local config (.env, CLAUDE.md.local, .claude/settings.local.json), symlinking warm caches (node_modules, .venv, target, .next), and re-trusting mise/direnv. Also use when a worktree is missing files, builds cold, or reports mise 'not a trusted directory'. Bundles a worktree-sync engine, a create-in-.worktrees entrypoint, a minimal baseline template, and references.
Scoped to Jacob's homelab Rust repos — the rmcp MCP-server family (rustifi, rustify, rustscale, unrust, rarcane, rustarr, apprise-mcp, cortex, synapse2, rmcp-template) and the Lab runtime/ACP work. Use when editing those repos: covers rmcp-template-derived server patterns, action-dispatched MCP tools, CLI/MCP/API parity, service-layer architecture, config/auth/scope contracts, testing strategy, release/build conventions, and ACP runtime/provider work. Not a general-purpose Rust skill.