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 [email protected] 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.