# Gogcli > Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, Docs, Tasks, Chat, People, and Classroom via the `gog` command - Skill: `tivojn/gogcli` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tivojn/gogcli` - Raw SKILL.md: https://api.skillmd.com/api/skills/tivojn/gogcli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tivojn (https://skillmd.com/u/tivojn) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tivojn/gogcli --- # 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 ```bash brew tap petergriffin42/tap brew install gogcli ``` Verify installation: ```bash 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. 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: ```javascript page.locator('.xterm-helper-textarea').first().type(command, { delay: 10 }) ``` Then press Enter via: `page.keyboard.press('Enter')` 4. Type this single batch command: ```bash 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., `maneai4bit@gmail.com`) 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: ```json { "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 ```bash gog auth credentials ~/Downloads/client_secret_gogcli.json # Output: Credentials stored at ~/Library/Application Support/gogcli/credentials.json ``` ### Step 8: Authenticate Your Google Account ```bash gog auth add your-email@gmail.com ``` 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: ```bash 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 ```bash gog gmail search "is:unread" # Search threads gog gmail search "from:boss subject:urgent" --max=5 gog gmail get # Get full message gog gmail get --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 # Get thread gog gmail thread modify --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 ```bash 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 --summary="Updated Meeting" gog calendar delete primary 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 --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 ```bash gog drive ls # List files in root gog drive ls --folder= # List files in folder gog drive search "quarterly report" # Full-text search gog drive get # File metadata gog drive download # Download file gog drive download --format=pdf # Export Google Doc as PDF gog drive upload ./local-file.pdf # Upload file gog drive upload ./file.pdf --folder= gog drive mkdir "New Folder" # Create folder gog drive mkdir "Subfolder" --parent= gog drive delete # Move to trash gog drive move --to= # Move file gog drive rename "New Name" # Rename gog drive share --email="user@example.com" --role=writer gog drive permissions # List permissions gog drive url # Print web URL gog drive copy "Copy Name" # Copy file gog drive drives # List shared drives ``` ## Contacts ```bash gog contacts list # List all contacts gog contacts search "John" # Search by name/email/phone gog contacts get # Get contact details gog contacts create --given-name="John" --family-name="Doe" --email="john@example.com" gog contacts update --phone="+1234567890" gog contacts delete gog contacts directory list # Directory contacts gog contacts other list # Other contacts ``` ## Sheets ```bash gog sheets get "Sheet1!A1:D10" # Read range gog sheets update "Sheet1!A1" "val1" "val2" "val3" # Write values gog sheets append "Sheet1!A1" "new1" "new2" # Append row gog sheets clear "Sheet1!A1:D10" # Clear range gog sheets metadata # Sheet metadata gog sheets create "New Spreadsheet" # Create new gog sheets copy "Copy Title" # Copy sheet gog sheets export --format=csv # Export gog sheets format "Sheet1!A1:D1" --bold --bg-color="#4285F4" ``` ## Docs ```bash gog docs cat # Print doc as plain text gog docs info # Doc metadata gog docs create "New Document" # Create new doc gog docs create "Doc Title" --body="Initial content" gog docs copy "Copy Title" # Copy doc gog docs export --format=pdf # Export as PDF/DOCX/TXT ``` ## Tasks ```bash gog tasks lists list # List task lists gog tasks list # List tasks in a list gog tasks get # Get task details gog tasks add --title="Buy groceries" --notes="Milk, eggs" gog tasks add --title="Due tomorrow" --due="2024-01-16" gog tasks update --title="Updated title" gog tasks done # Mark completed gog tasks undo # Mark needs action gog tasks delete # Delete task gog tasks clear # Clear completed ``` ## Chat ```bash gog chat spaces list # List chat spaces gog chat messages list # List messages in space gog chat messages send --text="Hello!" # Send message gog chat dm send --text="Hi" # Direct message gog chat threads list # List threads ``` ## People ```bash gog people search "Jane" # Search people gog people get # 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 --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 --help` — some commands don't take positional email args | | OAuth "access denied" | Add your email as test user in OAuth Consent Screen > Audience |