avifenesh/gogcli

gogcli Skill

IMPORTANT: Google Workspace ONLY

This skill is for Google Workspace services ONLY: Gmail, Calendar, Drive, Contacts, Sheets, Docs, Tasks, Chat, People, and Classroom.

Never use this skill for GitHub or git operations.

• For GitHub operations: use cairn.shell with the gh CLI.
• For git operations: use cairn.shell or cairn.gitRun.
• Never pass gh pr view, gh pr create, git status, git log, or any git/GitHub command to gog.
• Never call cairn.googleQuery or cairn.googleExecute for GitHub — they are Google Workspace tools only.

Misrouting git/GitHub commands to gog causes 100+ errors per period. Use the right tool.

---

Use gog (installed at /usr/local/bin/gog) to interact with Google Workspace services via CLI. Authenticated account is configured via gog auth add.

---

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
# /usr/local/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.

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

Option B: Manual Setup

1. Go to https://console.cloud.google.com/
2. Create a new project or select an existing one
3. 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):

1. Claude navigates to: https://shell.cloud.google.com/?show=terminal
2. Wait for the Cloud Shell terminal to load (look for the xterm terminal element)
3. 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')
4. 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

5. 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

1. Claude navigates to: https://console.cloud.google.com/auth/overview
2. Click "Get started" or "Go to OAuth consent screen"
3. 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
4. Click through to save (Accept defaults for scopes)
5. 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.

1. Claude navigates to: https://console.cloud.google.com/auth/audience
2. Under "Test users", click "Add users"
3. Enter the user's Gmail address (e.g., [email protected])
4. Click "Save"
5. Verify: should show "1 user / 100 user cap"

Step 6: Create OAuth Desktop Client

1. Claude navigates to: https://console.cloud.google.com/auth/clients
2. Click "Create Client" (or "+ CREATE CLIENT")
3. Select Application type: Desktop app
4. Name: gogcli
5. Click "Create"
6. 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:

1. Navigate to https://console.cloud.google.com/auth/clients
2. Click on the "gogcli" client
3. Click "Information and summary" button in the side panel
4. 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 ~/.config/gogcli/credentials.json

Step 8: Authenticate Your Google Account

gog auth add [email protected]

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

1. Select their Google account
2. Click "Continue" on the "Google hasn't verified this app" warning
3. Click "Continue" again to grant permissions
4. 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

IMPORTANT: Gmail search filters (from:, to:, subject:, is:, has:, newer_than:, older_than:, in:, label:) are NOT CLI flags. They go INSIDE the quoted query string. Never use --from: or --subject: as flags.

# Correct: filters inside quoted query string
gog gmail search "is:unread"
gog gmail search "from:boss subject:urgent" --max=5
gog gmail search "from:ceo newer_than:7d" --max=10
gog gmail search "subject:budget from:finance" --max=5
gog gmail search "in:trash from:noreply"

# WRONG — these will fail:
# gog gmail search --from:boss              ← WRONG: --from: is not a flag
# gog gmail search --subject:budget         ← WRONG: --subject: is not a flag
# gog gmail search --newer_than:7d          ← WRONG: put inside quotes

gog gmail get <messageId>                 # Get full message
gog gmail get <messageId> --format=raw    # Raw message
gog gmail send --to="[email protected]" --subject="Hello" --body="Message"
gog gmail send --to="[email protected]" --cc="[email protected]" --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="[email protected]" --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="[email protected]" --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="[email protected]"
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: ~/.config/gogcli/
• Use gog <service> --help for detailed subcommand help
• Use --json for programmatic output parsing
• Gmail search filters go INSIDE the quoted query string, not as CLI flags: gog gmail search "from:X subject:Y" not gog gmail search --from:X
• 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 [email protected] | | 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 |