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.

Safety Rules

Do not print access tokens, refresh tokens, OAuth client secrets, or keyring passwords.
Do not store GOG_KEYRING_PASSWORD in a shell profile or plaintext project file. If the file keyring cannot unlock non-interactively, stop and ask for a safer setup.
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.
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 --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 gmail,calendar,drive --readonly
gog auth add user@example.com --services docs,sheets,slides
gog auth remove user@example.com

Use narrow services and --readonly when the task only reads. 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.

Common Reads

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 contacts list --max 20 --json --wrap-untrusted

For Gmail body inspection, prefer --sanitize-content unless the user explicitly needs raw payloads.

Writes

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 sheets update <spreadsheetId> Sheet1!A1 --values-json '[["hello"]]'
gog --account user@example.com drive upload ./file.txt --parent <folderId> --json

When testing creation commands, name artifacts with a clear temporary prefix and delete or trash them after verification.

Discovery

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.md
docs/commands/README.md
docs/safety-profiles.md

Repo paths:

CLI entrypoint: cmd/gog/
Command implementations: internal/cmd/
OAuth/keyring: internal/googleauth/, internal/authclient/, internal/secrets/
Generated command docs: docs/commands/

gog

gog

Fast Path