/setup-gogcli.en

description: "Lesson command"
duration: "~15 min"
prerequisites: ["Have a Google account", "Browser available"]
level: "beginner"
tags: ["setup", "gogcli", "google", "gmail", "calendar", "oauth"]
nonInteractiveMode: incompatible

gogcli (Google Workspace CLI) Setup

Step 0: Check Setup Progress

**What the AI auto-runs:** 1. Run `uv run python tools/setup_progress.py show --current setup-gogcli` to display progress 2. Auto-detect existing installation and authentication:

• Run `which gog` or `gog --version`
• If gogcli is already installed, check authentication status with `gog auth list`
• If installed and authenticated, skip to Step 4 (functionality test)

What You'll Do in This Session

| Item | Details | |------|---------| | Goal | Install gogcli and complete Google OAuth authentication so you can access Gmail/Calendar/Drive/Sheets from the CLI | | Duration | ~15 minutes | | Prerequisites | Have a Google account, browser available | | Skill Level | No CLI commands needed (everything is auto-run by AI + browser OAuth authentication only) |

**Session flow:** 1. Install gogcli (AI auto-detects OS and installs) 2. Perform Google OAuth authentication (AI runs the command, you log in via browser) 3. Verify the authenticated account (AI auto-runs) 4. Gmail/Calendar functionality test (AI auto-runs)

> **Hint**: If the AI's response stops midway, type "please continue" or "it stopped" to resume.

---

Readiness Check

**AskQuestion configuration:**

{
  "title": "Pre-session confirmation",
  "questions": [{
    "id": "readiness",
    "prompt": "Are you ready?",
    "options": [
      {"id": "ready", "label": "Ready! Let's start"},
      {"id": "check_prereq", "label": "I want to check the prerequisites"},
      {"id": "different_lesson", "label": "I want to go to a different lesson"}
    ]
  }]
}

(ready -> Proceed to Step 1) (check_prereq -> Guide: "You're ready if you can log in to a browser with a Google account. gogcli is free to use and operates within Google Workspace API free tier limits.") (different_lesson -> Display module list)

---

Step 1: Install gogcli

**What the AI does:** 1. Auto-detect the OS (Mac / Windows / Linux) 2. Check if already installed: `which gog` (Mac/Linux) or `where gog` (Windows) 3. If not installed, run the following commands:

# Mac / Linux (Homebrew recommended):
brew install gogcli

# Windows:
# Download the ZIP from GitHub Releases, extract gog.exe, and add it to your PATH
# https://github.com/steipete/gogcli/releases

# Linux alternative (if Homebrew is not installed):
# Download the binary directly from GitHub Releases
# https://github.com/steipete/gogcli/releases

4. After installation, verify with `gog --version`

**Installation method decision logic:**

• On Windows -> Download from GitHub Releases (https://github.com/steipete/gogcli/releases)
• `which brew` succeeds -> Install via Homebrew
• Homebrew not available -> Guide through Homebrew installation first (https://brew.sh)

**AskQuestion configuration:**

{
  "title": "Step 1: Install gogcli",
  "questions": [{
    "id": "install_status",
    "prompt": "The gogcli installation has been run. Please check the result.",
    "options": [
      {"id": "installed", "label": "Installed successfully!"},
      {"id": "brew_error", "label": "I got an error with brew install"},
      {"id": "no_brew", "label": "Homebrew is not installed"},
      {"id": "windows", "label": "I'm using Windows"},
      {"id": "command_not_found", "label": "The gog command is not found"}
    ]
  }]
}

(installed -> Proceed to Step 2) (brew_error -> Run `brew update && brew install gogcli` then retry) (no_brew -> Guide: "Let's install Homebrew first. Open https://brew.sh in your browser and copy/run the installation command.") (windows -> Guide: "Download the ZIP from https://github.com/steipete/gogcli/releases, extract gog.exe, and place it in a folder that is in your PATH. Then restart your terminal and verify with `gog --version`.") (command_not_found -> Mac/Linux: Run `brew link gogcli`. Windows: Check that gog.exe has been added to your PATH. If not resolved, guide to restart the terminal)

---

Step 2: Google OAuth Authentication

**What the AI does:** 1. Ask the user which Google account email to use for authentication 2. Run `gog auth add <email>` 3. The browser opens automatically and displays the Google OAuth authentication screen

**Message to display to the user:**

Starting Google OAuth authentication.

+-------------------------------------------------------------+
| The browser will open automatically. Follow these steps to   |
| authenticate:                                                |
|                                                              |
| 1. Select your Google account in the browser (or log in)     |
| 2. On the "Allow this app?" screen, click "Allow"            |
| 3. When "Authorization successful" appears, auth is complete |
| 4. Return to the terminal                                    |
|                                                              |
| * Credentials are securely stored by gogcli                  |
|   (macOS: ~/Library/Application Support/gogcli/              |
|    Linux: ~/.config/gogcli/)                                 |
| * No manual API key entry needed (managed via OAuth)         |
+-------------------------------------------------------------+

**AskQuestion configuration:**

{
  "title": "Step 2: Google OAuth Authentication",
  "questions": [{
    "id": "auth_status",
    "prompt": "Please authenticate your Google account in the browser. Were you able to authenticate?",
    "options": [
      {"id": "authenticated", "label": "Authenticated!"},
      {"id": "browser_not_open", "label": "The browser didn't open"},
      {"id": "auth_error", "label": "I got an authentication error"},
      {"id": "account_help", "label": "I don't know which Google account to choose"},
      {"id":