steipete/gogcli
Gogcli
gogcli is a single command-line binary that manages Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Apps Script, Contacts, People, Tasks, Classroom, Chat, Groups, Keep, and Workspace Admin services through a predictable service resource method grammar. It authenticates across multiple Google accounts using OAuth, service accounts, access tokens, or application default credentials, storing credentials in the OS keyring for secure persistence. The tool also exposes a Model Context Protocol server over stdio that registers typed tools for agent clients, and can invoke any Google Discovery-described API method through a schema lookup primitive.
The project distinguishes itself through comprehensive safety controls and automation-oriented design. It enforces read-only modes, command allowlists and denylists, build-time command blocking, and safety profiles that wrap untrusted content and prevent accidental mutations. Structured output emits JSON or TSV on stdout while separating human messages to stderr, and the tool returns distinct exit codes for auth failures, permission denials, empty results, and retryable errors. For backup, it encrypts Gmail, Drive, Calendar, and other service data into age-encrypted shards committed to Git, with incremental checkpointing and crash recovery.
The tool supports headless execution in containers and CI environments with encrypted file keyrings, shell hook execution on events, and Pub/Sub event polling with local cursor persistence. It provides runtime command schema discovery, shell completion generation, and AI agent skill file generation for tooling integration. Additional capabilities include Drive file and sharing auditing, Gmail search and filter export, Calendar event management with Meet and Zoom support, Docs editing with revision control, spreadsheet management, and YouTube channel and playlist operations. The project includes a live API test harness that creates and cleans up disposable resources, with configurable retry behavior.
Features
- Google Workspace Integrations - Manages Gmail, Drive, Calendar, and other Google Workspace services from the command line for automation and scripting.
- CLI Tools - Provides a single command-line binary that manages Gmail, Drive, Calendar, and other Google Workspace services.
- AI Agent Tooling - Exposes Google Workspace tools to AI agents through a Model Context Protocol server with typed, permissioned interfaces.
- Google Workspace Servers - Exposes typed, allowlisted Google Workspace tool schemas over stdio for AI agent clients.
- Google Workspace Tool Servers - Runs a typed MCP stdio server that registers specific Google tools for agent clients without exposing a generic command runner.
- Allowlisted Tool Servers - Exposes typed, allowlisted tools for agent clients through an MCP server without a generic command bridge.
- Structured Output Diffing - Outputs structured JSON or stable TSV for programmatic consumption while keeping human messages on stderr.
- Google Sheets Managers - Reads, updates, and formats spreadsheet ranges, manages tables, sets validation rules, and applies conditional formatting.
- Admin Task Executions - Manages users, groups, and organizational units in a Google Workspace domain with domain-wide delegation.
- Automation Frameworks - Provides a scriptable orchestration layer for chaining Google API operations with structured output and safety controls.
- Google Docs Readers and Writers - Reads and writes Google Docs documents as wrapped text or Markdown through the API.
- Calendar Event Management - Retrieves events from Google Calendar for a specified time range.
- Gmail Workflows - Searches, retrieves, and reads Gmail messages and threads by ID with optional content sanitization.
- Workspace Management - Creates users, lists organizational units, and manages groups using admin-scoped commands for Google Workspace.
- Workspace Resource Management - Creates, inspects, suspends, deletes, and lists Workspace users, organizational units, and groups.
- Google Docs Editors - Provides programmatic editing of Google Docs documents including text, tables, images, and find-and-replace operations.
- Command Grammars - Follows a predictable service resource method grammar for easy command discovery.
- Google Workspace Automations - Provides a headless automation framework for chaining Google Workspace API operations with safety controls.
- Machine-Readable CLI Outputs - Outputs results as JSON or TSV on stdout while sending human-readable messages to stderr.
- Structured CLI Outputs - Emits JSON or plain text on stdout, separates progress to stderr, and supports flags for no-input, dry-run, and command allowlisting.
- Google Account Authenticators - Opens a browser for OAuth consent and stores refresh tokens in the OS keyring for persistent API access.
- Multi-Provider - Supports OAuth, access tokens, ADC, and service accounts across many Google accounts and projects.
- Google API Integrations - Runs a single binary that authenticates and interacts with Gmail, Drive, Calendar, Docs, and other Google services from the command line.
- Discovery API Invocations - Invokes any Google Discovery-described API method and lists or describes available APIs.
- Credential Authentication - Uses the same account and OAuth client configuration as the parent CLI with environment variable inheritance for headless setups.
- Keyring Backend Stores - Stores OAuth tokens and service account keys in native OS keyrings or encrypted files for secure persistence.
- Service Account Authenticators - Accepts Workspace service accounts, direct tokens, and ADC credentials through a unified command interface.
- Multi-Provider Routing - Manages multiple Google accounts and OAuth client projects with support for various credential types.
- Domain-Wide Delegation - Uses domain-wide delegation to impersonate Workspace admin identities for authorized API access.
- Token and Key Storage - Stores and manages OAuth refresh tokens and service account keys for authorized API access.
- Safety Profile Enforcers - Enforces read-only modes, untrusted-content wrapping, and command guards for safe non-interactive operation.
- Safety Profile Guards - Applies comprehensive safety profiles including untrusted content wrapping, dry-run plans, and no-send policies.
- Account Impersonation - Configures domain-wide delegation for Workspace service accounts to impersonate users for authorized API access.
- Google Discovery Schema Lookups - Uses a schema lookup primitive to close the long tail of API methods without per-command learning.
- Service-Oriented Grammars - Routes all operations through a predictable service resource method grammar for command discovery.
- Google Account Credential Management - Holds credentials for several Google accounts and OAuth clients, routing each command to the right identity.
- Stderr-Separated Outputs - Outputs JSON or TSV on stdout while separating human messages to stderr for parseable pipelines.
- Google Slides Editors - Creates presentations from Markdown, edits text and tables, inserts images, and manages slide structure and layout.
- Agent Skill Generators - Generates a structured skill file from the CLI's schema so an AI agent knows every command and flag for a Google service.
- Backup and Encryption - Fetches calendar events, contacts, task lists, and Drive files/metadata via their respective APIs and encrypts them into shards.
- Send Guards - Enforces a no-send flag to prevent accidental email sending during automated Gmail operations.
- Drive Resource Auditing - Computes storage or permission summaries across a Drive hierarchy without manual aggregation.
- Workspace Security Audits - Inspects Drive sharing permissions, contacts, and account data to identify security risks without modifying anything.
- Spreadsheet Data Writing - Reads values from a Sheets range and updates cells with a literal JSON 2D array.
- Format Selectors - Chooses between parsed, metadata-only, or raw RFC822 message formats when fetching a Gmail message.
- Search Queries - Provides Gmail search with standard query syntax and sanitized content for automation and AI consumption.
- Workspace Data Backups - Initializes a backup repository, pushes data from selected services, verifies integrity, and exports in readable formats.
- Encrypted Exports - Exports and encrypts Gmail, Drive, and Calendar data into age-encrypted shards committed to Git.
- Account Data Backups - Pushes mailbox and other account content to a backup destination with a single command.
- Contact Management - Searches, exports, and deduplicates contacts by matching fields like email, phone, or name.
- Gmail Backup Exports - Fetches raw Gmail messages and labels via the API and encrypts them into shards for backup.
- Google Drive Change Pollers - Polls the Google Drive changes feed at a configurable interval, persisting the API cursor locally for resumable incremental sync.
- Drive Change Polling - Provides continuous polling of the Drive changes feed with local cursor persistence for resumable incremental sync.
- API Read-Only Modes - Blocks all mutation requests at runtime when the --readonly flag is active.
- Apps Script Management - Creates, retrieves content, and runs deployed functions for Google Apps Script projects.
- Cloud Drive File Searches - Finds files by text or Drive query language and retrieves file metadata or document content.
- Destructive Operation Previews - Shows what a Drive tree, disk usage, inventory, or contact deduplication would change before requiring an explicit apply flag.
- Command Discovery - Exposes command schema, exit codes, output modes, and safety state via a JSON contract.
- Dry-Run Previews - Tests subscription and playlist mutations without making network requests using a dry-run flag.
- Exit Status Signaling - Returns distinct exit codes for auth failures, permission denials, empty results, and retryable errors.
- Headless Execution Environments - Configures the CLI with an encrypted file keyring for headless execution in containers and CI environments.
- Canonical API Response Fetching - Outputs the canonical Google API response for a resource as JSON, preserving all fields for programmatic or LLM consumption.
- Multi-Step Workflow Runners - Executes a hand-authored multi-step task that chains Google services in a safe, ordered sequence with cleanup.
- Event-Driven Execution - Executes a trusted local shell command per event batch, passing the event payload as JSON on stdin and retrying on failure.
- Build-Time Command Blockers - Compiles a restricted binary that removes disallowed commands, making them invisible at runtime.
- Subprocess Security Policies - Runs each tool call as a sandboxed subprocess with non-interactive flags, timeouts, and bounded output capture.
- Safety-Focused Compilations - Compiles restricted binaries that remove disallowed commands and enforce safety profiles at build time.
- Account Switching and Aliasing - Switches between multiple Google accounts by name or alias with environment variable defaults.
- Email Send Blockers - Blocks all email send operations via flag or environment variable to prevent accidental sends during automation.
- Tool Access Controls - Controls which tools are registered by allowing only read tools by default and requiring opt-in for write tools.
- Command Restrictions - Limits which command paths an agent or script can execute using exact or prefix allowlists and denylists.
- Untrusted Content Markings - Marks fetched Google text as untrusted so downstream tools and agents handle user-supplied data safely.
- Sharded Git Backups - Encrypts API data into age-encrypted shards and commits them to Git for versioned backup.
- Encrypted Git Backups - Encrypts Gmail, Drive, and Calendar data into age-encrypted shards and commits them to a Git repository.
- Browserless OAuth Flows - Supports manual URL pasting or split-server flows for OAuth in environments without a browser.
- Client Secret and Scope Management - Stores OAuth client secrets, adds accounts with selected scopes, and lists stored credentials.
- Client and Token Selection - Picks which stored credentials and token bucket to use via flag, config mapping, or domain auto-detection.
- Destructive Operation Bypasses - Skips confirmation prompts for destructive operations when explicitly enabled for automation.
- Untrusted Content Wrappings - Wraps fetched free-text fields as untrusted in raw output so LLM agents consume them safely.
- Automatic Redaction - Automatically removes capability URLs and app-stashed metadata from API responses to prevent data leakage.
- API Response Field Redactors - Strips high-risk fields like thumbnail links and export URLs from Drive raw responses unless explicitly requested.
- API Schema Discovery - Exposes a runtime schema lookup primitive that dynamically inspects available Google Discovery APIs and their methods.
- CLI Command Generators - Outputs a JSON schema of the running binary's commands, including build-time safety filters.
- YouTube Channel and Video Managers - Lists channels, videos, playlists, and subscriptions, and creates playlists with privacy settings and dry-run support.
- API Testing - Runs real Google Workspace API tests using disposable resources that are cleaned up after each test run.
- Cursor-Persisting Pollers - Persists cursors for Drive and Docs changes and optionally invokes trusted shell hooks when new events arrive.
- Runtime Command Generation - Exposes command shape, exit codes, output modes, and safety state via a generated schema.
