DOCSEARCHbyAlgolia
Submit Docs

gog CLI

repository·main·Indexed 27 days ago

https://github.com/openclaw/gogcli

A command-line interface for Google Workspace providing task-oriented workflows for Gmail, Calendar, Drive, and other Google services. Designed for human users and automated systems, gogcli focuses on safety, predictability, and parseable output. It includes comprehensive command suites for Google Analytics, Apps Script, Classroom, Contacts, Docs, and Workspace Admin (via Directory API), as well as tools for encrypted account backups and OAuth credential management.

Tokens
827.7K
Snippets
722
Records
1.8K
Agent score
91%

What's inside gogcli

  1. Overview of gog CLI commands

    main
    The gog CLI provides a wide range of commands to interact with Google Workspace services directly from the terminal. Commands are categorized by the Google service they interface with (e.g., gog gmail for Gmail, gog drive for Google Drive, gog calendar for Google Calendar). Many commands have convenient aliases (e.g., gog send for gog gmail send).

  2. Use the gog CLI

    main

    The gog CLI provides a terminal interface for various Google Workspace services including Gmail, Calendar, Drive, Sheets, and more. It is designed to be parseable, non-interactive, and can be configured for read-only or restricted use (e.g., preventing Gmail from sending emails).

    Configuration

    • Config file location: <config-dir>/gogcli/config.json
    • Keyring backend: auto (default)
    • Environment Variable: Use GOG_HOME to override the config/data/state/cache root, or use the --home flag.
    gog <command> [flags]

  3. Design principles of gog

    main

    gog is designed to bridge the gap between human terminal usage and automated agent/CI workflows using a single command surface. Key design principles include:

    • Workflow-centric commands: Commands handle complex tasks like pagination, time parsing, and content sanitation rather than just exposing raw API endpoints.
    • Stdout as an API: Uses --json and --plain flags for machine-readable output on stdout, while keeping human-centric guidance and warnings on stderr. It uses stable exit codes for automation branching.
    • Unified Auth Routing: Supports multiple Google accounts and OAuth client projects via aliases, domain mappings, direct access tokens, ADC, and Workspace service accounts.
    • Layered Safety: Provides multiple safety mechanisms including --readonly enforcement, Gmail no-send policies, dry-run modes, and command allowlists/denylists.
    • Self-documenting Schema: The CLI can generate its own contract via gog schema --json, which can be used for agent discovery and documentation.

  4. Available gog workflows

    main

    The following curated cross-service workflows are included in the gog agent skills package:

    • gog-inbox-triage: Prioritize unread mail without sending any messages.
    • gog-meeting-prep: Combines Calendar context with linked Drive material.
    • gog-save-attachments: Downloads Gmail attachments and can optionally upload them to Drive.
    • gog-drive-audit: Inspects public, external, and user-specific sharing permissions.
    • gog-weekly-digest: Summarizes Calendar, Gmail, and Tasks.
    • gog-contacts-cleanup: Reviews duplicate contacts before an explicitly confirmed merge.

  5. Set up Workspace service accounts with domain-wide delegation

    main

    For automation involving Workspace Admin, groups, org-units, or Keep, use a service-account key with domain-wide delegation. You must store the key for the Workspace admin identity you intend to impersonate.

    Note: For Cloud Identity Groups commands, ensure https://www.googleapis.com/auth/cloud-identity.groups.readonly is included in your domain-wide delegation settings.

    # Set the service account key for an admin identity
gog auth service-account set admin@example.com --key ~/Downloads/service-account.json

# Check the status of the service account
gog auth service-account status admin@example.com

# Use the service account for Cloud Identity Groups
gog --account admin@example.com groups list
gog --account admin@example.com groups members engineering@example.com

# Use the service account for Admin SDK commands
gog --account admin@example.com admin users create ada@example.com \
  --first-name Ada \
  --last-name Lovelace \
  --change-password

  6. Manage Google API Scopes and Authentication

    main

    The gog CLI manages authentication by storing a single refresh token per Google account email. Scopes are requested as a union based on the --services flag provided during authentication.

    To add or update authentication for a specific email address and include specific Google services, use the gog auth add command. If you need to add new services to an existing account, you may need to use the --force-consent flag to generate a new refresh token with the expanded scope set.

    Supported services and their associated scopes include:

    • Gmail: https://mail.google.com/
    • Calendar: https://www.googleapis.com/auth/calendar
    • Chat: https://www.googleapis.com/auth/chat.spaces, https://www.googleapis.com/auth/chat.messages, https://www.googleapis.com/auth/chat.memberships, https://www.googleapis.com/auth/chat.users.readstate.readonly
    • Drive: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.labels.readonly
    • Contacts/Directory: https://www.googleapis.com/auth/contacts, https://www.googleapis.com/auth/contacts.other.readonly, https://www.googleapis.com/auth/directory.readonly
    • People: profile (OIDC)
    • YouTube: https://www.googleapis.com/auth/youtube.readonly, https://www.googleapis.com/auth/youtube.force-ssl
    • Photos: https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata, https://www.googleapis.com/auth/photospicker.mediaitems.readonly

  7. Configure `gog youtube` output for scripting

    main

    When using gog youtube in scripts or automation, use the following flags to ensure parseable output:

    • -j, --json, or --machine: Outputs JSON to stdout.
    • --results-only: When in JSON mode, emits only the primary result, omitting envelope fields like nextPageToken.
    • --select, --pick, or --project: In JSON mode, selects specific comma-separated fields (supports dot paths).
    • -p, --plain, or --tsv: Outputs stable, parseable TSV text without colors.
    • --no-input, --non-interactive, or --noninteractive: Prevents interactive prompts; the command will fail instead if input is required.

  8. Set up Gmail email open tracking

    main

    To enable email open tracking, you must configure a local tracking configuration and link it to a Cloudflare Worker URL. This command creates a local config file containing the worker_url and the active tracking key version. Sensitive keys (tracking and admin keys) are stored in your system's keychain/keyring rather than the JSON config.

    Use the --deploy flag to automatically provision and deploy the worker using wrangler if you are working from the repository root.

  9. Rotate email tracking keys

    main

    To rotate the pixel encryption key without invalidating existing tracking IDs, use gog gmail track key rotate. This command generates a new key version, deploys the necessary TRACKING_KEY_V<N> secrets and updates TRACKING_CURRENT_KEY_VERSION, and updates your local configuration.

    Warning: If you use the --no-deploy flag for local testing, do not send new tracked emails until the Worker has been updated with the matching versioned secret, otherwise the new pixels will not be decryptable.

  12. Configure Google Cloud project and OAuth client with gog auth setup

    main

    Use gog auth setup to automate the creation of a Google Cloud project, enabling necessary APIs, and preparing for OAuth.

    Key Flags:

    • --gcloud-project <project-id>: Specifies the Google Cloud project to use.
    • --enable-apis: Automatically enables the APIs required for the requested services.
    • --open-console: Opens the Google Cloud Console in your browser.
    • --create-project: Creates the specified project if it doesn't exist (requires confirmation).
    • --credentials <path>: Path to the downloaded Desktop OAuth client JSON.
    • --login: Starts the OAuth authorization flow immediately after setup.
    • --dry-run --json --no-input: Inspects the execution plan without making any changes or opening a browser.
    # Guided setup for a specific email and project
gog auth setup you@gmail.com --gcloud-project my-gog-project --enable-apis --open-console

# Complete setup: store credentials and start login
gog auth setup you@gmail.com --gcloud-project my-gog-project \
  --credentials ~/Downloads/client_secret_*.json --login