goog

CLI for managing Gmail and YouTube from the terminal. LLM-powered daily digests. JSON output for piping.

Install

uv tool install .

Setup

1. Create a Google Cloud project

• Go to https://console.cloud.google.com
• Create a new project (or select an existing one)

2. Enable APIs

• Go to APIs & Services > Library
• Enable Gmail API
• Enable YouTube Data API v3

3. Configure OAuth consent screen

• Go to APIs & Services > OAuth consent screen
• Choose External user type
• Fill in app name and support email
• Add scopes: gmail.modify, gmail.settings.basic, and youtube.force-ssl
• Under Test users, add your Gmail address
• Save

Unverified apps are limited to 100 test users and tokens expire every 7 days.

4. Create OAuth credentials

• Go to APIs & Services > Credentials
• Click Create Credentials > OAuth client ID
• Choose Desktop app as the application type
• Download the JSON file and save it:

mkdir -p ~/.config/goog
mv ~/Downloads/client_secret_*.json ~/.config/goog/credentials.json

5. Authenticate

goog auth login

Usage

Gmail

goog gmail search "from:amazon subject:receipt" --json
goog gmail list --label INBOX --unread
goog gmail read <message-id>
goog gmail trash <message-id>
goog gmail label <message-id> --add "Finance"
goog gmail labels
goog gmail bulk-delete "older_than:1y label:promotions" --dry-run
goog gmail stats

Gmail Routine (LLM-powered daily digest)

goog gmail routine                 # Daily digest — what needs your attention
goog gmail routine --full          # Ignore cache, scan everything
goog gmail routine --days 7        # Wider lookback
goog gmail routine -m sonnet       # Use a smarter model

Gmail Filters

goog gmail filters suggest         # Analyze inbox, suggest filters
goog gmail filters create chase.com --label Finance --skip-inbox --apply-existing 1000
goog gmail filters list

Gmail Subscriptions

goog gmail subscriptions           # List all email subscriptions
goog gmail subscriptions open-unsub fandango.com   # Open unsubscribe page

YouTube

goog youtube playlists --json
goog youtube playlist <id>
goog youtube playlist-create "Watch Queue" --privacy private
goog youtube playlist-add <playlist-id> <video-id>
goog youtube search "golang tutorial" --max 10
goog youtube audit --months 12     # Find dead channels
goog youtube audit --months 12 --unsubscribe-dead  # Bulk unsubscribe

YouTube Local Cache

goog youtube subs init             # Populate subscription list from YouTube
goog youtube subs                  # List cached subscriptions
goog youtube subs remove <id>      # Remove a channel
goog youtube subs check-new        # Find new subs not in local list

goog youtube sync --days 30        # Fetch videos → local cache
goog youtube sync stats            # Cache statistics
goog youtube sync rebuild          # Rebuild SQLite from raw JSONL files

goog youtube digest --days 7       # LLM picks best videos this week
goog youtube digest search "spring boot"  # Search local video cache

Pipe to LLM

goog gmail search "is:unread" --json | llm "summarize my unread emails"
goog youtube digest --json | llm "which of these should I watch first?"

Data Storage

All data lives in ~/.config/goog/ (outside the repo):

File	What
credentials.json	OAuth client secret (from Google Cloud Console)
token.json	Your auth token (auto-refreshed)
subscriptions.json	Curated YouTube channel list (editable)
videos/YYYY.jsonl	Raw video data from YouTube API (append-only backup)
goog.db	SQLite — video cache (rebuildable from JSONL)
routine_cache.json	Gmail digest cache (seen message IDs)

Development

uv sync
uv run pytest
uv run ruff check src/ tests/