SkillAgentSearch skills...

Gogcli

Google Suite CLI: Gmail, GCal, GDrive, GContacts.

GenerateConvertImprove

Install / Use

/learn @steipete/Gogcli
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

🧭 gogcli — Google in your terminal.

GitHub Repo Banner

<!-- Created with GitHub Repo Banner by Waren Gonzaga: https://ghrb.waren.build -->

Fast, script-friendly CLI for Gmail, Calendar, Chat, Classroom, Drive, Docs, Slides, Sheets, Forms, Apps Script, Contacts, Tasks, People, Admin, Groups (Workspace), and Keep (Workspace-only). JSON-first output, multiple accounts, and flexible auth built in.

Features

  • Gmail - search threads/messages, send mail, view attachments, manage labels/drafts/filters/delegation/vacation settings, modify single messages, export filters, inspect history, and run Pub/Sub watch webhooks
  • Email tracking - track opens for gog gmail send --track with a small Cloudflare Worker backend
  • Calendar - list/create/update/delete events, manage invitations, aliases, subscriptions, team calendars, free/busy/conflicts, propose new times, focus/OOO/working-location events, recurrence, and reminders
  • Classroom - manage courses, roster, coursework/materials, submissions, announcements, topics, invitations, guardians, profiles
  • Chat - list/find/create spaces, list messages/threads, send messages and DMs, and manage emoji reactions (Workspace-only)
  • Drive - list/search/upload/download files, replace uploads in-place, convert uploads, manage permissions/comments, organize folders, and list shared drives
  • Contacts - search/create/update contacts, including addresses, relations, org/title metadata, custom fields, Workspace directory, and other contacts
  • Tasks - manage tasklists and tasks: get/create/add/update/done/undo/delete/clear, plus repeat schedule materialization with RRULE aliases
  • Sheets - read/write/update spreadsheets, insert rows/cols, manage tabs and named ranges, format/merge/freeze/resize cells, read/write notes, inspect formats, find/replace text, list links, and create/export sheets
  • Forms - create/update forms, manage questions, inspect responses, and manage watches
  • Apps Script - create/get/bind projects, inspect content, and run functions
  • Docs/Slides - create/copy/export docs/slides, edit Docs by tab, import Markdown, do richer find-replace, export Docs as Markdown/HTML, and generate Slides from Markdown or templates
  • People - profile lookup and directory search helpers
  • Keep (Workspace only) - list/get/search/create/delete notes and download attachments (service account + domain-wide delegation)
  • Admin (Workspace only) - Workspace Admin users/groups commands for common directory operations
  • Groups - list groups you belong to, view group members (Google Workspace)
  • Local time - quick local/UTC time display for scripts and agents
  • Multiple accounts - manage multiple Google accounts simultaneously, with account aliases and per-client OAuth buckets
  • Command allowlist - restrict top-level commands for sandboxed/agent runs
  • Secure credential storage using OS keyring or encrypted on-disk keyring (configurable)
  • Auto-refreshing tokens - authenticate once, use indefinitely
  • Flexible auth - OAuth refresh tokens, ADC, direct access tokens, service accounts, manual/remote flows, --extra-scopes, and proxy-safe callbacks
  • Least-privilege auth - --readonly, --drive-scope, and --gmail-scope to request fewer scopes
  • Workspace service accounts - domain-wide delegation auth (preferred when configured)
  • Parseable output - JSON mode for scripting and automation (Calendar adds day-of-week fields)

Installation

Homebrew

brew install gogcli

Arch User Repository

yay -S gogcli

Build from Source

git clone https://github.com/steipete/gogcli.git
cd gogcli
make

Run:

./bin/gog --help

Help:

  • gog --help shows top-level command groups.
  • Drill down with gog <group> --help (and deeper subcommands).
  • For the full expanded command list: GOG_HELP=full gog --help.
  • Make shortcut: make gog -- --help (or make gog -- gmail --help).
  • make gog-help shows CLI help (note: make gog --help is Make’s own help; use --).
  • Version: gog --version or gog version.

Quick Start

1. Get OAuth2 Credentials

Before adding an account, create OAuth2 credentials from Google Cloud Console:

  1. Open the Google Cloud Console credentials page: https://console.cloud.google.com/apis/credentials
  2. Create a project: https://console.cloud.google.com/projectcreate
  3. Enable the APIs you need:
    • Admin SDK API: https://console.cloud.google.com/apis/api/admin.googleapis.com
    • Apps Script API: https://console.cloud.google.com/apis/api/script.googleapis.com
    • Cloud Identity API (Groups): https://console.cloud.google.com/apis/api/cloudidentity.googleapis.com
    • Gmail API: https://console.cloud.google.com/apis/api/gmail.googleapis.com
    • Google Calendar API: https://console.cloud.google.com/apis/api/calendar-json.googleapis.com
    • Google Chat API: https://console.cloud.google.com/apis/api/chat.googleapis.com
    • Google Docs API: https://console.cloud.google.com/apis/api/docs.googleapis.com
    • Google Drive API: https://console.cloud.google.com/apis/api/drive.googleapis.com
    • Google Classroom API: https://console.cloud.google.com/apis/api/classroom.googleapis.com
    • Google Keep API: https://console.cloud.google.com/apis/api/keep.googleapis.com
    • People API (Contacts): https://console.cloud.google.com/apis/api/people.googleapis.com
    • Google Tasks API: https://console.cloud.google.com/apis/api/tasks.googleapis.com
    • Google Sheets API: https://console.cloud.google.com/apis/api/sheets.googleapis.com
    • Google Forms API: https://console.cloud.google.com/apis/api/forms.googleapis.com
    • Google Slides API: https://console.cloud.google.com/apis/api/slides.googleapis.com
  4. Configure OAuth consent screen: https://console.cloud.google.com/auth/branding
  5. If your app is in "Testing", add test users: https://console.cloud.google.com/auth/audience
  6. Create OAuth client:
    • Go to https://console.cloud.google.com/auth/clients
    • Click "Create Client"
    • Application type: "Desktop app"
    • Download the JSON file (usually named client_secret_....apps.googleusercontent.com.json)

2. Store Credentials

gog auth credentials ~/Downloads/client_secret_....json

For multiple OAuth clients/projects:

gog --client work auth credentials ~/Downloads/work-client.json
gog auth credentials list

3. Authorize Your Account

gog auth add you@gmail.com

This will open a browser window for OAuth authorization. The refresh token is stored securely in your system keychain.

Headless / remote server flows (no browser on the server):

Manual interactive flow (recommended):

gog auth add you@gmail.com --services user --manual
  • The CLI prints an auth URL. Open it in a local browser.
  • After approval, copy the full loopback redirect URL from the browser address bar.
  • Paste that URL back into the terminal when prompted.

Split remote flow (--remote, useful for two-step/scripted handoff):

# Step 1: print auth URL (open it locally in a browser)
gog auth add you@gmail.com --services user --remote --step 1

# Step 2: paste the full redirect URL from your browser address bar
gog auth add you@gmail.com --services user --remote --step 2 --auth-url 'http://127.0.0.1:<port>/oauth2/callback?code=...&state=...'
  • The state is cached on disk for a short time (about 10 minutes). If it expires, rerun step 1.
  • Remote step 2 requires a redirect URL that includes state (state check mandatory).

Browser OAuth behind proxies / remote tunnels:

gog auth add you@gmail.com --listen-addr 0.0.0.0:8080 --redirect-host gog.example.com
gog auth manage --listen-addr 0.0.0.0:8080 --redirect-host gog.example.com
  • --listen-addr changes where the local callback server binds.
  • --redirect-host builds https://<host>/oauth2/callback for the OAuth redirect URI.
  • The redirect URI must also be registered in your OAuth client settings.

Direct access token flow (headless/CI, no stored refresh token):

gog --access-token "$(gcloud auth print-access-token)" gmail labels list
  • Also available as GOG_ACCESS_TOKEN
  • Bypasses stored refresh tokens and keyring lookup
  • Token expires in about 1 hour; no auto-refresh

4. Test Authentication

export GOG_ACCOUNT=you@gmail.com
gog gmail labels list

Authentication & Secrets

Accounts and tokens

gog stores your OAuth refresh tokens in a “keyring” backend. Default is auto (best available backend for your OS/environment).

Before you can run gog auth add, you must store OAuth client credentials once via gog auth credentials <credentials.json> (download a Desktop app OAuth client JSON from the Cloud Console). For multiple clients, use gog --client <name> auth credentials ...; tokens are isolated per client.

List accounts:

gog auth list

Verify tokens are usable (helps spot revoked/expired tokens):

gog auth list --check

Accounts can be authorized either via OAuth refresh tokens or Workspace service accounts (domain-wide delegation). If a service account key is configured for an account, it takes precedence over OAuth refresh tokens (see gog auth list).

Show current auth state/services for the active account:

gog auth status

Multiple OAuth clients

Use --client (or GOG_CLIENT) to select a named OAuth client:

gog --client work auth credentials ~/Downloads/work.json
gog --client work auth add you@company.com

Optional domain mapping for auto-selection:

gog --client work auth credentials ~/Downloads/work.json --domain example.com

How it works:

  • Default client is default (stored in credentials.json).
  • Named clients are stored as credentials-<client>.json.
  • Tokens

steipete

View profile

View on GitHub
GitHub Stars6.7k
CategoryDevelopment
Updated17m ago
Forks513
steipete/gogcli

Languages

Go

Security Score

85/100

Audited on Apr 7, 2026

No findings