gogcli

What this skill does

# gogcli — Google Workspace in the terminal

`gogcli` (binary name: `gog`) is a single Go CLI that covers Gmail, Calendar, Drive, Docs, Slides, Sheets, Chat, Tasks, Contacts, People, Classroom, Forms, Apps Script, Keep, Admin (Directory), and Cloud Identity Groups. It is JSON-first, multi-account, and designed for agents as well as humans.

**Binary:** `gog` (not `gogcli`). **Repo:** `github.com/steipete/gogcli`. **Latest release at time of writing:** 0.12.0.

---

## When to Use

Trigger this skill whenever the user asks to do any of the following from the terminal or a script/agent:

- Send, draft, or reply to a Gmail message; search Gmail with operators (`from:`, `newer_than:7d`, `is:unread`); manage labels, filters, vacation responder, send-as, delegates, or forwarding.
- Create/list/update/delete Google Calendar events, including recurring events (RRULE), focus-time, out-of-office, working-location, and free/busy lookups.
- List, search, upload, download, replace, move, share, or permission-manage Google Drive files and folders, including shared drives and Workspace file conversions.
- Read/write/append/clear Google Sheets ranges, insert rows/columns, manage tabs and named ranges, apply formatting/merge/freeze/number-format, or run find/replace.
- Create, edit, find/replace, sed-regex-edit, or export Google Docs; generate Slides decks from Markdown or templates; export Docs/Slides as PDF/DOCX/PPTX/Markdown.
- Manage Google Contacts (CRUD with custom fields), query the Workspace directory, or manage Google Tasks with client-materialized recurrence.
- Post messages to Google Chat spaces/DMs/threads; manage reactions.
- Administer a Google Workspace domain (users, groups, members) via a domain-wide-delegation service account.
- Authenticate one or more Google accounts for CLI/CI/headless use via OAuth, Application Default Credentials, a direct access token, or a service account.
- Build agent workflows that need stable JSON output, deterministic exit codes, a machine-readable schema of the CLI, or a command allowlist sandbox.
- Operate Pub/Sub push handlers for Gmail or Forms; set up email-open tracking via a Cloudflare Worker.

---

## Prerequisites

### Install the `gog` binary

```bash
# macOS / Linux (Homebrew Core)
brew install gogcli

# Arch Linux (AUR)
yay -S gogcli

# From source (Go 1.25+)
git clone https://github.com/steipete/gogcli.git
cd gogcli
make            # outputs ./bin/gog
```

### Verify

```bash
command -v gog && gog --version
```

### Google Cloud project

Each service group calls a different API. Enable the APIs you need on the Google Cloud project that owns your OAuth client (or service account):

- Gmail, Calendar, Drive, Docs, Slides, Sheets, People, Tasks API for the user-facing groups.
- Chat API for `chat` (Workspace only).
- Admin SDK + Cloud Identity API for `admin` and `groups` (DWD service account).
- Classroom, Forms, Apps Script, Keep APIs for the respective groups.

The upstream README lists the enable URLs for each. `gog auth services` prints the full scope list needed when registering DWD.

---

## First-time setup (OAuth, single account)

```bash
# 1. Store a Desktop OAuth client JSON once.
gog auth credentials /path/to/client_secret.json

# 2. Launch browser OAuth and persist a refresh token in the OS keyring.
gog auth add [email protected]

# 3. Verify status and stored accounts.
gog auth status
gog auth list --check
```

For headless/CI, ADC, service-account (DWD), `--manual`, `--remote`, `--access-token`, custom redirect URIs, least-privilege scope flags (`--services`, `--readonly`, `--drive-scope`, `--gmail-scope`, `--extra-scopes`), multiple OAuth clients, and keyring backends (`keychain` / `file` / `auto`), see **[references/auth.md](references/auth.md)**.

---

## Agent-mode essentials

### Output modes

| Flag / Env | Effect |
|---|---|
| `--json` (alias `--machine`, `-j`) | Emit JSON on stdout. |
| `--plain` (alias `--tsv`, `-p`) | Stable TSV on stdout; disables colors. |
| `GOG_AUTO_JSON=1` | Auto-switch to JSON when stdout is not a TTY. Opt-in agent mode. |
| `GOG_JSON=1` / `GOG_PLAIN=1` | Force mode (overridden by explicit flags). |
| `--select`/`--fields`/`--pick`/`--project <a,b,c>` | Project only these dot-paths from JSON output. |
| `--results-only` | Strip envelope (`nextPageToken`, etc.); emit only the primary result. |
| `NO_COLOR=1` | Disable ANSI colors. |

**Gotcha:** `--fields` is silently rewritten to `--select` everywhere **except** `calendar events|ls|list`, where `fields` is the Calendar API selector. Use `--select` to be unambiguous.

### Safety rails

| Flag | Effect |
|---|---|
| `--dry-run` (aliases `-n`, `--noop`, `--preview`, `--dryrun`) | Print intended actions, succeed. Honored by destructive commands (`gmail archive|read|unread|trash`, `drive delete`, `sheets delete-tab`, `forms delete-question`, etc.). |
| `--force` (aliases `-y`, `--yes`, `--assume-yes`) | Skip confirmations. |
| `--no-input` / `--non-interactive` | Never prompt; fail instead. Public Drive shares, Gmail forwarding filters, and delegate grants still require `--force`. |
| `--verbose` | Extra diagnostic output on stderr. |

### Schema + exit codes for agents

```bash
gog schema                  # Full CLI JSON schema (aliases: help-json, helpjson).
gog schema calendar create  # Scope to a sub-tree.
gog agent exit-codes        # Stable exit-code table (also `gog exit-codes`).
gog completion zsh          # Generate shell completion (bash|zsh|fish|pwsh).
GOG_HELP=full gog --help    # Expanded help with all commands.
```

**Stable exit codes:**

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Generic failure |
| 2 | Usage / parse error |
| 3 | Empty result set (paging) |
| 4 | Auth required (401, keyring miss, auth errors) |
| 5 | Not found (404) |
| 6 | Permission denied (403 non-quota) |
| 7 | Rate limited (403 quota, 429) |
| 8 | Retryable (5xx, timeouts, deadline exceeded) |
| 10 | Config error (e.g. missing OAuth credentials) |
| 130 | Cancelled (SIGINT / context canceled) |

### Sandbox for agent runs

```bash
# Only these top-level groups are callable; everything else errors out.
gog --enable-commands calendar,tasks events --today
GOG_ENABLE_COMMANDS=calendar,tasks gog events --today
```

### Account selection

```bash
gog --account [email protected] events --today
GOG_ACCOUNT=work-alias gog drive ls --max 20

# Set a friendly alias once.
gog auth alias set work [email protected]
```

Reserved alias words: `auto`, `default`. `--account auto` resolves to the default or sole stored account.

---

## Core workflow patterns

### Send a Gmail reply with quoted thread text

```bash
gog gmail drafts create --to [email protected] \
  --subject "Re: Status" --body "See below." \
  --reply-to-message-id 193a... --quote --json
```

### List today's calendar events as JSON, only a few fields

```bash
gog events --today --json --select "summary,startLocal,endLocal,attendees[].email"
```

### Upload a local file to Drive, replacing an existing Doc

```bash
gog drive upload ./spec.md --replace 1A2b3C... --convert-to doc --json
```

### Read a named range from a spreadsheet

```bash
gog sheets get <spreadsheetId> "Roster" --json --results-only
```

### Batch-modify Gmail label on matching threads

```bash
# Preview first.
gog gmail search "label:inbox older_than:30d" --max 200 --json --select "id" \
  | jq -r '.[].id' \
  | xargs -n1 -I{} gog gmail thread modify {} --add Archive --dry-run

# Then apply.
... (drop --dry-run)
```

### Agent-safe call: JSON, dry-run, explicit account, field projection

```bash
gog --account work --no-input \
    calendar create primary \
    --summary "Focus block" --from "2026-04-17T09:00:00-07:00" \
    --to "2026-04-17T11:00:00-07:00" --event-type focus-time \
    --dry-run --json --results-only
```

---

## Quick command reference

Top-level groups (aliases in parentheses):

| Group | One-liner |
|---|---|
| `gmail` (`mail`, `email`) | Search/read/send, labels, drafts, filters, delegat