gogcli

---
name: gogcli
description: Google Workspace CLI - manage Gmail, Calendar, Drive, Contacts, Sheets, Docs, Tasks, and more from the command line with JSON output.
---

# gogcli — Google in your terminal

Fast, script-friendly CLI for Gmail, Calendar, Chat, Classroom, Drive, Docs, Slides, Sheets, Forms, Apps Script, Contacts, Tasks, People, Admin, Groups, and Keep.

## Installation

```bash
# Homebrew
brew install gogcli

# Build from source
git clone https://github.com/steipete/gogcli.git
cd gogcli
make
```

## Quick Start

### Setup

```bash
# Store OAuth credentials
gog auth credentials ~/Downloads/client_secret_*.json

# Authorize account
gog auth add you@gmail.com

# Test
gog gmail labels list
```

## Gmail

```bash
# Search emails
gog gmail search 'newer_than:7d subject:project' --max 10

# Send email
gog gmail send --to recipient@example.com --subject "Hello" --body "Message"

# Send HTML email
gog gmail send --to recipient@example.com --subject "Hello" --body "Plain" --body-html "<p>HTML</p>"

# List labels
gog gmail labels list

# Get thread
gog gmail thread get <threadId>
```

## Calendar

```bash
# List today's events
gog calendar events primary --today

# List this week
gog calendar events primary --week

# Create event
gog calendar create primary --summary "Meeting" --from 2025-01-15T10:00:00Z --to 2025-01-15T11:00:00Z

# Search events
gog calendar search "standup" --today
```

## Drive

```bash
# List files
gog drive ls --max 20

# Search files
gog drive search "report" --max 10

# Upload file
gog drive upload ./file.pdf --parent <folderId>

# Download file
gog drive download <fileId> --out ./downloaded.pdf

# Share file
gog drive share <fileId> --to user --email user@example.com --role reader
```

## Sheets

```bash
# Read range
gog sheets get <spreadsheetId> 'Sheet1!A1:D10'

# Update cells
gog sheets update <spreadsheetId> 'A1' 'value1|value2,value3|value4'

# Append row
gog sheets append <spreadsheetId> 'Sheet1!A:D' 'new|row|data'

# Create spreadsheet
gog sheets create "My Spreadsheet" --sheets "Sheet1,Sheet2"
```

## Docs

```bash
# Create doc
gog docs create "My Document"

# Import markdown
gog docs create "My Doc" --file ./document.md

# Export as PDF
gog docs export <docId> --format pdf --out ./doc.pdf

# Read content
gog docs cat <docId> --max-bytes 10000
```

## Contacts

```bash
# List contacts
gog contacts list --max 50

# Search contacts
gog contacts search "John" --max 20

# Create contact
gog contacts create --given "John" --family "Doe" --email "john@example.com" --phone "+1234567890"
```

## Tasks

```bash
# List task lists
gog tasks lists

# Add task
gog tasks add <tasklistId> --title "Buy groceries" --due 2025-02-01

# Mark done
gog tasks done <tasklistId> <taskId>
```

## Output Formats

- Default: Human-friendly tables
- --json: Structured JSON (best for agents)
- --plain: Tab-separated values

## Environment Variables

```bash
export GOG_ACCOUNT=you@gmail.com
export GOG_CLIENT=work  # For multiple OAuth clients
export GOG_JSON=1       # Default JSON output
```

## Multi-Account Setup

```bash
# Set up work account
gog --client work auth credentials ~/Downloads/work-client.json
gog --client work auth add work@company.com
gog auth alias set work work@company.com

# Use alias
gog gmail list --account work
```