gog-cli

intent

gog is a fast, script-friendly CLI for Google services. use this skill whenever the user wants to operate Google Workspace from the command line, including Gmail, Calendar, Drive, Docs, Sheets, and other services. gog is JSON-first, supports multiple accounts and OAuth clients, and has explicit guardrails for agent and CI usage. this skill covers setup, authentication, common operations, and safety practices.

inputs

• gog binary: must be installed locally. authoritative upstream: https://github.com/steipete/gogcli. current skill validated against gog v0.13.0 (2026-04-20).
• Google Workspace account(s): one or more Google accounts you own or admin.
• OAuth consent: first use of gog on a new machine requires browser-based OAuth flow to grant scopes (Gmail, Calendar, Drive, etc.). you control which scopes gog requests.
• keyring/credential store: gog stores OAuth tokens in your OS keyring (macOS Keychain, Linux secret-service, Windows Credential Manager). must be accessible and unlocked.
• GOG_GMAIL_NO_SEND (optional env var): set to 1 to disable mail sending globally (agent/CI safety).
• gog config (optional): persistent account settings, OAuth client mappings, no-send flags stored in $HOME/.config/gog/config.toml or similar.

external docs: gog --help and gog schema --json for command schema. command surface moves quickly; check upstream for exact syntax when in doubt.

procedure

1. install gog (if not present).

   • input: your OS type.
   • install from https://github.com/steipete/gogcli per instructions.
   • output: gog binary in PATH.

2. authenticate a Google account.

   • input: Google account email, desired OAuth scopes (Gmail, Calendar, Drive, Docs, Sheets, Admin, etc.).
   • run: gog auth login <account-email> or gog auth login for interactive prompt.
   • gog opens browser for OAuth consent. you grant scopes. gog stores token in keyring.
   • output: authenticated account added to gog. verify with gog auth list.
   • note: if keyring is locked, unlock it first. if consent fails, check browser console for errors and re-run.

3. list or switch accounts.

   • input: (none if listing; target account email if switching).
   • run: gog auth list to show all authenticated accounts and active account.
   • run: gog auth use <account-email> to set active account.
   • output: list of accounts or confirmation of active account change.

4. run a read operation (Gmail, Calendar, Drive, etc.).

   • input: command (e.g., gog gmail threads list or gog calendar events list), optional filters, output format preference.
   • run: gog <service> <resource> <action> [options] --json for JSON output or --plain for TSV.
   • for inspection or scripting, pipe to jq: gog <service> <resource> <action> --json | jq '.field'.
   • output: JSON array or TSV rows matching query.
   • handle edge case: empty result set (no threads, no events) returns empty JSON array [] or blank TSV. do not treat as error.

5. run a write or mutating operation (send mail, create event, update doc, etc.).

   • input: command, mutation details, user intent confirmation.
   • if user intent is ambiguous or you are preparing a change, first run: gog <service> <resource> <action> [options] --dry-run to preview effect.
   • output: dry-run shows what would change without applying it. review with user.
   • once confirmed, run: gog <service> <resource> <action> [options] --force (if the action is destructive, sends mail, makes public, adds delegates, suspends users, or permanently deletes).
   • if action is not destructive, --force may not be needed. some actions prompt for confirmation; use --no-input in automation to fail instead of hanging.
   • output: confirmation message, updated resource ID, or affected count.

6. handle authentication errors or token expiry.

   • input: command fails with "unauthorized" or "invalid grant" error.
   • do not attempt to repair OAuth or consent silently. instead, show the user the exact command to re-authenticate: gog auth login <account-email> --force-refresh.
   • user runs command, grants consent again, token is refreshed in keyring.
   • output: re-authentication confirmation, token refreshed.

7. enable safety guards for agent or CI runs.

   • input: context is automated, risk of unintended mail send or data mutation.
   • set env var: GOG_GMAIL_NO_SEND=1 (or configure: gog config no-send set <account>).
   • or append --gmail-no-send flag to any gmail command.
   • output: mail send operations fail with explicit error instead of executing.
   • verify safety: run a dry-run or list operation first to confirm auth and context.

8. switch OAuth client (multi-client setups).

   • input: target OAuth client ID (if you manage multiple apps or delegate accounts).
   • run: gog config oauth-client set <account> <client-id> or gog auth login <account-email> --client-id <id>.
   • output: account mapped to new OAuth client.

decision points

• if user wants to send mail or mutate data: require explicit --force flag and confirm user intent first. do not send, delete, or change without user request.
• if user wants to repair auth, consent, or keyring issues: do not attempt silent repair. show exact command for user to run (e.g., gog auth login --force-refresh).
• if user wants stable TSV output for scripting: use --plain. otherwise default to --json for inspection and piping.
• if command may hang waiting for input in CI: add --no-input flag to fail fast instead.
• if it is an agent run and mail send must be prevented: set GOG_GMAIL_NO_SEND=1 env var or use --gmail-no-send flag.
• if result set is empty (no Gmail threads, no Calendar events, no Drive files): do not error. return empty JSON [] or blank TSV and inform user no matches found.
• if rate limit or network timeout occurs: gog backs off and retries. if retry fails, show user the rate limit error (includes retry-after header) and advise waiting before next request.
• if command syntax has changed since v0.13.0: run gog <command> --help or gog schema --json to check current signature. upstream moves fast.

output contract

• success for read operations: JSON array of objects (with --json) or TSV rows (with --plain), matching query filters. empty array [] or blank output if no results.
• success for write operations: confirmation object including operation status, affected resource ID, and/or count of changed rows. dry-run prepends [DRY RUN] marker.
• success for auth operations: list of authenticated accounts, active account name, or token refresh confirmation.
• error output: stderr message including error code, scope/permission issue, or exact command to retry. no silent repairs.
• file location: tokens stored in OS keyring (not exportable). config written to $HOME/.config/gog/config.toml or platform-specific config dir.

outcome signal

• user sees JSON or TSV data matching their query, or confirmation of write/mutation.
• for auth: user sees account listed in gog auth list or token refreshed without errors.
• for safety: agent/CI run with --gmail-no-send or GOG_GMAIL_NO_SEND=1 fails explicitly if mail send is attempted, instead of sending.
• for errors: user sees exact command to fix (e.g., re-auth, check consent, unlock keyring). no silent failures.
• dry-run shows preview before mutation. user approves, re-runs with --force, sees final confirmation.

credits: original skill by intellectronica. enriched for implexa quality standards.