ckorhonen/google

Google Personal Assistant

A comprehensive skill for managing Google Workspace services via the gog CLI. Designed for Personal Assistant and Chief of Staff workflows with emphasis on efficient searching, filtering, and querying.

When to Use This Skill

• Triaging and processing email inbox
• Scheduling meetings and managing calendar events
• Finding availability across multiple calendars
• Searching and organizing Google Drive documents
• Managing task lists and to-dos
• Looking up and managing contacts
• Reading/writing data in Google Sheets
• Exporting Docs, Slides, or Sheets
• Setting focus time or out-of-office status

Prerequisites

Ensure gog is installed and authenticated:

# Check installation
gog version

# Check authentication status
gog auth status

# Verify account access
gog people me

# Add a new account if needed
gog auth add [email protected] --services=all

Quick Start

Gmail

# Search unread emails
gog gmail search "is:unread" --max=20

# Search from specific sender
gog gmail search "from:[email protected] newer_than:7d"

# Send an email
gog gmail send --to="[email protected]" --subject="Subject" --body="Message body"

# Reply to a thread
gog gmail send --reply-to-message-id=MESSAGE_ID --body="Reply text"

# Get message details
gog gmail get MESSAGE_ID

Calendar

# View today's events
gog calendar events --today

# View this week
gog calendar events --week

# Create an event with Google Meet
gog calendar create primary \
  --summary="Team Sync" \
  --from="2026-01-15T14:00:00-08:00" \
  --to="2026-01-15T15:00:00-08:00" \
  --attendees="[email protected],[email protected]" \
  --with-meet

# Check availability
gog calendar freebusy "[email protected],[email protected]" \
  --from="2026-01-15T09:00:00Z" --to="2026-01-15T17:00:00Z"

# Find scheduling conflicts
gog calendar conflicts --week

Drive

# List files in root
gog drive ls

# Search for documents
gog drive search "quarterly report"

# Download a file
gog drive download FILE_ID

# Upload a file
gog drive upload /path/to/file.pdf --parent=FOLDER_ID

# Get shareable URL
gog drive url FILE_ID

Tasks

# List task lists
gog tasks lists list

# View tasks in default list
gog tasks list @default

# Add a task
gog tasks add @default --title="Review report" --due="2026-01-15"

# Mark task complete
gog tasks done @default TASK_ID

Sheets

# Read a range
gog sheets get SPREADSHEET_ID "Sheet1!A1:D10"

# Update values
gog sheets update SPREADSHEET_ID "Sheet1!A1" "Value1" "Value2"

# Append a row
gog sheets append SPREADSHEET_ID "Sheet1!A:D" "Col1" "Col2" "Col3" "Col4"

Gmail Search Syntax

Gmail search is powerful. Here are the essential operators:

Sender & Recipient

| Operator | Example | Description | |----------|---------|-------------| | from: | from:[email protected] | Emails from sender | | to: | to:[email protected] | Emails sent to recipient | | cc: | cc:[email protected] | CC'd recipient | | bcc: | bcc:[email protected] | BCC'd recipient |

Status & Labels

| Operator | Example | Description | |----------|---------|-------------| | is:unread | is:unread | Unread messages | | is:read | is:read | Read messages | | is:starred | is:starred | Starred messages | | is:important | is:important | Marked important | | is:snoozed | is:snoozed | Snoozed messages | | label: | label:work | Has specific label | | in:inbox | in:inbox | In inbox | | in:sent | in:sent | In sent folder | | in:drafts | in:drafts | In drafts | | in:trash | in:trash | In trash | | in:spam | in:spam | In spam | | in:anywhere | in:anywhere | All mail including spam/trash |

Content & Subject

| Operator | Example | Description | |----------|---------|-------------| | subject: | subject:urgent | Subject contains word | | "exact phrase" | "quarterly report" | Exact phrase match | | has:attachment | has:attachment | Has any attachment | | filename: | filename:pdf | Attachment filename/type | | filename: | filename:report.xlsx | Specific filename |

Date & Time

| Operator | Example | Description | |----------|---------|-------------| | newer_than: | newer_than:7d | Within last N days | | older_than: | older_than:1y | Older than N years | | after: | after:2026/01/01 | After specific date | | before: | before:2026/12/31 | Before specific date |

Units for newer_than/older_than: d (day), m (month), y (year)

Size

| Operator | Example | Description | |----------|---------|-------------| | larger: | larger:5M | Larger than size | | smaller: | smaller:100K | Smaller than size |

Units: K (KB), M (MB)

Categories

| Operator | Example | Description | |----------|---------|-------------| | category:primary | category:primary | Primary inbox | | category:social | category:social | Social category | | category:promotions | category:promotions | Promotions | | category:updates | category:updates | Updates | | category:forums | category:forums | Forums |

Boolean Operators

| Operator | Example | Description | |----------|---------|-------------| | AND (or space) | from:alice subject:report | Both conditions | | OR | from:alice OR from:bob | Either condition | | - (NOT) | -category:promotions | Exclude condition | | () | (from:alice OR from:bob) is:unread | Grouping | | {} | {from:alice from:bob} | OR shorthand |

Example Queries

# Unread from VIPs this week
gog gmail search "is:unread from:([email protected] OR [email protected]) newer_than:7d"

# Large attachments
gog gmail search "has:attachment larger:10M"

# Urgent subjects excluding promotions
gog gmail search "subject:(urgent OR asap OR EOD) -category:promotions is:unread"

# Contracts from legal team
gog gmail search "from:[email protected] subject:contract has:attachment filename:pdf"

# All messages in a thread (use thread ID from search results)
gog gmail thread get THREAD_ID

See references/gmail-search-syntax.md for complete operator reference.

Drive Search Syntax

Drive search uses a query language for precise file finding:

Basic Operators

| Operator | Example | Description | |----------|---------|-------------| | name contains | name contains 'report' | Filename contains | | fullText contains | fullText contains 'budget' | Content search | | mimeType = | mimeType = 'application/pdf' | File type |

Date Filters

| Operator | Example | Description | |----------|---------|-------------| | modifiedTime > | modifiedTime > '2026-01-01' | Modified after | | modifiedTime < | modifiedTime < '2026-01-01' | Modified before | | createdTime > | createdTime > '2026-01-01' | Created after | | viewedByMeTime > | viewedByMeTime > '2026-01-01' | Viewed after |

Ownership & Sharing

| Operator | Example | Description | |----------|---------|-------------| | 'email' in owners | 'me' in owners | Owned by user | | 'email' in writers | '[email protected]' in writers | User can edit | | 'email' in readers | '[email protected]' in readers | User can view | | sharedWithMe | sharedWithMe | Shared with you |

Properties

| Operator | Example | Description | |----------|---------|-------------| | starred | starred | Starred files | | trashed = false | trashed = false | Not in trash | | 'folderId' in parents | 'FOLDER_ID' in parents | In specific folder |

Common MIME Types

| Type | MIME Type | |------|-----------| | Google Doc | application/vnd.google-apps.document | | Google Sheet | application/vnd.google-apps.spreadsheet | | Google Slides | application/vnd.google-apps.presentation | | Google Form | application/vnd.google-apps.form | | Folder | application/vnd.google-apps.folder | | PDF | application/pdf | | Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document | | Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |

Boolean Operators

• and - Both conditions must match
• or - Either condition matches
• not - Negate condition

Example Queries

# Recent docs mentioning Q4
gog drive search "fullText contains 'Q4' and modifiedTime > '2026-01-01'"

# All spreadsheets shared with me
gog drive search "sharedWithMe and mimeType = 'application/vnd.google-apps.spreadsheet'"

# PDFs I own
gog drive search "'me' in owners and mimeType = 'application/pdf'"

# Files modified this week
gog drive search "modifiedTime > '2026-01-03'"

# Documents in specific folder
gog drive ls --parent=FOLDER_ID

# Starred presentations
gog drive search "starred and mimeType = 'application/vnd.google-apps.presentation'"

See references/drive-search-syntax.md for complete query reference.

PA/CoS Workflows

Morning Inbox Triage

# 1. Check unread counts by label
gog gmail labels list --json | jq '.[] | select(.messagesUnread > 0) | {name, unread: .messagesUnread}'

# 2. Review unread from priority senders
gog gmail search "is:unread from:([email protected] OR [email protected])" --max=20

# 3. Check for urgent subjects
gog gmail search "is:unread subject:(urgent OR asap OR EOD OR \"action required\")" --max=10

# 4. Review threads needing response (excludes noise)
gog gmail search "is:unread in:inbox -category:updates -category:promotions -category:social" --max=30

# 5. Check for emails with attachments requiring action
gog gmail search "is:unread has:attachment newer_than:2d" --max=15

Schedule a Meeting

# 1. Find availability for attendees
gog calendar freebusy "[email protected],[email protected]" \
  --from="2026-01-15T09:00:00-08:00" \
  --to="2026-01-15T17:00:00-08:00"

# 2. Check your own conflicts
gog calendar conflicts --days=7

# 3. Create the meeting
gog calendar create primary \
  --summary="Project Kickoff" \
  --from="2026-01-15T14:00:00-08:00" \
  --to="2026-01-15T15:00:00-08:00" \
  --attendees="[email protected],[email protected]" \
  --description="Agenda:\n1. Project overview\n2. Timeline review\n3. Action items" \
  --location="Conference Room A" \
  --with-meet \
  --reminder="popup:15m"

# 4. Send follow-up email with details
gog gmail send \
  --to="[email protected],[email protected]" \
  --subject="Meeting Scheduled: Project Kickoff - Jan 15 at 2pm" \
  --body="Hi team,

I've scheduled our project kickoff meeting for Wednesday, January 15th at 2:00 PM.

Location: Conference Room A (Google Meet link in calendar invite)

Agenda:
1. Project overview
2. Timeline review
3. Action items

Please let me know if you have any conflicts.

Best regards"

Weekly Calendar Prep

# 1. View the week ahead
gog calendar events --week

# 2. Check all calendars for the week
gog calendar events --week --all

# 3. Find and resolve conflicts
gog calendar conflicts --week

# 4. Check team availability (for group)
gog calendar team [email protected] --week

# 5. Block focus time
gog calendar focus-time \
  --from="2026-01-16T09:00:00-08:00" \
  --to="2026-01-16T12:00:00-08:00"

# 6. Set out of office (if needed)
gog calendar out-of-office \
  --from="2026-01-20" \
  --to="2026-01-21" \
  --summary="Out of office - personal day"

# 7. Set working location
gog calendar working-location \
  --from="2026-01-17" \
  --to="2026-01-17" \
  --type="home"

Document Search & Organization

# Find all docs from a project
gog drive search "fullText contains 'Project Alpha'"

# List recent docs you created
gog drive search "'me' in owners and modifiedTime > '2026-01-01'" --max=50

# Find docs shared by specific person
gog drive search "'[email protected]' in writers"

# Find presentation decks
gog drive search "mimeType = 'application/vnd.google-apps.presentation' and modifiedTime > '2025-10-01'"

# Download a doc as PDF
gog docs export DOC_ID --format=pdf --output="./report.pdf"

# Read doc contents (plain text for quick review)
gog docs cat DOC_ID

# Export spreadsheet as Excel
gog sheets export SPREADSHEET_ID --format=xlsx --output="./data.xlsx"

# Get shareable link
gog drive url FILE_ID
gog drive share FILE_ID --role=reader --type=anyone

Daily Task Management

# 1. List all task lists
gog tasks lists list

# 2. View all tasks in default list
gog tasks list @default

# 3. View tasks due today
gog tasks list @default --due-max="$(date -u +%Y-%m-%dT23:59:59Z)"

# 4. Add a new task with due date
gog tasks add @default \
  --title="Review Q4 financials" \
  --due="2026-01-15" \
  --notes="Check revenue projections and expense reports"

# 5. Complete a task
gog tasks done @default TASK_ID

# 6. Reopen a completed task
gog tasks undo @default TASK_ID

# 7. Delete a task
gog tasks delete @default TASK_ID

# 8. Clear all completed tasks
gog tasks clear @default

Contact Lookup

# Search for a contact
gog contacts search "John Smith"

# List all contacts
gog contacts list --max=100

# Get contact details
gog contacts get RESOURCE_NAME

# Create a new contact
gog contacts create \
  --given="Jane" \
  --family="Doe" \
  --email="[email protected]" \
  --phone="+1-555-123-4567"

# Search directory (Workspace)
gog contacts directory search "engineering"

See references/common-workflows.md for more workflow recipes.

Command Reference

Gmail Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | gmail search <query> | Search threads | --max, --oldest, --page | | gmail get <messageId> | Get message content | --format=full\|metadata\|raw | | gmail send | Send email | --to, --cc, --bcc, --subject, --body, --attach | | gmail thread get <id> | Get full thread | - | | gmail thread modify <id> | Modify thread labels | --add-labels, --remove-labels | | gmail labels list | List all labels | - | | gmail labels get <name> | Get label details | - | | gmail labels modify <ids> | Bulk modify labels | --add, --remove | | gmail attachment <msgId> <attId> | Download attachment | - | | gmail url <threadId> | Get Gmail web URL | - | | gmail batch delete <ids> | Bulk delete | - | | gmail drafts list | List drafts | - | | gmail drafts create | Create draft | Same flags as send |

Calendar Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | calendar calendars | List calendars | - | | calendar events [calId] | List events | --from, --to, --today, --week, --all | | calendar event <calId> <eventId> | Get event details | - | | calendar create <calId> | Create event | --summary, --from, --to, --attendees, --with-meet | | calendar update <calId> <eventId> | Update event | Same as create | | calendar delete <calId> <eventId> | Delete event | - | | calendar freebusy <calendars> | Check availability | --from, --to | | calendar conflicts | Find conflicts | --week, --days | | calendar search <query> | Search events | - | | calendar respond <calId> <eventId> | RSVP | --status=accepted\|declined\|tentative | | calendar focus-time | Create focus block | --from, --to | | calendar out-of-office | Set OOO | --from, --to | | calendar working-location | Set work location | --from, --to, --type | | calendar team <groupEmail> | View team calendars | - |

Drive Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | drive ls | List files | --parent | | drive search <query> | Full-text search | --max | | drive get <fileId> | Get file metadata | - | | drive download <fileId> | Download file | --output | | drive upload <path> | Upload file | --name, --parent | | drive mkdir <name> | Create folder | --parent | | drive delete <fileId> | Delete (trash) | - | | drive move <fileId> | Move file | --parent | | drive rename <fileId> <name> | Rename file | - | | drive share <fileId> | Share file | --role, --type, --email | | drive unshare <fileId> <permId> | Remove permission | - | | drive permissions <fileId> | List permissions | - | | drive url <fileId> | Get web URL | - | | drive copy <fileId> <name> | Copy file | - |

Sheets Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | sheets get <id> <range> | Read values | - | | sheets update <id> <range> [vals] | Update values | --input=RAW\|USER_ENTERED | | sheets append <id> <range> [vals] | Append row | --input | | sheets clear <id> <range> | Clear values | - | | sheets metadata <id> | Get spreadsheet info | - | | sheets create <title> | Create spreadsheet | - | | sheets copy <id> <title> | Copy spreadsheet | - | | sheets export <id> | Export | --format=pdf\|xlsx\|csv |

Docs Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | docs cat <docId> | Print as plain text | - | | docs export <docId> | Export document | --format=pdf\|docx\|txt | | docs info <docId> | Get metadata | - | | docs create <title> | Create document | - | | docs copy <docId> <title> | Copy document | - |

Slides Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | slides export <id> | Export presentation | --format=pdf\|pptx | | slides info <id> | Get metadata | - | | slides create <title> | Create presentation | - | | slides copy <id> <title> | Copy presentation | - |

Tasks Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | tasks lists list | List task lists | - | | tasks list <listId> | List tasks | --due-min, --due-max, --show-completed | | tasks add <listId> | Add task | --title, --due, --notes | | tasks update <listId> <taskId> | Update task | Same as add | | tasks done <listId> <taskId> | Mark complete | - | | tasks undo <listId> <taskId> | Mark incomplete | - | | tasks delete <listId> <taskId> | Delete task | - | | tasks clear <listId> | Clear completed | - |

Contacts Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | contacts search <query> | Search contacts | - | | contacts list | List all contacts | --max | | contacts get <resourceName> | Get contact | - | | contacts create | Create contact | --given, --family, --email, --phone | | contacts update <resourceName> | Update contact | Same as create | | contacts delete <resourceName> | Delete contact | - | | contacts directory search | Search directory | - |

Groups Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | groups list | List your groups | - | | groups members <groupEmail> | List group members | - |

People Commands

| Command | Description | Key Flags | |---------|-------------|-----------| | people me | Show your profile | - |

Global Flags

All gog commands support these flags:

| Flag | Description | |------|-------------| | --json | Output JSON (best for scripting/piping to jq) | | --plain | TSV output, no colors (for scripts/parsing) | | --account=EMAIL | Use specific account (multi-account support) | | --force | Skip confirmation prompts | | --no-input | Never prompt, fail instead (CI/automation) | | --verbose | Detailed logging for debugging | | --color=<auto\|always\|never> | Control color output |

Multi-Account Usage

# Use specific account for a command
gog gmail search "is:unread" [email protected]

# List available accounts
gog auth list

JSON Output for Scripting

# Get unread count for inbox
gog gmail labels get INBOX --json | jq '.messagesUnread'

# Extract event IDs from today
gog calendar events --today --json | jq '.[].id'

# List file IDs from search
gog drive search "budget" --json | jq '.[].id'

# Process email subjects
gog gmail search "is:unread" --json | jq '.[].snippet'

Best Practices

Efficient Searching

1. Start narrow, then broaden - Begin with specific queries, add filters if too many results
2. Use date filters - newer_than: reduces noise dramatically
3. Combine operators - is:unread from:boss newer_than:7d is better than browsing
4. Use --max - Limit results when exploring: --max=10

Calendar Management

1. Always check freebusy before scheduling meetings with others
2. Use --with-meet for remote meetings to auto-create video link
3. Set reminders - --reminder="popup:15m" for important meetings
4. Block focus time proactively to protect deep work

Drive Organization

1. Use folder IDs - Store frequently-used folder IDs for quick access
2. Search by content - fullText contains finds docs even if filename is unclear
3. Filter by MIME type - Narrow to specific doc types
4. Export early - Download important docs as PDF for offline access

Automation Tips

1. Use --json for scripting - Parse with jq
2. Use --plain for simple scripts - Tab-separated, no colors
3. Use --no-input in CI - Prevents hangs on prompts
4. Store IDs - Calendar, folder, and task list IDs for reuse

Reference Files

• Gmail Search Syntax - Complete query operator reference
• Drive Search Syntax - Complete Drive query reference
• Calendar Scheduling - Event creation, time formats, RRULE
• Common Workflows - Extended PA/CoS workflow recipes