gw

name	gw
description	Access Google Workspace via gw CLI (Gmail, Calendar, Drive, Sheets, Docs, Contacts, Tasks, Meet). Permanent OAuth (never expires). Use when: (1) Checking calendar (today/week/agenda), (2) Sending/searching/reading Gmail, (3) Managing Drive files, (4) Reading/writing Sheets, (5) Reading/exporting Docs, (6) Searching contacts.

gw — Google Workspace CLI

Binary: /opt/homebrew/bin/gw (or which gw)
Config: ~/.config/gw/config.toml
Auth: Permanent OAuth 2.0 (auto-refresh, never expires)

Global Flags

Flag	Description
--json	Output as JSON (works on all commands)
--profile TEXT	Use a named profile from config.toml (multi-account)
--version	Show version

---

Auth Commands

gw auth login           # Authorize via browser OAuth
gw auth logout          # Revoke and remove stored token
gw auth status          # Show current auth status / which account
gw auth setup           # Interactive setup wizard (config.toml)

---

Gmail Commands

List / Read

gw gmail list                        # 10 most recent emails
gw gmail list --max 20               # 20 most recent
gw gmail read <message_id>           # Read full email body
gw gmail thread <thread_id>          # Show full thread
gw gmail search "query"              # Search emails (Gmail query syntax)
gw gmail count                       # Count unread messages

Send / Reply / Forward

gw gmail send TO SUBJECT BODY        # Send email
gw gmail send "[e-mail]" "Subject" "Body text"
gw gmail send "[e-mail]" "Subject" "Body" --cc "[e-mail]"
gw gmail send "[e-mail]" "Subject" "Body" --bcc "[e-mail]"
gw gmail draft "[e-mail]" "Subject" "Body text"

gw gmail reply <message_id> "Reply body"
gw gmail forward <message_id> "[e-mail]"

Manage

gw gmail mark-read <message_id>      # Mark as read
gw gmail mark-unread <message_id>    # Mark as unread
gw gmail archive <message_id>        # Archive email
gw gmail trash <message_id>          # Move to trash
gw gmail label <message_id> LABEL    # Apply label
gw gmail star <message_id>           # Star a message

JSON output

gw --json gmail list
gw --json gmail search "from:[e-mail] newer_than:7d"

---

Calendar Commands

View Events

gw calendar today                    # Today (primary calendar)
gw calendar today --all              # Today (all calendars) ← USE THIS
gw calendar tomorrow --all           # Tomorrow (all calendars)
gw calendar week --all               # This week (all calendars)
gw calendar agenda --all             # Upcoming agenda (all calendars)
gw calendar next --all               # Next event
gw calendar list --all               # List events

Create / Update / Delete

# Create event (required: TITLE START END)
gw calendar create "Meeting" "2026-03-27T14:00:00" "2026-03-27T15:00:00"
gw calendar create "Meeting" "2026-03-27T14:00:00" "2026-03-27T15:00:00" \
  --description "Discuss roadmap" \
  --reminder 15 \
  --calendar "calendar_id"

# All-day event
gw calendar create "Birthday" "2026-03-27" "2026-03-28" --all-day

# Recurring event
gw calendar create "Weekly Sync" "2026-03-27T10:00:00" "2026-03-27T11:00:00" \
  --recurrence "RRULE:FREQ=WEEKLY;BYDAY=FR"

gw calendar update <event_id>        # Update event
gw calendar delete <event_id>        # Delete event
gw meet create                       # Create instant Meet link
gw meet create --title "Team Sync"   # Custom instant meeting title

JSON output

gw --json calendar today --all
gw --json calendar week --all

---

Drive Commands

gw drive list                        # List recent files (10)
gw drive list --max 20               # List 20 files
gw drive search "query"              # Search Drive files
gw drive upload /path/to/file        # Upload file
gw drive upload /path/to/file --name "Custom Name"
gw drive upload /path/to/file --folder "folder_id"
gw drive download <file_id>          # Download file
gw drive mkdir "Projects"           # Create folder
gw drive share <file_id> [e-mail] --role writer
gw drive info <file_id>              # Show metadata

JSON output

gw --json drive list
gw --json drive search "report 2026"

---

Sheets Commands

gw sheets read <spreadsheet_id> <range>     # Read cells
gw sheets read "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" "Sheet1!A1:D20"

gw sheets write <spreadsheet_id> <range> <values>  # Write cells
gw sheets write "spreadsheet_id" "Sheet1!A1" '[["Hello", "World"]]'

JSON output

gw --json sheets read "spreadsheet_id" "Sheet1!A1:C10"

---

Docs Commands

gw docs list                         # List recent Docs
gw docs read <document_id>           # Read document content
gw docs export <document_id>         # Export document (PDF, DOCX, etc.)

JSON output

gw --json docs list
gw --json docs read <document_id>

---

Contacts Commands

gw contacts list                     # List all contacts
gw contacts search "query"           # Search contacts by name/email

JSON output

gw --json contacts search "Victor"

---

Tasks Commands

gw tasks lists                       # List task lists
gw tasks list                        # List tasks from the default list
gw tasks list --list <list_id>       # List tasks from a specific list
gw tasks add "Buy milk"              # Create a task
gw tasks add "Buy milk" --notes "2L" --due 2026-04-01
gw tasks complete <task_id>          # Mark task complete
gw tasks delete <task_id>            # Delete task

JSON output

gw --json tasks list
gw --json tasks add "Prepare review" --due 2026-04-02

---

Diagnostics & Config

gw doctor                            # Check auth, API access, config
gw config show                       # Show current config.toml contents
gw --version                         # Show installed version

---

Multi-Account (Profiles)

Define profiles in ~/.config/gw/config.toml:

[profiles.work]
credentials_file = "~/.config/gw/work-credentials.json"

[profiles.personal]
credentials_file = "~/.config/gw/personal-credentials.json"

Use:

gw --profile work calendar today --all
gw --profile personal gmail list

---

Agent Rules

1. Calendar: Always use --all unless user explicitly asks for primary only
2. Gmail send: Show draft (to/subject/body), get confirmation, then execute
3. JSON: Use --json when output needs to be parsed/processed programmatically
4. Auth: Token never expires — no troubleshooting needed
5. Timezone: Uses America/Sao_Paulo automatically