Gog

gog

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.

Fast Path

gog --version
gog auth list --check --json --no-input
gog auth doctor --check --json --no-input
GOG_HELP=agent gog --help
gog schema --json

GOG_HELP=agent makes root help emit a compact automation contract and common read-only recipes; commands and behavior stay unchanged. Machine output, non-interactive behavior, stable exit codes, command guards, and untrusted-content wrapping apply across the CLI. 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.

--results-only unwraps the primary result before --select projects it. For lists, select item-relative fields: --results-only --select id. Dot paths do not broadcast through nested arrays (--select items.id selects nothing). Unmatched object fields are omitted.

Pick the account explicitly for API work:

gog --readonly --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.

Safety Rules

• Do not print access tokens, refresh tokens, OAuth client secrets, or keyring passwords.
• If 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.
• In headless/service agents, verify the service environment, not just the login shell. GOG_KEYRING_BACKEND=file, GOG_KEYRING_PASSWORD, and HOME must be present in the process that launches gog.
• Use --no-input in automation so auth/keyring prompts fail clearly.
• Use --dry-run first where commands support it.
• Use --readonly for tasks that must not mutate Google data; remove it only for the exact write the user approved.
• Destructive commands require --force; do not add it unless the user asked for that exact mutation.
• Use --gmail-no-send or GOG_GMAIL_NO_SEND=1 unless sending mail is the requested task.
• For shared agent environments, prefer a baked readonly or agent-safe binary from docs/safety-profiles.md.

Runtime command guards:

gog --readonly --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

Auth

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.

Browser-Driven Reauth

An agent can complete this flow end to end when it can drive a signed-in browser. Consent still happens in a real browser; nothing here bypasses it.

Run the CLI leg in a detached tmux session so it survives command boundaries:

tmux -L gog-auth new-session -d -s auth -x 200 -y 50
tmux -L gog-auth send-keys -t auth \
  "gog auth add user@example.com --services all-user --force-consent --timeout 15m" Enter

Capture the consent URL with -J:

tmux -L gog-auth capture-pane -t auth -p -J -S - \
  | grep -oE 'https://accounts\.google\.com[^ ]+' | tail -1 > "$url_file"

-J is mandatory. capture-pane otherwise returns the URL hard-wrapped at the pane width. A truncated consent URL does not fail loudly: Google renders Invalid OAuth Request / Invalid response_type: missing, which reads like a client misconfiguration and sends you debugging the wrong thing. Verify the captured URL contains response_type before using it.

Write the URL to a mode-0600 file and hand it to the browser by file reference (see $browser-use); never echo it. Appending &login_hint=user@example.com skips the account chooser and removes a whole class of wrong-account risk.

Expect up to two interstitials when the OAuth client is unverified or in testing:

1. "Google hasn't verified this app." Continue is a low-emphasis link on one side; Back to safety is the prominent button. Activating the visually obvious control aborts the flow. A developer-info control sits in the tab order between them, so count focus stops deliberately instead of guessing.
2. "You're signing back in to <app>" — confirm the displayed account is the intended one, then Continue.