ez-google

# ez-google

Agent-friendly Google Workspace tools. Simple CLI scripts with hosted OAuth - users just click a link and paste back a token. No API keys or credentials needed.

**Run all commands with:** `uv run scripts/<script>.py <command> [args]`

## Auth (do this first)

```bash
auth.py status        # Check: AUTHENTICATED or NOT_AUTHENTICATED
auth.py login         # Get URL → send to user
auth.py save '<TOKEN>'  # Save token from hosted OAuth
```

**Auth flow:** `status` → if not authenticated → `login` → user clicks link, copies token → `save '<TOKEN>'`

---

## Gmail

```bash
gmail.py list [-n 10] [-q "query"]   # List emails
gmail.py search "query"              # Search emails
gmail.py get MESSAGE_ID              # Read email
gmail.py send "to" "subject" "body"  # Send email
gmail.py draft "to" "subject" "body" # Create draft
gmail.py labels                      # List labels

# Bulk operations (up to 1000 messages per API call)
gmail.py bulk-label "query" --add LABEL --remove LABEL  # Add/remove labels
gmail.py bulk-trash "query" [-y]     # Move to trash (use -y to skip confirmation)
```

**Bulk examples:**
```bash
gmail.py bulk-label "from:newsletter@example.com" --add ARCHIVE --remove INBOX
gmail.py bulk-trash "subject:alert older_than:30d" -y
gmail.py bulk-label "category:promotions" --add Label_3  # Use label IDs from `labels`
```

## Calendar

```bash
gcal.py list [DATE]                  # List events (DATE: YYYY-MM-DD or "today")
gcal.py create "title" "START" "END" # Create event (START/END: YYYY-MM-DDTHH:MM)
gcal.py get EVENT_ID                 # Event details
gcal.py delete EVENT_ID              # Delete event
gcal.py calendars                    # List calendars
```

## Drive

```bash
drive.py list [-n 20]                # List files
drive.py search "query"              # Search by name
drive.py get FILE_ID                 # File metadata
drive.py download FILE_ID            # File content
drive.py create-folder "name"        # Create folder
```

##...