gogcli Skill

Use gog (installed at /opt/homebrew/bin/gog) to interact with Google Workspace services via CLI. Authenticated account: maneai4bit@gmail.com

Installation & Setup SOP

Follow these steps to install gogcli from scratch and connect it to a Google account.

Step 1: Install gogcli via Homebrew

brew tap petergriffin42/tap
brew install gogcli

Verify installation:

gog --version
# Should output: v0.9.0 or later
which gog
# /opt/homebrew/bin/gog

Step 2: Create or Select a GCP Project

You need a Google Cloud Platform project to host the OAuth credentials and enable APIs.

Option A: Playwright-Assisted Setup (Recommended) Claude navigates the GCP Console via Playwright MCP while the user clicks/inputs when needed.

Claude opens: https://console.cloud.google.com/
If user needs to log in, Claude navigates to the login page and tells the user what to type
Claude navigates to project selector and either selects an existing project or creates a new one
Claude takes snapshots to verify the correct page is loaded before each action

Option B: Manual Setup

Go to https://console.cloud.google.com/
Create a new project or select an existing one
Note your Project ID (visible in project settings)

Step 3: Enable Required Google APIs

gogcli needs 11 APIs enabled. The fastest method is Google Cloud Shell batch command.

Cloud Shell Batch Enable (Fastest Method):

Claude navigates to: https://shell.cloud.google.com/?show=terminal
Wait for the Cloud Shell terminal to load (look for the xterm terminal element)
Important Playwright note: Standard fill() does NOT work in Cloud Shell's xterm terminal. You must use:
```
page.locator('.xterm-helper-textarea').first().type(command, { delay: 10 })
```
Then press Enter via: page.keyboard.press('Enter')
Type this single batch command:

gcloud services enable \
  gmail.googleapis.com \
  calendar-json.googleapis.com \
  drive.googleapis.com \
  people.googleapis.com \
  contacts.googleapis.com \
  sheets.googleapis.com \
  docs.googleapis.com \
  tasks.googleapis.com \
  chat.googleapis.com \
  classroom.googleapis.com \
  admin.googleapis.com

Wait for "Operation finished successfully" for each API (~30-60 seconds total)

Full list of 11 required APIs:

API	Service Name
Gmail	gmail.googleapis.com
Calendar	calendar-json.googleapis.com
Drive	drive.googleapis.com
People	people.googleapis.com
Contacts	contacts.googleapis.com
Sheets	sheets.googleapis.com
Docs	docs.googleapis.com
Tasks	tasks.googleapis.com
Chat	chat.googleapis.com
Classroom	classroom.googleapis.com
Admin SDK	admin.googleapis.com

Alternative: Enable APIs individually via Console UI Claude navigates to https://console.cloud.google.com/apis/library and searches/enables each API one by one. This is slower but works if Cloud Shell is unavailable.

Step 4: Configure OAuth Consent Screen

Claude navigates to: https://console.cloud.google.com/auth/overview
Click "Get started" or "Go to OAuth consent screen"
Configure:
- App name: gogcli
- User support email: select the user's email from dropdown
- Audience: External (for personal Gmail accounts)
- Contact email: enter user's email
Click through to save (Accept defaults for scopes)
Publishing status will be "Testing" - this is fine for personal use

Step 5: Add Test User

Since the app is in "Testing" mode, the Google account must be added as a test user.

Claude navigates to: https://console.cloud.google.com/auth/audience
Under "Test users", click "Add users"
Enter the user's Gmail address (e.g., maneai4bit@gmail.com)
Click "Save"
Verify: should show "1 user / 100 user cap"

Step 6: Create OAuth Desktop Client

Claude navigates to: https://console.cloud.google.com/auth/clients
Click "Create Client" (or "+ CREATE CLIENT")
Select Application type: Desktop app
Name: gogcli
Click "Create"
A dialog shows the Client ID and Client Secret

Getting the credentials JSON:

The "Download JSON" button in GCP Console may not work via Playwright
Workaround: Claude reads the Client ID and Client Secret from the dialog/details page, then creates the JSON file manually:

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "project_id": "YOUR_PROJECT_ID",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uris": ["http://localhost"]
  }
}

Save as: ~/Downloads/client_secret_gogcli.json

To find Client Secret if dialog was closed:

Navigate to https://console.cloud.google.com/auth/clients
Click on the "gogcli" client
Click "Information and summary" button in the side panel
Client Secret is visible (may appear in a copy-button tooltip)

Step 7: Store Credentials in gogcli

gog auth credentials ~/Downloads/client_secret_gogcli.json
# Output: Credentials stored at ~/Library/Application Support/gogcli/credentials.json

Step 8: Authenticate Your Google Account

gog auth add your-email@gmail.com

This opens a browser for Google OAuth. The user must:

Select their Google account
Click "Continue" on the "Google hasn't verified this app" warning
Click "Continue" again to grant permissions
Authorization completes automatically

Verify with:

gog gmail labels list

If labels appear, setup is complete.

Playwright Walkthrough Notes for Claude

When assisting with GCP setup via Playwright MCP:

General approach:

Claude navigates to the correct page using browser_navigate
Claude takes a browser_snapshot to verify the page loaded correctly
Claude identifies the correct elements (buttons, inputs, dropdowns)
Claude tells the user what to click/input OR clicks via browser_click/browser_type
After each action, Claude snapshots again to confirm success

Known Playwright quirks with GCP Console:

Cloud Shell xterm terminal requires .xterm-helper-textarea locator with .type() and { delay: 10 } — standard fill() won't work
File downloads (e.g., "Download JSON") often fail via Playwright — use the manual workaround above
Some Save buttons may require a second click if the first doesn't register
Wait for page loads after navigation; GCP Console uses heavy JS rendering
OAuth consent screen has multi-step wizard — snapshot after each step

Helpful GCP Console URLs:

Page	URL
Project selector	`https://console.cloud.google.com/projectselector2/home/dashboard`
APIs Library	`https://console.cloud.google.com/apis/library`
APIs Dashboard	`https://console.cloud.google.com/apis/dashboard`
OAuth Consent	`https://console.cloud.google.com/auth/overview`
OAuth Audience	`https://console.cloud.google.com/auth/audience`
OAuth Clients	`https://console.cloud.google.com/auth/clients`
Cloud Shell	`https://shell.cloud.google.com/?show=terminal`
IAM & Admin	`https://console.cloud.google.com/iam-admin`

Output Flags

--json for JSON output (best for scripting/parsing)
--plain for stable TSV output
--force to skip confirmations on destructive commands
--no-input never prompt, fail instead

Gmail

gog gmail search "is:unread"              # Search threads
gog gmail search "from:boss subject:urgent" --max=5
gog gmail get <messageId>                 # Get full message
gog gmail get <messageId> --format=raw    # Raw message
gog gmail send --to="user@example.com" --subject="Hello" --body="Message"
gog gmail send --to="a@b.com" --cc="c@d.com" --subject="Hi" --body="Body" --attach=file.pdf
gog gmail labels list                     # List labels
gog gmail labels create "MyLabel"         # Create label
gog gmail thread get <threadId>           # Get thread
gog gmail thread modify <threadId> --add-labels=INBOX --remove-labels=UNREAD
gog gmail drafts list                     # List drafts
gog gmail drafts create --to="a@b.com" --subject="Draft" --body="Content"
gog gmail messages list --label=INBOX --max=10
gog gmail batch archive --query="older_than:30d label:promotions"

Calendar

gog calendar events                       # List events from all calendars
gog calendar events primary               # Events from primary calendar
gog calendar events --from="2024-01-01" --to="2024-01-31"
gog calendar create primary --summary="Meeting" --from="2024-01-15T10:00:00-05:00" --to="2024-01-15T11:00:00-05:00"
gog calendar create primary --summary="All Day" --from="2024-01-15" --to="2024-01-16" --all-day
gog calendar update primary <eventId> --summary="Updated Meeting"
gog calendar delete primary <eventId>
gog calendar search "team meeting"        # Search events
gog calendar calendars                    # List calendars
gog calendar freebusy primary --from="2024-01-15" --to="2024-01-16"
gog calendar conflicts                    # Find scheduling conflicts
gog calendar respond primary <eventId> --status=accepted
gog calendar focus-time --from="2024-01-15T14:00:00" --to="2024-01-15T16:00:00"
gog calendar out-of-office --from="2024-01-20" --to="2024-01-22"

Calendar create important notes:

Uses --from and --to (NOT --start/--end)
Timed events require RFC3339 with timezone offset: 2024-01-15T10:00:00-05:00
All-day events use date-only format with --all-day flag: --from="2024-01-15" --to="2024-01-16"
Available flags: --description, --location, --attendees, --event-color (1-11), --with-meet

Drive

gog drive ls                              # List files in root
gog drive ls --folder=<folderId>          # List files in folder
gog drive search "quarterly report"       # Full-text search
gog drive get <fileId>                    # File metadata
gog drive download <fileId>               # Download file
gog drive download <fileId> --format=pdf  # Export Google Doc as PDF
gog drive upload ./local-file.pdf         # Upload file
gog drive upload ./file.pdf --folder=<folderId>
gog drive mkdir "New Folder"              # Create folder
gog drive mkdir "Subfolder" --parent=<folderId>
gog drive delete <fileId>                 # Move to trash
gog drive move <fileId> --to=<folderId>   # Move file
gog drive rename <fileId> "New Name"      # Rename
gog drive share <fileId> --email="user@example.com" --role=writer
gog drive permissions <fileId>            # List permissions
gog drive url <fileId>                    # Print web URL
gog drive copy <fileId> "Copy Name"       # Copy file
gog drive drives                          # List shared drives

Contacts

gog contacts list                         # List all contacts
gog contacts search "John"               # Search by name/email/phone
gog contacts get <resourceName>           # Get contact details
gog contacts create --given-name="John" --family-name="Doe" --email="john@example.com"
gog contacts update <resourceName> --phone="+1234567890"
gog contacts delete <resourceName>
gog contacts directory list               # Directory contacts
gog contacts other list                   # Other contacts

Sheets

gog sheets get <spreadsheetId> "Sheet1!A1:D10"    # Read range
gog sheets update <spreadsheetId> "Sheet1!A1" "val1" "val2" "val3"  # Write values
gog sheets append <spreadsheetId> "Sheet1!A1" "new1" "new2"         # Append row
gog sheets clear <spreadsheetId> "Sheet1!A1:D10"   # Clear range
gog sheets metadata <spreadsheetId>                 # Sheet metadata
gog sheets create "New Spreadsheet"                 # Create new
gog sheets copy <spreadsheetId> "Copy Title"        # Copy sheet
gog sheets export <spreadsheetId> --format=csv      # Export
gog sheets format <spreadsheetId> "Sheet1!A1:D1" --bold --bg-color="#4285F4"

Docs

gog docs cat <docId>                      # Print doc as plain text
gog docs info <docId>                     # Doc metadata
gog docs create "New Document"            # Create new doc
gog docs create "Doc Title" --body="Initial content"
gog docs copy <docId> "Copy Title"        # Copy doc
gog docs export <docId> --format=pdf      # Export as PDF/DOCX/TXT

Tasks

gog tasks lists list                      # List task lists
gog tasks list <tasklistId>               # List tasks in a list
gog tasks get <tasklistId> <taskId>       # Get task details
gog tasks add <tasklistId> --title="Buy groceries" --notes="Milk, eggs"
gog tasks add <tasklistId> --title="Due tomorrow" --due="2024-01-16"
gog tasks update <tasklistId> <taskId> --title="Updated title"
gog tasks done <tasklistId> <taskId>      # Mark completed
gog tasks undo <tasklistId> <taskId>      # Mark needs action
gog tasks delete <tasklistId> <taskId>    # Delete task
gog tasks clear <tasklistId>              # Clear completed

Chat

gog chat spaces list                      # List chat spaces
gog chat messages list <spaceName>        # List messages in space
gog chat messages send <spaceName> --text="Hello!"  # Send message
gog chat dm send <userId> --text="Hi"     # Direct message
gog chat threads list <spaceName>         # List threads

People

gog people search "Jane"                  # Search people
gog people get <resourceName>             # Get person details

Common Gotchas

gog gmail labels requires a subcommand: list, get, create, or modify
Gmail commands do NOT take an email argument — the authenticated account is used automatically
Calendar create uses --from/--to, NOT --start/--end
Calendar timed events need RFC3339 with timezone (e.g., 2026-02-16T10:00:00-05:00)
Config files stored at: ~/Library/Application Support/gogcli/
Use gog <service> --help for detailed subcommand help
Use --json for programmatic output parsing
Gmail search supports full Gmail query syntax (from:, to:, subject:, is:unread, has:attachment, etc.)
Drive fileIds can be found from URLs or search results

Troubleshooting

Issue	Fix
`gog: command not found`	Run `brew install gogcli` or check `which gog`
`401 Unauthorized`	Re-authenticate: `gog auth add your-email@gmail.com`
`403 API not enabled`	Enable the missing API in GCP Console or via Cloud Shell
`400 Missing time zone`	Calendar create needs RFC3339 with timezone offset
`unexpected argument`	Check `gog <command> --help` — some commands don't take positional email args
OAuth "access denied"	Add your email as test user in OAuth Consent Screen > Audience