# gogcli - Google Workspace CLI Skill Control Gmail, Calendar, Drive, Contacts, Sheets, Docs, Tasks, Chat, People, and Classroom from Claude Code using the `gog` command. **Version:** 0.9.0 | **Author:** steipete | **Binary:** `/opt/homebrew/bin/gog` --- ## Quick Start (Already Installed) ```bash gog gmail search "is:unread" # Check unread emails gog calendar events primary # Today's events gog drive ls # List Drive files gog gmail send --to="a@b.com" --subject="Hi" --body="Hello!" ``` --- ## Full Setup SOP (New Install) ### Prerequisites - macOS with Homebrew - A Google account (personal Gmail works) - Claude Code with Playwright MCP (for assisted browser setup) ### Step 1: Install gogcli ```bash brew tap petergriffin42/tap brew install gogcli ``` Verify: ```bash gog --version # v0.9.0+ which gog # /opt/homebrew/bin/gog ``` ### Step 2: Set Up Google Cloud Project You need a GCP project with OAuth credentials. There are two ways to do this: #### Option A: Claude-Assisted Setup via Playwright (Recommended) Ask Claude: *"Help me set up gogcli with my Google account"* Claude will: 1. Open GCP Console in the Playwright browser 2. Navigate to each configuration page for you 3. Tell you what to click or type at each step 4. Handle the tricky parts (Cloud Shell commands, JSON creation) You just need to: - Log in to your Google account when prompted - Click buttons Claude points out - Type your email when asked - Complete the OAuth consent in your browser #### Option B: Manual Setup Follow Steps 2-8 below manually. ### Step 3: Enable 11 Required Google APIs **Fastest: Use Google Cloud Shell** 1. Go to https://shell.cloud.google.com/?show=terminal 2. Wait for the terminal to load 3. Paste and run this single 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 ``` 4. Wait ~30-60 seconds for all APIs to enable

Full API list (click to expand)

| Service | API 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 |

### Step 4: Configure OAuth Consent Screen 1. Go to https://console.cloud.google.com/auth/overview 2. Click **"Get started"** 3. Fill in: - **App name:** `gogcli` - **User support email:** your email 4. Select **External** for audience type 5. Add your email as developer contact 6. Click through to finish (defaults are fine) ### Step 5: Add Yourself as Test User Since the app is in "Testing" mode, your account must be listed as a test user. 1. Go to https://console.cloud.google.com/auth/audience 2. Under **Test users**, click **"Add users"** 3. Enter your Gmail address 4. Click **Save** 5. Confirm it shows "1 user / 100 user cap" ### Step 6: Create OAuth Desktop Client 1. Go to https://console.cloud.google.com/auth/clients 2. Click **"+ CREATE CLIENT"** 3. Choose **Application type: Desktop app** 4. Name it `gogcli` 5. Click **Create** 6. Copy the **Client ID** and **Client Secret** from the dialog ### Step 7: Create Credentials JSON Create a file at `~/Downloads/client_secret_gogcli.json`: ```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"] } } ``` Replace `YOUR_CLIENT_ID`, `YOUR_PROJECT_ID`, and `YOUR_CLIENT_SECRET` with your actual values. > **Tip:** If Claude is assisting via Playwright, it will create this file automatically after reading the credentials from the GCP Console. ### Step 8: Store Credentials & Authenticate ```bash # Store the OAuth credentials gog auth credentials ~/Downloads/client_secret_gogcli.json # Authenticate your Google account gog auth add your-email@gmail.com ``` A browser window opens for OAuth consent. Follow the prompts: 1. Select your Google account 2. Click **"Continue"** on the unverified app warning 3. Click **"Continue"** to grant permissions 4. Done! The browser shows "Authorization received" ### Step 9: Verify ```bash gog gmail labels list ``` If you see your Gmail labels, setup is complete! --- ## Playwright Walkthrough Guide (For Claude) When a user asks Claude to help set up gogcli, Claude uses Playwright MCP to navigate the GCP Console. Here's the cooperative workflow: ### How It Works | Claude does | User does | |------------|-----------| | Navigates to the correct GCP page | Logs in to Google account | | Takes snapshots to find buttons/inputs | Clicks buttons Claude identifies | | Types in Cloud Shell via xterm automation | Types passwords (Claude never sees these) | | Creates the credentials JSON file | Completes OAuth consent in browser | | Runs `gog auth` commands | Verifies the test email | ### Key GCP Console URLs | Page | URL | |------|-----| | Dashboard | `https://console.cloud.google.com/` | | Project Selector | `https://console.cloud.google.com/projectselector2/home/dashboard` | | APIs Library | `https://console.cloud.google.com/apis/library` | | OAuth Consent | `https://console.cloud.google.com/auth/overview` | | Test Users | `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` | ### Known Quirks - **Cloud Shell terminal:** Standard Playwright `fill()` doesn't work. Must use: ```javascript page.locator('.xterm-helper-textarea').first().type(command, { delay: 10 }) ``` - **"Download JSON" button:** Often fails in Playwright. Workaround: read Client ID and Secret from the details page and create the JSON manually. - **Save buttons:** Sometimes need a second click if the first doesn't register. - **GCP Console rendering:** Heavy JavaScript - always take a snapshot after navigation to confirm the page loaded. - **OAuth consent wizard:** Multi-step - snapshot after each step to track progress. --- ## Command Reference ### Output Flags (work with all commands) | Flag | Description | |------|-------------| | `--json` | JSON output (best for scripting) | | `--plain` | Stable TSV output | | `--force` | Skip destructive confirmations | | `--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 # Full message gog gmail send --to="a@b.com" --subject="Hi" --body="Hello" 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 # All calendars gog calendar events primary # 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="Day Off" --from="2024-01-15" --to="2024-01-16" --all-day gog calendar update primary --summary="New Title" gog calendar delete primary gog calendar search "team meeting" gog calendar calendars # List calendars gog calendar freebusy primary --from="2024-01-15" --to="2024-01-16" gog calendar conflicts # Scheduling conflicts ``` > **Important:** Calendar create uses `--from`/`--to` (NOT `--start`/`--end`). Timed events need RFC3339 with timezone: `2024-01-15T10:00:00-05:00` ### Drive ```bash gog drive ls # Root files gog drive ls --folder= # Folder contents gog drive search "quarterly report" # Full-text search gog drive download # Download gog drive download --format=pdf # Export as PDF gog drive upload ./file.pdf # Upload gog drive upload ./file.pdf --folder= gog drive mkdir "New Folder" # Create folder gog drive delete # Trash gog drive move --to= # Move gog drive share --email="user@example.com" --role=writer ``` ### Contacts ```bash gog contacts list # All contacts gog contacts search "John" # Search gog contacts create --given-name="John" --family-name="Doe" --email="j@example.com" gog contacts update --phone="+1234567890" gog contacts delete ``` ### Sheets ```bash gog sheets get "Sheet1!A1:D10" # Read range gog sheets update "Sheet1!A1" "v1" "v2" # Write values gog sheets append "Sheet1!A1" "new1" "new2" # Append row gog sheets clear "Sheet1!A1:D10" # Clear range gog sheets create "New Spreadsheet" # Create new gog sheets export --format=csv # Export ``` ### Docs ```bash gog docs cat # Print as text gog docs info # Metadata gog docs create "New Document" # Create gog docs create "Title" --body="Content" # Create with body gog docs export --format=pdf # Export ``` ### Tasks ```bash gog tasks lists list # Task lists gog tasks list # Tasks in list gog tasks add --title="Buy groceries" --notes="Milk, eggs" gog tasks done # Complete gog tasks undo # Uncomplete gog tasks delete # Delete ``` ### Chat ```bash gog chat spaces list # List spaces gog chat messages list # Messages gog chat messages send --text="Hi!" # Send gog chat dm send --text="Hello" # DM ``` ### People ```bash gog people search "Jane" # Search gog people get # Details ``` --- ## Troubleshooting | Problem | Solution | |---------|----------| | `gog: command not found` | `brew tap petergriffin42/tap && brew install gogcli` | | `401 Unauthorized` | Re-auth: `gog auth add your-email@gmail.com` | | `403 API not enabled` | Enable via Cloud Shell (see Step 3) | | `400 Missing time zone` | Use RFC3339 with offset: `T10:00:00-05:00` | | `unexpected argument` | Run `gog --help` to check syntax | | OAuth "access denied" | Add email as test user (see Step 5) | | Labels command fails | Use `gog gmail labels list` (subcommand required) | --- ## File Locations | File | Path | |------|------| | Binary | `/opt/homebrew/bin/gog` | | Config | `~/Library/Application Support/gogcli/config.json` | | Credentials | `~/Library/Application Support/gogcli/credentials.json` | | Skill definition | `~/.claude/skills/gogcli/SKILL.md` | | Plugin metadata | `~/.claude/skills/gogcli/.claude-plugin/plugin.json` |

gogcli

Installation

SKILL.md