Gog: Automate Google Workspace from the Terminal with Agent Safety

Terminal Access to Gmail, Calendar, Drive and Other Google Workspace Services

Gog connects Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Contacts, Tasks, Meet, Chat, YouTube, AdSense, and other Google Workspace APIs to the command line and scripts. It is built for people, scripts, CI, and agents that need explicit account routing, machine-readable output, and safety controls.

This differs from casual curl calls to the Google APIs: gog handles OAuth renewal via the platform keyring or encrypted files, routes among multiple Google accounts by name, emits stable machine-readable output with --json or --plain (TSV), and enforces safety boundaries that you define. You can run gog with --readonly to forbid any write operations, --gmail-no-send to allow reading mail but never sending, or --enable-commands-exact to whitelist only the subcommands you trust. It is built for human operators and for agents that agents allow to touch your account.

Safety Controls for Untrusted Execution

Gog is designed to run with explicit constraints. The --readonly flag blocks all write operations, including changes to settings. The --enable-commands-exact flag accepts a comma-separated list of commands (e.g., gmail.search,gmail.get) and rejects anything else. The --gmail-no-send flag forbids sending mail while allowing reads. The --wrap-untrusted flag wraps content from untrusted sources, preventing injection. The --no-input flag rejects any interactive prompt; combined with --json for structured output and stderr for warnings, this makes gog usable in unattended scripts. These flags can be layered together for defense in depth: `gog --readonly --no-input --enable-commands-exact gmail.search --wrap-untrusted gmail search 'is:unread'` creates a highly constrained execution context.

For long-lived binaries like agents, gog offers safety profiles: YAML files that bake in command allowlists and locked flag values at build time. Build one with `./build-safe.sh safety-profiles/agent-safe.yaml -o gog-safe`, and the resulting binary will never obey commands or flags that the profile forbids. The resulting binary cannot be overridden at runtime, making it suitable for delegation to untrusted environments. Gog also exposes an MCP server via `gog mcp`, a typed stdio interface for Claude and other agents. The MCP server is read-only by default and requires explicit tool authorization for writes.

Command Trees, OAuth Tokens, and Schema Generation

Gog translates commands and flags into Google API calls. It covers 20+ Google services with command trees: `gog gmail search`, `gog calendar events`, `gog drive ls`, `gog docs comments`, and so on. Each command maps to one or more Google APIs. The running binary generates its command schema with `gog schema --json`, and reference pages and agent skills from the same tree. The schema is stable and machine-readable, allowing external tools to discover what commands are available and their parameters.

Authentication uses OAuth 2.0 flows. Each gog account stores tokens using the platform keyring by default: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Headless systems can use the encrypted file backend with `GOG_HOME`. Gog supports multiple authentication methods: Desktop OAuth clients (the typical path), Application Default Credentials, direct access tokens, and Workspace service accounts for domain-wide delegation. Service accounts can use domain-wide delegation, allowing a single service account to act on behalf of any user in a Workspace domain. The toolchain is built in Go 1.27.1, as specified in go.mod.

Installing and Setting Up

Homebrew is the shortest path on macOS and Linux:

brew install openclaw/tap/gogcli
gog --version

On any OS with Go installed, use:

go install github.com/openclaw/gogcli/cmd/gog@latest
gog --version

Docker images, Windows archives, raw binaries, and source builds are available. The quick start is to create a Desktop OAuth client in Google Cloud Console, download its JSON file, and authorize the services you need:

gog auth credentials set ~/Downloads/client_secret_*.json
gog auth add [email protected] --services gmail,calendar,drive
export [email protected]
gog auth doctor --check
gog gmail search 'newer_than:7d' --max 10

The `auth doctor` command verifies that tokens are valid and the API is accessible. The first `gog` command will open a browser for OAuth consent.

Least-Privilege Authorization

Google OAuth scopes determine what operations a token permits. Gog lets you choose scopes at authorization time. For example, use `--gmail-scope send` for sending only, or `--gmail-scope read-send` to read messages without mailbox-modification or settings-management permissions. For each service you authorize, you can see the scopes with `gog auth services`, which reports the supported surface from the installed binary.

This gives you control over the blast radius of a compromised token. If you only need to read unread emails for a daily briefing, authorize only the read scope. If an agent needs to create events, authorize only calendar write. Supported services include gmail, calendar, chat, classroom, drive, driveactivity (read-only audit), drivelabels (read-only labels), docs, sheets, slides, forms, contacts, tasks, meet, zoom, keep, groups, admin (directory), analytics, searchconsole, adsense, and youtube. Consumer Google accounts work with user-facing APIs; Workspace admin APIs, Chat, and Keep require a managed Workspace domain.

Multiple Accounts and Output Formats

One gog installation can manage multiple Google accounts and OAuth client projects. List them with `gog auth list --check` and set an alias with `gog auth alias set work [email protected]`. Then route commands with `gog --account work gmail search 'is:unread'`. The environment variable `GOG_ACCOUNT` sets the default.

For scripts and agents, gog emits structured output: `--json` for JSON, `--plain` for TSV with stable columns. Prompts, progress, and warnings go to stderr, leaving stdout clean for piping.

The generic `gog api` commands offer a fallback for services gog does not yet expose as first-class commands. `gog api describe` lists available APIs from Google, and `gog api call` invokes them with raw payloads, as long as your token permits. This gives you access to new Google services immediately, even if gog has not added a typed command for them.

When Gog Is Not the Right Tool

Gog does not cover the full Google Workspace UI. It exposes the APIs that exist as REST endpoints, but Gmail labels, filters, and some calendar event details do not have public APIs. If you need to read or manage labels, gog offers the Gmail Settings API scope but does not wrap it in a command; you would use the generic `gog api` fallback or a different tool.

Google Workspace administration via gog requires a Workspace domain and service account credentials. Consumer Google accounts support user-facing APIs only. If you need to bulk-manage users, audit Admin Directory, or enforce DLP policies across your domain, gog works as a helper but the primary tools are the Admin console and gcloud command-line tools.

For batch work on millions of documents or emails, gog is a REST client; it makes one API call per document. If your task is to scan 10 million emails in Drive, a library like gophercloud or a custom script using the Google client libraries in batch mode will be faster. The Makefile notes that CI tests exist, but the README does not state performance or throughput benchmarks.

Comparison with Google Cloud CLI

Google Cloud's gcloud CLI covers Cloud resources like Compute Engine, BigQuery, and Cloud Storage, but not consumer Google services. The Google Cloud CLI is for infrastructure engineers; gog is for terminal automation of Gmail, Calendar, and Drive. Some organizations use gcloud for Workspace admin via Identity and Access Management, but that manages Cloud project access, not Workspace itself.

For Workspace administration, Google publishes a Python library, googleapis, and command-line tools like the Admin Data Transfer tool, but these are narrower. Gog unifies all of Gmail, Calendar, Drive, and Workspace admin under one consistent CLI. A developer might instead write custom scripts using the google-api-python-client library or the google-cloud SDK for Go, which offer more flexibility but require you to handle OAuth, token refresh, and error cases yourself.

Editorial conclusion

Gog is for engineers automating Google Workspace in CI/CD, shell scripts, or agent workflows where safety controls and structured output matter more than breadth. Adopt it if you need to read Gmail or Drive from the terminal and can afford the OAuth setup. Verify that your Google account type supports the services you need: Workspace admin features, Chat, and Keep require a managed domain.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes