# `gog` CLI — Practical Usage Examples

`gog` is the pre-authenticated read-only CLI for Google Workspace. Preferred over `google_api.py` when available. Credentials at `~/.config/gog/credentials.json`.

## Gmail

### Search
```bash
# Basic search — returns JSON with messages array
gog gmail search "hundetuedel" --max 20

# Search with date range
gog gmail search "from:boss newer_than:7d" --max 10

# Search across multiple terms (OR)
gog gmail search "hundetuedel OR Kirsten Germann OR Christina Korf" --max 20

# Search with multiple fields
gog gmail search "from:andrespaleico subject:expiring" --max 5
```

### Read full email
```bash
gog gmail get MESSAGE_ID
```

Returns nested JSON. Body is often base64-encoded in `payload.parts[]` or `payload.body.data`.

### Extract body text from email (Python one-liner)
```bash
gog gmail get MESSAGE_ID 2>&1 | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
def find_text(parts):
    for p in parts:
        if p.get('mimeType') == 'text/plain' and p.get('body', {}).get('data'):
            return base64.urlsafe_b64decode(p['body']['data']).decode('utf-8', errors='replace')
        if 'parts' in p:
            r = find_text(p['parts'])
            if r: return r
    return None
body = find_text(data.get('payload', {}).get('parts', []))
if not body:
    b = data.get('payload', {}).get('body', {}).get('data', '')
    if b:
        body = base64.urlsafe_b64decode(b).decode('utf-8', errors='replace')
print(body[:3000] if body else 'No text body found')
"
```

### List emails in table format
```bash
gog gmail search "query" --max 20 2>&1 | python3 -c "
import sys, json
data = json.load(sys.stdin)
for m in data.get('messages', []):
    print(f\"{m['date'][:16]} | {m['from'][:40]} | {m['subject'][:60]}\")
"
```

## Drive

### Search files
```bash
gog drive search "hundetuedel" --max 20
# Returns: [{id, name, mimeType, modifiedTime, webViewLink}]

# Search by MIME type
gog drive search "mimeType='application/pdf'" --raw-query --max 5
```

### Get file metadata
```bash
gog drive get FILE_ID
```

## Docs

### Read document content
```bash
gog docs get DOC_ID
```

Returns structured JSON with `body.content[]` array of paragraphs. Each paragraph has `elements[]` with `textRun.content`.

### Extract plain text from doc
```bash
gog docs get DOC_ID 2>&1 | python3 -c "
import sys, json
data = json.load(sys.stdin)
content = data.get('body', {}).get('content', [])
text = ''
for item in content:
    para = item.get('paragraph', {})
    for elem in para.get('elements', []):
        text += elem.get('textRun', {}).get('content', '')
print(text[:3000])
"
```

## Common Pitfalls

1. **`gog` is READ-ONLY.** Cannot send email, create events, or modify files. Use `google_api.py` or `$GAPI` for write operations.
2. **Email body encoding.** `gog gmail get` returns raw API JSON. Body text is base64-encoded — always decode before reading.
3. **Multipart emails.** Some emails have `text/html` only (no `text/plain`). The Python extraction snippet above handles both.
4. **Timeout on large queries.** `gog gmail search` with `--max 30`+ can be slow. Add `newer_than:` date filters to narrow results.
5. **Attachment filenames.** Available in `payload.parts[].filename` — not in the search result snippet.